¶ 通过 SDK 接入 MFA
¶ 概述
Authing 不仅可以通过控制台来配置 MFA 认证流程，你还可以通过 SDK 的方式为 Authing 的 MFA 认证流程进行定制化开发。
本文将以 Authing - Node/JavaScript SDK 为例，指引用户完成基于 SDK 的 MFA 自定义开发。
其中包含：绑定 MFA 认证器、解绑 MFA 认证器、用户二次认证等。
¶ 准备工作
¶ 多因素认证（MFA）API
¶ 查询用户开启的 MFA 信息
查询用户开启的 MFA 信息
返回用户开启的 MFA 信息
¶ 请求绑定 MFA 口令
获取 MFA 二维码以及 Secret 信息，用于展示，等待用户确认绑定。
请求此接口后，用户确认绑定之前，MFA 二次认证不会生效。接口返回 MFA Secret、MFA Uri、MFA 二维码 Data Url，恢复代码。
¶ 确认绑定 MFA 口令
确认绑定 MFA。
请求此接口后，用户确认绑定 MFA，之后登录会要求输入二次验证 MFA 口令。
¶ 一次认证后返回 MFA Token
调用 authing-js-sdk 中的登录方法，参考登录。或者直接调用 GraphQL 接口。你需要存储 mfaToken 以备后续使用。
调用 SDK 的处理方式：
try {
window.user = await window.authing.login({ email, password })
alert(`登录成功，信息：${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)
}
直接调用 GraphQL 接口的返回信息：
{
"errors": [
{
"message": {
"code": 1635,
"message": "请输入二次认证安全码",
"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 }
}
¶ 登录验证 MFA 口令
用于登录时一次认证成功后，检验二次认证口令是否正确。
对于开启二次认证的用户，第一次认证成功后会返回一个 mfaToken，需要携带 mfaToken 请求本接口完成二次认证。
¶ 使用恢复代码
用于用户登录一次认证成功后，丢失 MFA 口令时恢复账号访问。
如果用户开启了二次认证而丢失了 MFA 口令，需要使用恢复代码来恢复账号的访问。使用恢复代码等效于使用 MFA 口令，使用过后会为用户生成新的恢复代码。用户可以在登录后解绑 MFA 并重新绑定新的 MFA。
¶ 解绑 MFA
解绑 MFA 认证器
请求此接口后，会解绑 MFA，之后登录无需 TOTP MFA 二次认证。
¶ 运行方法
- 双击打开 ‘index.html’ 文件，或在项目目录启动一个 http 服务器。
$ npm install -g http-server
$ http-server
- 然后访问 127.0.0.1:8080。
你可以参考 Authing 提供的 MFA Demo (opens new window)。
¶ 多因素认证（MFA）SDK
¶ 请求绑定 MFA 认证器
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',
})
¶ 验证 MFA 二次口令
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',
})
¶ 获取 MFA 认证器
MfaAuthenticationClient().getMfaAuthenticators()
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'AUTHING_APP_ID',
appHost: 'https://xxx.authing.cn',
})
const authenticators = await authenticationClient.mfa.getMfaAuthenticators({
type: 'totp',
})
¶ 返回值
Promise<IMfaAuthenticators>
¶ 请求 MFA 二维码和密钥信息
MfaAuthenticationClient().assosicateMfaAuthenticator()
请求 MFA 二维码和密钥信息
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'AUTHING_APP_ID',
appHost: 'https://xxx.authing.cn',
})
const authenticators = await authenticationClient.mfa.assosicateMfaAuthenticator(
{ authenticatorType: 'totp' }
)
¶ 返回值
Promise<IMfaAssociation>
¶ 解绑 MFA
MfaAuthenticationClient().deleteMfaAuthenticator()
解绑 MFA
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'AUTHING_APP_ID',
appHost: 'https://xxx.authing.cn',
})
const authenticators = await authenticationClient.mfa.deleteMfaAuthenticator()
¶ 返回值
Promise<IMfaDeleteAssociation>
¶ 确认绑定 MFA
MfaAuthenticationClient().confirmAssosicateMfaAuthenticator()
确认绑定 MFA
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'AUTHING_APP_ID',
appHost: 'https://xxx.authing.cn',
})
const authenticators = await authenticationClient.mfa.confirmAssosicateMfaAuthenticator(
{ authenticatorType: 'totp', totp: '112233' }
)
¶ 返回值
Promise<IMfaConfirmAssociation>
¶ 检验二次验证 MFA 口令
MfaAuthenticationClient().verifyTotpMfa()
检验二次验证 MFA 口令
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'AUTHING_APP_ID',
appHost: 'https://xxx.authing.cn',
})
const authenticators = await authenticationClient.mfa.verifyTotpMfa({
authenticatorType: 'totp',
totp: '112233',
})
¶ 返回值
¶ 检验二次验证 MFA 短信验证码
MfaAuthenticationClient().verifyAppSmsMfa()
¶ 参数
options<Object>options.phone<string> 用户手机号。options.code<string> 手机验证码。options.mfaToken<string> 登录接口返回的 mfaToken。
¶ 示例
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',
})
¶ 返回值
¶ 检验二次验证 MFA 邮箱验证码
MfaAuthenticationClient().verifyAppEmailMfa()
¶ 参数
options<Object>options.email<string> 用户邮箱。options.code<string> 手机验证码。options.mfaToken<string> 登录接口返回的 mfaToken。
¶ 示例
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',
})
¶ 返回值
¶ 检测手机号或邮箱是否已被绑定
MfaAuthenticationClient().phoneOrEmailBindable()
当需要手机或邮箱 MFA 登录，而用户未绑定手机或邮箱时，可先让用户输入手机号或邮箱，用此接口先检测手机或邮箱是否可绑定，再进行 MFA 验证
¶ 参数
options<Object>[options.email]<string> 要检测的邮箱。[options.phone]<string> 要检测的手机号。options.mfaToken<string> 登录接口返回的 mfaToken。
¶ 示例
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}}',
})
¶ 返回值
Promise<boolean>
¶ 检验二次验证 MFA 恢复代码
MfaAuthenticationClient().verifyTotpRecoveryCode()
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'AUTHING_APP_ID',
appHost: 'https://xxx.authing.cn',
})
const authenticators = await authenticationClient.mfa.verifyTotpRecoveryCode({
authenticatorType: 'totp',
totp: '112233',
})