- 开发集成
- /
- JavaScript / Node.js
- /
- 用户认证模块
- /
- 认证核心模块
¶ 认证核心模块
此模块包含注册登录、重置手机号邮箱、修改账号信息等方法,是以你的终端用户(End User)的身份进行请求,适合在需要验证用户身份的情况下使用。如果你倾向于以管理员的身份管理用户,请使用 UsersManagementClient - 用户管理模块。
import { AuthenticationClient } from 'authing-js-sdk'
const authenticationClient = new AuthenticationClient({
appId: 'YOUR_APP_ID',
appHost: 'https://xxx.authing.cn',
})
authenticationClient.registerByEmail // 使用邮箱注册
authenticationClient.loginByEmail // 使用邮箱登录
¶ 使用邮箱注册
AuthenticationClient().registerByEmail(email, password, profile, options)
使用邮箱注册,邮箱不区分大小写且用户池内唯一。此接口不要求用户对邮箱进行验证,用户注册之后 emailVerified 字段会为 false 。如果你希望邮箱未验证的用户不能进行登录,可以在用户池的设置 - 安全信息 中开启禁止未验证邮箱的用户登录选项:
¶ 参数
email
<string> 邮箱password
<string> 密码profile
<RegisterProfile> 用户资料options
<object>options.forceLogin
<boolean> 是否走一遍完整的登录的,会触发登录前后的 pipeline 函数以及登录事件 webhook ,同时该用户的累计登录次数会加 1 。默认为 false 。options.clientIp
<string> 客户端真实 IP,如果你在服务器端调用此接口,请务必将此参数设置为终端用户的真实 IP。options.customData
<object> 用户自定义数据,你需要先在用户池定义用户自定义数据元信息,且传入值的类型必须和定义的类型匹配。options.context
<object> 请求上下文,这里设置的context
可以在 pipeline 的 context 中获取到。
¶ 示例
- 使用邮箱密码注册
authenticationClient.registerByEmail('test@example.com', 'passw0rd')
- 注册的同时设置用户信息(昵称和公司)
authenticationClient.registerByEmail(
'test@example.com',
'passw0rd',
{
nickname: 'Nick',
company: '蒸汽记忆'
},
)
- 注册的同时添加设置自定义数据,你需要先给用户定义一个
source
自定义字段。
authenticationClient.registerByEmail(
'test@example.com',
'passw0rd',
null,
{
customData: {
source: 'google'
}
}
)
¶ 返回值
¶ 使用用户名注册
AuthenticationClient().registerByUsername(username, password, profile, options)
使用用户名注册,用户名区分大小写且用户池内唯一。
¶ 参数
username
<string> 用户名password
<string> 密码profile
<RegisterProfile> 用户资料options
<object>options.forceLogin
<boolean> 是否走一遍完整的登录的,会触发登录前后的 pipeline 函数以及登录事件 webhook ,同时该用户的累计登录次数会加 1 。默认为 false 。options.clientIp
<string> 客户端真实 IP,如果你在服务器端调用此接口,请务必将此参数设置为终端用户的真实 IP。options.customData
<object> 用户自定义数据,你需要先在用户池定义用户自定义数据元信息,且传入值的类型必须和定义的类型匹配。options.context
<object> 请求上下文,这里设置的context
可以在 pipeline 的 context 中获取到。
¶ 示例
- 使用用户名密码注册
authenticationClient.registerByUsername('bob', 'passw0rd')
- 注册的同时设置用户信息(昵称和公司)
authenticationClient.registerByUsername(
'bob',
'passw0rd',
{
nickname: 'Nick',
company: '蒸汽记忆'
},
)
- 注册的同时添加设置自定义数据,你需要先给用户定义一个
source
自定义字段。
authenticationClient.registerByUsername(
'bob',
'passw0rd',
null,
{
customData: {
source: 'google'
}
}
)
¶ 返回值
¶ 使用手机号注册
AuthenticationClient().registerByPhoneCode(phone, code, password, profile, options)
使用手机号注册,你可以同时设置该账号的初始密码。你可以通过 sendSmsCode 方法发送短信验证码。
¶ 参数
phone
<string> 手机号code
<string> 短信验证码password
<string> 初始密码profile
<RegisterProfile> 用户资料options
<object>options.forceLogin
<boolean> 是否走一遍完整的登录的,会触发登录前后的 pipeline 函数以及登录事件 webhook ,同时该用户的累计登录次数会加 1 。默认为 false 。options.clientIp
<string> 客户端真实 IP,如果你在服务器端调用此接口,请务必将此参数设置为终端用户的真实 IP。options.customData
<object> 用户自定义数据,你需要先在用户池定义用户自定义数据元信息,且传入值的类型必须和定义的类型匹配。options.context
<object> 请求上下文,这里设置的context
可以在 pipeline 的 context 中获取到。options.phoneCountryCode
<string> 国际区号,例:+1 。 注意区号格式;
¶ 示例
- 使用手机号验证码注册
authenticationClient.registerByPhoneCode('176xxxx6754', '1234')
// 国外号码
authenticationClient.registerByPhoneCode(
'788xxxx637',
'1234',
null,
null,
{
phoneCountryCode: '+44'
}
);
- 注册的同时设置密码
authenticationClient.registerByPhoneCode(
'176xxxx6754',
'1234',
'passw0rd',
{
nickname: 'Nick',
company: '蒸汽记忆'
}
)
- 注册的同时设置用户资料(昵称和公司)
authenticationClient.registerByPhoneCode(
'176xxxx6754',
'1234',
null,
{
nickname: 'Nick',
company: '蒸汽记忆'
}
)
- 注册的同时添加设置自定义数据,你需要先给用户定义一个
source
自定义字段。
authenticationClient.registerByPhoneCode(
'176xxxx6754',
'1234',
null,
null,
{
customData: {
source: 'google'
}
}
)
¶ 返回值
¶ 使用邮箱登录
AuthenticationClient().loginByEmail(email, password, options)
使用邮箱登录,该接口默认不会限制未验证的邮箱进行登录,如果你希望邮箱未验证的用户不能进行登录,如果你希望邮箱未验证的用户不能进行登录,可以在用户池的设置 - 安全信息 中开启禁止未验证邮箱的用户登录选项:
如果你的用户池配置了登录失败检测,当同一 IP 下登录多次失败的时候会要求用户输入图形验证码(code 为 2000)。
¶ 参数
email
<string> 邮箱password
<string> 密码options
<object>options.autoRegister
<boolean> 是否自动注册。如果检测到用户不存在,会根据登录账密自动创建一个账号。options.captchaCode
<string> 图形验证码options.clientIp
<string> 客户端真实 IP,如果你在服务器端调用此接口,请务必将此参数设置为终端用户的真实 IP。options.customData
<object> 用户自定义数据,你需要先在用户池定义用户自定义数据元信息,且传入值的类型必须和定义的类型匹配。options.context
<object> 请求上下文,这里设置的context
可以在 pipeline 的 context 中获取到。
¶ 示例
- 使用邮箱密码登录
authenticationClient.loginByEmail('test@example.com', 'passw0rd')
- 屡次登录失败,当需要输入图形验证码时
try {
await authenticationClient.loginByEmail('test@example.com', 'passw0rd')
} catch (error) {
const { code, message } = error
if (code === 2000) {
await authenticationClient.loginByEmail('test@example.com', 'passw0rd', {
captchaCode: 'xj72',
})
}
}
- 登录的同时设置自定义字段
authenticationClient.loginByEmail(
'test@example.com',
'passw0rd',
{
customData: {
source: 'google'
}
}
)
¶ 返回值
¶ 使用用户名登录
AuthenticationClient().loginByUsername(username, password, options)
使用用户名登录。如果你的用户池开启了登录失败检测,当同一 IP 下登录多次失败的时候会要求用户输入图形验证码(错误码 为 2000)。
¶ 参数
username
<string> 用户名password
<string> 密码options
<object>options.autoRegister
<boolean> 是否自动注册。如果检测到用户不存在,会根据登录账密自动创建一个账号。options.captchaCode
<string> 图形验证码options.clientIp
<string> 客户端真实 IP,如果你在服务器端调用此接口,请务必将此参数设置为终端用户的真实 IP。options.customData
<object> 用户自定义数据,你需要先在用户池定义用户自定义数据元信息,且传入值的类型必须和定义的类型匹配。options.context
<object> 请求上下文,这里设置的context
可以在 pipeline 的 context 中获取到。
¶ 示例
- 使用用户名、密码登录
authenticationClient.loginByUsername('test', 'passw0rd')
- 屡次登录失败,当需要输入图形验证码时
try {
await authenticationClient.loginByUsername('test', 'passw0rd')
} catch (error) {
const { code, message } = error
if (code === 2000) {
await authenticationClient.loginByUsername(
'test',
'passw0rd',
{
captchaCode: 'xj72'
}
)
}
}
- 登录的同时设置自定义字段
authenticationClient.loginByUsername(
'test',
'passw0rd',
{
customData: {
source: 'google'
}
}
)
¶ 返回值
¶ 使用手机号验证码登录
AuthenticationClient().loginByPhoneCode(phone, code)
使用手机号验证码登录。你需要先使用 sendSmsCode 方法发送短信验证码。
¶ 参数
phone
<string> 手机号;code
<string> 短信验证码,你可以通过 sendSmsCode 方法发送短信验证码;options.clientIp
<string> 客户端真实 IP,如果你在服务器端调用此接口,请务必将此参数设置为终端用户的真实 IP。options.customData
<object> 用户自定义数据,你需要先在用户池定义用户自定义数据元信息,且传入值的类型必须和定义的类型匹配。options.context
<object> 请求上下文,这里设置的context
可以在 pipeline 的 context 中获取到。options.phoneCountryCode
<string> 国际区号,例:+1 。 注意区号格式;
¶ 示例
- 使用手机号验证码登录
authenticationClient.loginByPhoneCode('176xxxx6754', '1234')
// 国外号码
authenticationClient.loginByPhoneCode("788xxxx637", "1234", { phoneCountryCode: '+44' });
- 登录的同时传递终端用户的真实 IP 地址(纯在后端与 Authing 交互的场景)
authenticationClient.loginByPhoneCode('176xxxx6754', '1234', {
clientIp: '1.1.1.1'
})
- 登录的同时设置自定义数据
authenticationClient.loginByPhoneCode(
'176xxxx6754',
'1234',
{
customData: {
source: 'google'
}
}
)
¶ 返回值
¶ 使用手机号密码登录
AuthenticationClient().loginByPhonePassword(phone, password, options)
如果用户绑定了手机号且设置了密码,可以使用手机号 + 密码的方式登录。如果你的用户池开启了登录失败检测,当同一 IP 下登录多次失败的时候会要求用户输入图形验证码(错误码 为 2000)。
¶ 参数
phone
<string> 手机号password
<string> 密码options
<object>options.captchaCode
<string> 图形验证码options.clientIp
<string> 客户端真实 IP,如果你在服务器端调用此接口,请务必将此参数设置为终端用户的真实 IP。options.customData
<object> 用户自定义数据,你需要先在用户池定义用户自定义数据元信息,且传入值的类型必须和定义的类型匹配。options.context
<object> 请求上下文,这里设置的context
可以在 pipeline 的 context 中获取到。
¶ 示例
- 使用手机号密码登录
authenticationClient.loginByPhonePassword('176xxxx6754', 'passw0rd')
- 屡次登录失败,当需要输入图形验证码时
try {
await authenticationClient.loginByPhonePassword('176xxxx6754', 'passw0rd')
} catch (error) {
const { code, message } = error
if (code === 2000) {
await authenticationClient.loginByPhonePassword('176xxxx6754', 'passw0rd', {
captchaCode: 'xj72',
})
}
}
- 登录的同时设置自定义数据
authenticationClient.loginByPhonePassword('176xxxx6754', 'passw0rd', {
customData: {
source: 'google'
},
})
¶ 返回值
¶ 使用子账户登录
AuthenticationClient().loginBySubAccount(account, password, options)
使用子账户登录。
¶ 参数
username
<string> 用户名password
<string> 密码options
<object> 配置对象,可选参数。options.captchaCode
<string> 图形验证码options.clientIp
<string> 客户端真实 IP,如果你在服务器端调用此接口,请务必将此参数设置为终端用户的真实 IP。
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
})
authenticationClient.loginBySubAccount('admin', 'admin')
¶ 使用 LDAP 用户名登录
AuthenticationClient().loginByLdap(username, password)
使用 LDAP 身份源的账号密码登录。如果此账号第一次登录,将会将其用户信息导入到用户池的用户目录中;之后再次登录,将会根据获取到的最新的账号资料更新此账号的用户信息。
点此查看连接 LDAP 身份源文档。
¶ 参数
username
<string> 用户名password
<string> 密码
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
})
authenticationClient.loginByLdap('admin', 'admin')
¶ 返回值
¶ 使用 AD 用户名登录
AuthenticationClient().loginByAd(username, password)
使用 AD 域的账号登录。如果此账号第一次登录,将会将其用户信息导入到用户池的用户目录中;之后再次登录,将会根据获取到的最新的账号资料更新此账号的用户信息。
点此查看连接 Active Directory 身份源文档。
¶ 参数
username
<string> 用户名password
<string> 密码
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
})
authenticationClient.loginByAd('admin', 'admin')
¶ 返回值
¶ 获取当前登录的用户信息
AuthenticationClient().getCurrentUser()
获取当前登录用户的用户信息,需要 AuthenticationClient 当前处于已登录状态才能获取到。你可以通过两种方式设置 AuthenticationClient 的登录状态:
- 调用登录接口(如密码登录、手机号验证码登录、社会化登录)之后,AuthenticationClient 会缓存用户的 id_token,从而记住登录状态;
- 通过用户的 id_token 初始化 AuthenticationClient。
¶ 示例
- 调用登录接口之后获取用户信息
const { AuthenticationClient } = require('authing-js-sdk')
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
})
authenticationClient.loginByUsername('bob', 'passw0rd').then(() => {
authenticationClient.getCurrentUser().then(user => {
console.log(user)
})
})
- 通过用户的 id_token 初始化之后获取用户信息
const { AuthenticationClient } = require('authing-js-sdk')
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
token: 'ID_TOKEN'
})
authenticationClient.getCurrentUser().then(user => {
console.log(user)
})
¶ 返回值
¶ 退出登录
AuthenticationClient().logout()
用于用户退出登录。
如果在前端浏览器环境下使用,会执行以下操作:
- 清空 localStorage 中保存的的用户信息和用户的
id_token
; - 清空用户在 appHost 域名下的 session;
- 将用户当前的
id_token
标记为已失效,使用此id_token
将调用 Authing 接口无法获取到相关数据。
如果在后端服务器环境下使用,会执行以下操作:
- 清空该用户在当前应用下的 session 会话信息;
- 将用户当前的
id_token
标记为已失效,使用此id_token
将调用 Authing 接口无法获取到相关数据。
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
token: 'ID_TOKEN'
})
authenticationClient.logout()
¶ 发送短信验证码
AuthenticationClient().sendSmsCode(phone)
发送短信验证码, 支持国内外手机号;该接口有接口频率限制,请勿频繁请求。
¶ 参数
phone
<string>phoneCountryCode
<string> 国际区号,例:+1 。 注意区号格式;
¶ 示例
authenticationClient.sendSmsCode('176xxxx6754')
// 发国际短信
authenticationClient.sendSmsCode("788xxxx637", "+44")
¶ 返回值
Promise<CommonMessage>
¶ 发送邮件
AuthenticationClient().sendEmail(email, scene)
主动发送邮件给用户,目前支持的 4 类邮件包含:重置密码邮件、验证邮箱邮件、修改邮箱验证码邮件、MFA 验证邮件。同时你可以自定义邮件模版和配置第三方邮件服务商。
¶ 参数
email
<string> 邮箱scene
<EmailScene> 发送场景,可选值包含:- RESET_PASSWORD: 发送重置密码邮件,邮件中包含验证码;
- VERIFY_EMAIL: 发送验证邮箱的邮件;
- CHANGE_EMAIL: 发送修改邮箱邮件,邮件中包含验证码;
- MFA_VERIFY: 发送 MFA 验证邮件。
¶ 示例
- 发送重置密码邮件,会将包含验证码的邮件发送到用户的邮箱
import { EmailScene } from 'authing-js-sdk'
authenticationClient.sendEmail('test@example.com', EmailScene.ResetPassword)
- 之后用户可以使用邮箱验证码重置密码
authenticationClient.resetPasswordByEmailCode(
'test@example.com',
'1234',
'newPassw0rd'
)
¶ 检查密码强度
AuthenticationClient().checkPasswordStrength(password)
判断密码是否符合密码强度要求。Authing 中密码强度等级分为以下几种:
- 任意非空字符串;
- 至少 6 位字符;
- 至少 6 位字符,且须包含英文、数字与符号中的两种;
- 至少 6 位字符,且密码中须包含英文、数字与符号。
默认为任意非空字符,你可以在此 配置用户池的密码强度等级。
¶ 参数
password
<string> 明文密码。
¶ 示例
authenticationClient.checkPasswordStrength('weak')
authenticationClient.checkPasswordStrength('strongPassw0rd!')
¶ 示例数据
- 满足密码强度要求
{
"valid": true,
"message": "密码检验成功"
}
- 不满足密码强度要求
{
"valid": false,
"message": "请使用至少 6 位字符作为密码,须包含英文、数字与符号中的两种"
}
¶ 获取自定义数据
AuthenticationClient().getUdfValue()
获取用户的所有自定义数据。你需要先在用户池定义用户自定义数据元信息。
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
token: 'ID_TOKEN', // 使用用户的 token 初始化 SDK
})
const data = await authenticationClient.getUdfValue()
¶ 示例数据
{
"school": "华中科技大学",
"age": 20
}
¶ 设置自定义数据
AuthenticationClient().setUdfValue(data)
设置用户的自定义字段。你需要先在用户池定义用户自定义数据元信息,且传入值的类型必须和定义的类型匹配。如果设置失败,会抛出异常,你需要对异常进行捕捉。
¶ 参数
data
<string> 输入数据,类型为一个对象,详情请见示例。
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
token: 'ID_TOKEN', // 使用用户的 token 初始化 SDK
})
await authenticationClient.setUdfValue({
school: '华中科技大学',
age: 20,
})
¶ 删除自定义数据
AuthenticationClient().removeUdfValue(key)
删除用户的某一个自定义数据。
¶ 参数
key
<string> 自定义字段的 key 。
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
token: 'ID_TOKEN', // 使用用户的 token 初始化 SDK
})
await authenticationClient.removeUdfValue('school')
¶ 检测 Token 登录状态
AuthenticationClient().checkLoginStatus(token)
检测用户 id_token 的登录状态。
¶ 参数
token
<string> 用户的登录凭证 token
¶ 示例
const data = await authenticationClient.checkLoginStatus('TOKEN')
¶ 示例数据
- 成功示例
{
"code": 200,
"message": "已登录",
"status": true,
"exp": 1620732833,
"iat": 1619523233,
}
- 失败示例
{
"code": 2206,
"message": "登录信息已过期",
"status": false,
"exp": null,
"iat": null,
}
¶ 上传头像
AuthenticationClient().uploadAvatar(options)
该方法会自动打开浏览器文件上传框(支持上传的文件格式为 image/*
),并自动完成图片文件上传 CDN、修改用户头像操作。
如果你需要使用自己的图片存储服务,或者图片已经上传好了,请使用 updateProfile
方法,如:
authenticationClient.updateProfile({
photo: 'https://ui-avatars.com/api/?background=0D8ABC&color=fff&name=bob'
})
¶ 参数
- options.accept: 支持的图片格式,默认为
image/*
¶ 代码示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
token: 'ID_TOKEN', // 使用用户的 token 初始化 SDK
})
const user = await authing.uploadAvatar()
// 仅选择 png 格式的图片
const user = await authing.uploadAvatar({
accept: '.png'
})
¶ 演示示例
¶ 返回值
该方法会返回用户最新的个人信息。
¶ 通过短信验证码重置密码
AuthenticationClient().resetPasswordByPhoneCode(phone, code, newPassword)
通过短信验证码重置密码,你可以通过 sendSmsCode 方法发送短信验证码。
¶ 参数
phone
<string> 手机号code
<string> 验证码newPassword
<string> 新的密码phoneCountryCode
<string> 国际区号 列: '+44'
¶ 示例
authenticationClient.resetPasswordByPhoneCode('176xxxx6754', '1234', 'passw0rd')
// 国外号码
authenticationClient.resetPasswordByPhoneCode('788xxxx637', '1234', 'passw0rd', '+44')
¶ 返回值
Promise<CommonMessage>
¶ 通过邮件验证码重置密码
AuthenticationClient().resetPasswordByEmailCode(email, code, newPassword)
通过邮件验证码重置密码,你需要先调用 sendEmail 接口发送重置密码邮件(场景值为 RESET_PASSWORD
)。
¶ 参数
email
<string> 邮箱code
<string> 验证码newPassword
<string> 新的密码
¶ 示例
import { EmailScene } from 'authing-js-sdk'
// 1. 发送邮件验证码
authenticationClient.sendEmail('test@example.com', EmailScene.ResetPassword)
// 2. 通过邮件验证码发送验证邮件
authenticationClient.resetPasswordByEmailCode(
'test@example.com',
'1234',
'passw0rd'
)
¶ 返回值
Promise<CommonMessage>
¶ 修改用户资料
AuthenticationClient().updateProfile(updates)
修改用户资料,此接口不能用于修改手机号、邮箱、密码,如果需要请调用 updatePhone、updateEmail、updatePassword 接口。
¶ 参数
updates
<UpdateUserInput> 修改的用户资料updates.username
<string> 用户名updates.nickname
<string> 昵称updates.photo
<string> 头像updates.company
<string> 公司updates.browser
<string> 浏览器updates.device
<string> 设备updates.lastIP
<string> 最近登录的 IPupdates.name
<string> Nameupdates.givenName
<string> Given Nameupdates.familyName
<string> Family Nameupdates.middleName
<string> Middle Nameupdates.profile
<string> Profile Urlupdates.preferredUsername
<string> Preferred Nameupdates.website
<string> 个人网站updates.gender
<string> 性别, F 表示男性、W 表示女性、未知表示 Uupdates.birthdate
<string> 生日updates.zoneinfo
<string> 时区updates.locale
<string> 语言updates.address
<string> 地址updates.streetAddress
<string> 街道地址updates.locality
<string>updates.region
<string> 地域updates.postalCode
<string> 邮编updates.city
<string> 城市updates.province
<string> 省份updates.country
<string> 国家
¶ 示例
- 修改昵称和最近登录地址
authenticationClient.updateProfile({
nickname: 'Nick',
lastIp: '111.111.111.111',
})
- 不能直接修改手机号、邮箱、密码,会报错
try {
await authenticationClient.updateProfile({
phone: '176xxxx6754'
})
} catch (error) {
// this will fail, you can't change your phone directly, must verify by phone code
}
¶ 返回值
¶ 更新用户密码
AuthenticationClient().updatePassword(newPassword, oldPassword)
更新用户密码,需要提供原始密码。
¶ 参数
newPassword
<string> 新密码oldPassword
<string> 旧密码,如果用户没有设置密码,可以不填。
¶ 示例
- 由手机号、社会化登录等其他方式注册的,首次没有设置密码,oldPassword 留空
authenticationClient.updatePassword('passw0rd')
- 用户之前设置了密码
authenticationClient.updatePassword('passw0rd', 'oldPassw0rd')
¶ 返回值
¶ 绑定手机号
AuthenticationClient().bindPhone(phone, phoneCode)
用户初次绑定手机号,如果需要修改手机号请使用 updatePhone 方法。如果该手机号已被绑定,将会绑定失败。发送验证码请使用 sendSmsCode 方法。
终端用户也可以在个人中心自助绑定手机号:
¶ 参数
phone
<string> 手机号;phoneCode
<string> 手机号验证码;phoneCountryCode
<string> 国际区号,例:+1 。 注意区号格式;
¶ 示例
authenticationClient.getCurrentUser().then(user => {
if (!user.phone) {
// 1. 第一步:发送短信验证码
authenticationClient.sendSmsCode('176xxxx6754').then(() => {
// 2. 第二步:使用手机号验证码绑定手机号
authenticationClient.bindPhone('176xxxx6754', '1234')
})
/* 国外手机号
* authenticationClient.sendSmsCode('788xxxx637', '+44').then(() => {
* authenticationClient.bindPhone('788xxxx637', '1234', '+44')
* })
*/
}
})
¶ 返回值
该接口会返回最新的用户信息。
¶ 解绑手机号
AuthenticationClient().unbindPhone()
用户解绑手机号,如果用户没有绑定其他登录方式(邮箱、社会化登录账号),将无法解绑手机号,会提示错误。
终端用户也可以在个人中心自助解绑手机号:
¶ 示例
authenticationClient.getCurrentUser().then(user => {
if (user.phone) {
authenticationClient.unbindPhone()
}
})
¶ 返回值
该接口会返回最新的用户信息。
¶ 更新用户手机号
AuthenticationClient().updatePhone(phone, phoneCode, oldPhone, oldPhoneCode, phoneCountryCode, oldPhoneCountryCode)
更新用户手机号。和修改邮箱一样,默认情况下,如果用户当前已经绑定了手机号,需要同时验证原有手机号(目前账号绑定的手机号)和当前邮箱(将要绑定的手机号)。
也就是说,用户 A 当前绑定的手机号为 15888888888,想修改为 15899999999,那么就需要同时验证这两个手机号。
开发者也可以选择不开启 “验证原有手机号“ ,可以在 Authing 控制台的设置目录下的安全信息模块进行关闭。
用户首次绑定手机号请使用 bindPhone 接口。
¶ 参数
phone
<string> 新手机号phoneCode
<string> 新手机号的验证码oldPhone
<string> 旧手机号oldPhoneCode
<string> 旧手机号的验证码phoneCountryCode
<string> 新手机号区号oldPhoneCountryCode
<string> 旧手机号区号
¶ 示例
- 关闭了“验证原有手机号”选项
authenticationClient.updatePhone('176xxxx6754', '1234') // 关闭了“验证原有手机号“选项
// 国际号码
authenticationClient.updatePhone('788xxxx637', '1234', '+44')
- 开启了“验证原有手机号”选项
authenticationClient.updatePhone('176xxxx6754', '1234', '156xxxx9876', '1234') // 开启了“验证原有手机号“选项
// 国际号码
authenticationClient.updatePhone('156xxxx9876', '1234', '788xxxx637', '1234', '+86', '+44')
¶ 返回值
¶ 绑定邮箱
AuthenticationClient().bindEmail(email, emailCode)
用于用户初次绑定邮箱,需检验邮箱验证码。如果需要修改邮箱请使用 updateEmail 方法。如果该邮箱已被绑定,将会绑定失败。发送邮件验证码请使用 sendEmail 方法。
终端用户也可以在个人中心自助绑定邮箱:
¶ 参数
email
<string> 邮箱emailCode
<string> 邮件验证码,可通过 sendEmail 方法获得,EmailScene 为 CHANGE_EMAIL。
¶ 示例
authenticationClient.bindEmail('test@example.com', '1234')
¶ 返回值
¶ 解绑邮箱
AuthenticationClient().unbindEmail(email, emailCode)
用户解绑邮箱,如果用户没有绑定其他登录方式(手机号、社会化登录账号),将无法解绑邮箱,会提示错误。
终端用户也可以在个人中心自助解绑邮箱:
¶ 示例
authenticationClient.getCurrentUser().then(user => {
if (user.email)
authenticationClient.unbindEmail()
}
})
¶ 返回值
¶ 更新用户邮箱
AuthenticationClient().updateEmail(email, emailCode, oldEmail, oldEmailCode)
如果用户已经绑定了邮箱,默认情况下,需要同时验证原有邮箱(目前账号绑定的邮箱)和当前邮箱(将要绑定的邮箱)。也就是说,用户 A 当前绑定的邮箱为 123456@qq.com,想修改为 1234567@qq.com,那么就需要同时验证这两个邮箱。
开发者也可以选择不开启 “验证原有邮箱“ ,可以在 Authing 控制台的设置目录下的安全信息模块进行关闭。
用户首次绑定邮箱请使用 bindEmail 接口。
¶ 参数
email
<string> 新邮箱emailCode
<string> 新邮箱的验证码oldEmail
<string> 旧邮箱oldEmailCode
<string> 旧邮箱的验证码
¶ 示例
- 关闭了“验证原有邮箱”选项
authenticationClient.updateEmail('test@example.com', '1234') // 关闭了“验证原有邮箱“选项
- 开启了“验证原有邮箱”选项
authenticationClient.updateEmail(
'test@example.com',
'1234',
'test2@example.com',
'1234'
) // 开启了“验证原有邮箱“选项
¶ 返回值
¶ 合并账号身份信息
AuthenticationClient().linkAccount(options)
将一个 Authing 子账号的外部身份源(如微信、GitHub、自定义 OIDC 身份源等)身份信息合并到一个 Authing 主账号上,同时删除子账号。
若用户原先使用某一身份源可以登录到子账号,合并之后,用户再用此身份源登录,将登录到主账号。
注意,除来自外部身份源的身份信息外,子账号的一切信息都会在合并后丢失!
¶ 参数
options.primaryUserToken
<string> 主账号 Tokenoptions.secondaryUserToken
<string> 子账号 Token
¶ 示例
authenticationClient.linkAccount({
primaryUserToken: primaryUser.token,
secondaryUserToken: secondaryUser.token,
})
¶ 返回值
{
"code": 200,
"message": "绑定成功"
}
¶ 计算密码安全等级
AuthenticationClient().computedPasswordSecurityLevel()
计算密码安全等级。
¶ 参数
password
: 需要计算的密码(明文格式),必须为string
类型;
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
})
const securityLevel = authenticationClient.computedPasswordSecurityLevel(
'xxxxxxxx'
)
¶ 返回值
返回值有三种情况:
1
: 等级低2
: 等级中3
: 等级高
¶ 获取用户账号安全等级
AuthenticationClient().getSecurityLevel()
获取此账号的账号安全等级。
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
token: 'ID_TOKEN', // 使用用户的 token 初始化 SDK
})
const securityLevel = await authenticationClient.getSecurityLevel()
¶ 示例数据
{
"score": 65,
"email": true,
"phone": false,
"password": true,
"passwordSecurityLevel": 1,
"mfa": false
}
字段释义:
email
: <boolean>,是否绑定了邮箱mfa
: <boolean>,是否绑定了个人 MFApassword
: <boolean>,是否设置了密码phone
: <boolean>,是否绑定了手机号passwordSecurityLevel
: <number | null>,密码安全登录,null
表示还没检测过密码安全等级1
: 低,2
: 中,3
: 高,
score
: <number>,账户安全等级总体评分,最高 100 分
¶ 获取用户被授权的所有资源列表
AuthenticationClient().listAuthorizedResources(namespace,options)
获取一个用户被授权的所有资源,用户被授权的所有资源里面包括从角色、分组、组织机构继承的资源。
¶ 参数
namespace
<string> 权限分组的 code,详情请见使用权限分组管理权限资源。options.resource_type
<string> 资源类型,一共有以下几种资源类型DATA
: 数据类型API
: API 类型数据MENU
: 菜单类型数据
¶ 示例
authenticationClient.users.listAuthorizedResources('namespace_code')
¶ 示例数据
{
"totalCount": 12,
"list": [
{
"code": "menu_a",
"type": "MENU"
},
{
"code": "menu_b",
"type": "MENU"
},
{
"code": "books:1",
"type": "DATA",
"actions": ["books:delete", "books:update"]
}
]
}
¶ 获取当前用户能够访问的应用
AuthenticationClient().listApplications(params)
获取当前用户能够访问的应用。
¶ 参数
page
<number> 分页序号, 默认为1
。limit
<number> 每页返回的个数, 默认为10
。
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
token: 'ID_TOKEN'
})
const { totalCount, list } = authenticationClient.listApplications({
page: 1,
limit: 10,
});
¶ 示例数据
{
"list": [
{
"id": "5f97fb40d352ecf69ffe6d98",
"name": "oo",
"logo": "https://files.authing.co/authing-console/default-app-logo.png",
"domain": "okokiohutuyfrtd",
"description": null,
"createdAt": "2020-10-27T10:49:36.817Z",
"updatedAt": "2021-03-17T10:39:53.650Z",
"protocol": "oidc"
}
],
"totalCount": 1
}
¶ 刷新当前用户的 Token
AuthenticationClient().refreshToken()
刷新当前用户的 Token
¶ 示例
await authing.registerByUsername(username, password, null, {
forceLogin: true
});
const data = await authing.refreshToken();
¶ 示例数据
{
"iat": 1632467937,
"token": "newToken",
"exp": 1633677537
}
¶ 添加自定义数据
AuthenticationClient().setUdv(key,value)
添加自定义数据
¶ 参数
key
<string> 自定义数据 Keyvalue
<string> 自定义数据 Key
¶ 示例
const key = generateRandomString(10);
await managementClient.udf.set(
UdfTargetType.User,
key,
UdfDataType.String,
generateRandomString(5)
);
await authing.setUdv(key, '123');
¶ 示例数据
[{
"dataType": "STRING",
"value": "ucla",
"key": "school",
"label": "学校"
}]
¶ 删除自定义数据
AuthenticationClient().removeUdv(key)
删除自定义数据
¶ 参数
key
<string> 自定义数据 Key
¶ 示例
const key = generateRandomString(10);
await managementClient.udf.set(
UdfTargetType.User,
key,
UdfDataType.String,
generateRandomString(5)
);
await authing.setUdv(key, '123');
await authing.removeUdv(key);
¶ 示例数据
[]
¶ 获取用户所在组织机构
AuthenticationClient().listOrgs()
获取用户所在组织机构
¶ 示例
const authing = new AuthenticationClient({
...getOptionsFromEnv(),
});
await authing.loginByUsername("xxxx","xxx");
const data = await authing.listOrgs();
¶ 示例数据
[]
¶ 判断当前用户是否有某个角色
AuthenticationClient().hasRole(code,namespace)
判断当前用户是否有某个角色
¶ 参数
code
<string> 角色 Codenamespace
<string> 命名空间
¶ 示例
await authing.loginByUsername("xx",password)
const res = await authing.hasRole("code")
¶ 示例数据
boolean
¶ 通过首次登录的 Token 重置密码
AuthenticationClient().resetPasswordByFirstLoginToken(params)
通过首次登录的 Token 重置密码,需要在创建用户时设置“强制用户首次登录时修改密码”
¶ 参数
params
<object>params.token
<string> 首次登录的 Tokenparams.password
<string> 密码
¶ 示例
const result = await authing.resetPasswordByFirstLoginToken({token:'eyJhbG14CTs',password})
¶ 通过密码强制更新临时 Token 修改密码
AuthenticationClient().resetPasswordByForceResetToken(params)
通过密码强制更新临时 Token 修改密码
¶ 参数
params
<object>params.token
<string> 首次登录的 Tokenparams.oldPassword
<string> 旧密码params.newPassword
<string> 新密码
¶ 示例
authentication.resetPasswordByForceResetToken({token:'',oldPassword:'',newPassword:''})
¶ 获取当前用户所有部门
AuthenticationClient().listDepartments()
获取当前用户能够访问的应用。
¶ 参数
¶ 示例
const authenticationClient = new AuthenticationClient({
appId: 'APP_ID',
appHost: 'https://xxx.authing.cn',
token: 'ID_TOKEN'
})
const { departments } = authenticationClient.listDepartments();
¶ 示例数据
{
"departments": {
"totalCount": 1,
"list": [{
"department": {
"code": null,
"description": null,
"updatedAt": "2021-09-16T06:46:11+00:00",
"children": [],
"namePath": ["xx2", "qqqx", "q2"],
"order": null,
"descriptionI18n": null,
"depth": null,
"orgId": "6142c2c41c6e6c6cc3edf",
"path": ["6142c2c4f8abf18c6c978b", "6142c32360021c1a05081579", "6142e833716601219e93d813"],
"nameI18n": null,
"codePath": ["codes", null, null],
"root": false,
"id": "6142e833716601219e93d3",
"createdAt": "2021-09-16T06:46:11+00:00",
"name": "q2"
},
"joinedAt": "2021-09-16T08:48:23+00:00",
"isMainDepartment": false
}]
}
}
¶ 判断用户是否存在
AuthenticationClient().isUserExists(options)
判断用户是否存在
¶ 参数
options
<object>options.user_name
<string> 用户名options.email
<string> 邮箱options.phone
<string> 电话options.externalId
<string> 数据源ID
¶ 示例
const res = await authing.isUserExists({username:"xx"})
¶ 示例数据
boolean
本文是否有解决您的问题?
如果遇到其他问题,你可以在 authing-chat/community 联系我们。