¶ Configure MFA through SDK
¶ Overview
Authing can not only configure the MFA authentication process through the console, but you can also config the MFA authentication through the SDK.
This article will take Authing - Node/JavaScript SDK as an example to guide developers to complete SDK-based MFA custom development. This includes: binding MFA authenticator, unbinding MFA authenticator, user secondary authentication, etc.
¶ Prerequisites
¶ Multi-Factor Authentication (MFA) API
¶ Query the MFA information opened by the user
Query the MFA information opened by the user
Return the MFA information opened by the user
¶ Request to bind MFA password
Obtain the MFA QR code and Secret information for display, and wait for the user to confirm the binding
After requesting this endpoint, the MFA secondary authentication will not take effect before the user confirms the binding. The endpoint returns MFA Secret, MFA Uri, MFA QR code Data Url, and recovery code.
¶ Confirm binding MFA password
Confirm binding MFA
After requesting this endpoint, the user confirms the binding of MFA, and then logs in and asks to enter the MFA password for secondary verification.
¶ Return MFA Token after first authentication
Call the login method in authing-js-sdk, refer to[Login](/sdk/sdk-for-javascript/README.md#Sign in). Or call [GraphQL Interface](/sdk/open-graphql.md#Sign in). You need store mfaToken for future use.
Call the SDK:
try {
window.user = await window.authing.login({ email, password });
alert(`Login successfully, information:${JSON.stringify(window.user)}`);
} catch (err) {
if (err.message.code === 1635) {
console.log(err.message.data.email);
console.log(err.message.data.nickname);
console.log(err.message.data.username);
console.log(err.message.data.avatar);
console.log(err.message.data.mfaToken);
window.mfaToken = err.message.data.mfaToken;
}
alert(err.message.message);
}
The return information of calling the GraphQL interface:
{
"errors": [
{
"message": {
"code": 1635,
"message": "Please enter Secondary Authentication Code",
"data": {
"mfaToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7InVzZXJQb29sSWQiOiI1Y2NlNGFhODNlZDlmOTdiNGRmZDk1ZjAiLCJ1c2VySWQiOiI1ZjhlZTYyY2FmYzJmZmFkMzY0MzQ1YjciLCJhcm4iOiJhcm46Y246YXV0aGluZzo1Y2NlNGFhODNlZDlmOTdiNGRmZDk1ZjA6dXNlcjo1ZjhlZTYyY2FmYzJmZmFkMzY0MzQ1YjciLCJzdGFnZSI6MX0sImlhdCI6MTYwMzIwNjcwOCwiZXhwIjoxNjAzMjA3MDY4fQ.PR7LXqpyH--6sF4eAcOcK1yZBi14lRv_lr9qUtbTQM4",
"nickname": null,
"email": "q3@123.com",
"username": null,
"avatar": "https://usercontents.{{$themeConfig.officeSiteDomain}}/authing-avatar.png"
}
},
"locations": [{ "line": 2, "column": 9 }],
"path": ["login"],
"extensions": { "code": "INTERNAL_SERVER_ERROR" }
}
],
"data": { "login": null }
}
¶ Login to verify MFA password
It is used to check whether the password for the second authentication is correct after the first authentication is successful during login.
For users who enable secondary authentication, an mfaToken will be returned after the first authentication is successful, and the mfaToken needs to be carried to request this endpoint to complete the secondary authentication
¶ Use Recovery Code
It is used to restore account access when the user loses the MFA password after a successful login.
If the user enables the secondary authentication and loses the MFA password, a recovery code is required to restore access to the account. Using the recovery code is equivalent to using the MFA password, and a new recovery code will be generated for the user. The user can unbind the MFA and re-bind the new MFA after logging in.
¶ Operation
Open index.html
Or start a http Server in the project directory
$ npm install -g http-server
$ http-server
Go to 127.0.0.1:8080
You can refer to MFA demo provided by Authing MFA Demo (opens new window)
¶ Multi-Factor Authentication (MFA) SDK
¶ Request to bind MFA authenticator：
import { AuthenticationClient } from "authing-js-sdk";
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
await authenticationClient.mfa.assosicateMfaAuthenticator({
authenticatorType: "totp"
});
¶ Verify MFA secondary password:
import { AuthenticationClient } from "authing-js-sdk";
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
await authenticationClient.mfa.verifyTotpMfa({
totp: "112233",
mfaToken: "xxx"
});
¶ Request an MFA authenticator
MfaAuthenticationClient().getMfaAuthenticators()
Request an MFA authenticator
¶ Sample
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
const authenticators = await authenticationClient.mfa.getMfaAuthenticators({
type: "totp"
});
¶ Return Value
Promise<IMfaAuthenticators>
¶ Request MFA QR code and key
MfaAuthenticationClient().assosicateMfaAuthenticator()
Request MFA QR code and key
¶ Sample
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
const authenticators = await authenticationClient.mfa.assosicateMfaAuthenticator(
{ authenticatorType: "totp" }
);
¶ Return Value
Promise<IMfaAssociation>
¶ Disable MFA
MfaAuthenticationClient().deleteMfaAuthenticator()
Disable MFA
¶ Sample
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
const authenticators = await authenticationClient.mfa.deleteMfaAuthenticator();
¶ Return Value
Promise<IMfaDeleteAssociation>
¶ Confirm binding MFA
MfaAuthenticationClient().confirmAssosicateMfaAuthenticator()
Confirm binding MFA
¶ Sample
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
const authenticators = await authenticationClient.mfa.confirmAssosicateMfaAuthenticator(
{ authenticatorType: "totp", totp: "112233" }
);
¶ Return Value
Promise<IMfaConfirmAssociation>
¶ Verify the MFA password for the second verification
MfaAuthenticationClient().verifyTotpMfa()
Verify the MFA password for the second verification
¶ Sample
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
const authenticators = await authenticationClient.mfa.verifyTotpMfa({
authenticatorType: "totp",
totp: "112233"
});
¶ Return Value
¶ Verify secondary verification MFA SMS verification code
MfaAuthenticationClient().verifyAppSmsMfa()
Verify secondary verification MFA SMS verification code
¶ Reference
options<Object>options.phone<string> Phone numberoptions.code<string> SMS codeoptions.mfaToken<string> MfaToken returned by the login endpoint
¶ Sample
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
const authenticators = await authenticationClient.mfa.verifySmsMfa({
mfaToken: "xxxxxx",
phone: "188xxxx8888",
code: "xxxx"
});
¶ Return Value
¶ Verify secondary verification MFA email verification code
MfaAuthenticationClient().verifyAppEmailMfa()
Verify secondary verification MFA email verification code
¶ Reference
options<Object>options.email<string> Emailoptions.code<string> SMS codeoptions.mfaToken<string> MfaToken returned by the login endpoint
¶ Sample
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
const authenticators = await authenticationClient.mfa.verifyAppEmailMfa({
mfaToken: "xxxxxx",
email: "example@{{$themeConfig.officeSiteDomain}}",
code: "xxxx"
});
¶ Return Value
¶ Check whether the phone number or email has been bound
MfaAuthenticationClient().phoneOrEmailBindable()
When the phone number or email MFA login is required, and the user has not bound the phone number or email, the user can first enter the phone number or email address, use this endpoint to first check whether the mobile phone or email address can be bound, and then perform MFA.
¶ Reference
options<Object>[options.email]<string> Email to be checked[options.phone]<string> Phone number to be checkedoptions.mfaToken<string> MfaToken returned by the login endpoint
¶ Sample
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
const authenticators = await authenticationClient.mfa.phoneOrEmailBindable({
mfaToken: "xxxxxx",
email: "example@{{$themeConfig.officeSiteDomain}}"
});
¶ Return Value
Promise<boolean>
¶ Verify the second verification MFA recovery code
MfaAuthenticationClient().verifyTotpRecoveryCode()
Verify the second verification MFA recovery code
¶ Sample
const authenticationClient = new AuthenticationClient({
appId: "AUTHING_APP_ID",
appHost: "https://xxx.authing.cn"
});
const authenticators = await authenticationClient.mfa.verifyTotpRecoveryCode({
authenticatorType: "totp",
totp: "112233"
});