JavaScript SDK 支持 Angular.js，React.js，Vue.js 以及浏览器原生环境。JavaScript SDK 可用来处理登录、注册等工作，若需要删除用户等敏感操作请使用 SDK for Node.js。

Github：https://github.com/Authing/authing.js。

安装

NPM

当构建大规模应用时，我们推荐使用 npm 进行安装， 它可以与一些模块打包工具很好地配合使用，如 Webpack， Browserify。

# latest stable
$ npm install authing-js-sdk --save

初始化

先从 Authing 控制台 中 获取用户池 ID。

• userPoolId

  • 用户池 ID，可从 Authing 控制台中获取。

示例

const auth = new Authing({
	userPoolId: 'your_userpool_id',
});
// authing.register({...}).then(info => {})
// authing.login({...}).then(info => {})

其他参数

• preflight

  • 是否开启网络状况预检，默认为 false。此参数适用于检查用户的网络是否屏蔽了 authing.cn 这个域名（某些企业的内网会屏蔽这个域名），检查成功不进行任何通知，检查失败后会调用传入的错误处理函数。执行预检之后会导致 SDK 初始化速度变慢，请谨慎使用。

• cdnPreflight

  • 是否开启 CDN 网络状况预检，默认为 false。此参数适用于检查用户的网络是否可以访问七牛云 CDN（某些开了代理的场景下无法访问），检查成功不进行任何通知，检查失败后调用传入的错误处理函数。执行 CDN 预检之后会导致 SDK 初始化速度变慢，请谨慎使用。

• timeout

  • 超时时间，默认为 10000 毫秒（10 秒）。

• onInitError，function(err) {}

  • 错误处理函数，用于处理初始化失败错误、预检错误。

使用

Authing SDK 的所有 API 都支持 Promise。

const Authing = require('authing-js-sdk');
​
const authing = new Authing({
	userPoolId: 'your_userpool_id'
});
​
authing.login({
	email: 'test@testmail.com',
	password: 'testpassword'
}).then(function(user) {
	console.log(user);	
}).catch(function(error) {
	console.log(error);	
});

如果你使用 ES6+ 推荐用 await 处理异步，示例如下：

import Authing from 'authing-js-sdk';
​
const main = async () => {
​
	let auth = new Authing({
		userPoolId: 'your_client_id',
		secret: 'your_app_secret'
	});
​
	let user;
	
	//使用async时需要使用 try...catch... 捕捉错误
	try {
		user = await auth.login({
			email: 'test@testmail.com',
			password: 'testpassword'
		});
	}catch(error) {
		console.log('登录失败:', error);
	}
​
	if(user) {
		console.log('login success');
	}else {
		console.log('login failed');
	}
​
}
​
main();

注册

Authing.register(options)

• 参数:

  • {Object} options

    • email

    • password

    • unionid，若不使用 email 和 password 则 unionid 必选

    • oauth 可选，oauth 信息的字符串，或者其他自定义的用户字段都可以以 JSON 字符串的形式存在这里

    • username，可选，用户名

    • nickname，可选，昵称

    • company，可选，公司名称

    • photo，可选，用户头像

    • lastIP，可选，用户登录的 IP 地址

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_userpool_id'
      });
      
      const userInfo = await authing.register({
        email: email,
        password: password
      }).catch((error) => { ... });;
    })();

• 返回数据:

  • {
        "_id": "59e5ff4935eebf1913cfe8a1",
        "email": "test@test.com",
        "emailVerified": false,
        "username": "test@test.com",
        "nickname": "",
        "company": "",
        "photo": "http://www.xiaohehe.net/uploads/allimg/150305/304-1503051H136.png",
        "browser": "",
        "token": null,
        "tokenExpiredAt": null,
        "loginsCount": 0,
        "lastLogin": "Tue Oct 17 2017 21:02:01 GMT+0800 (CST)",
        "lastIP": null,
        "signedUp": "Tue Oct 17 2017 21:02:01 GMT+0800 (CST)",
        "blocked": false,
        "isDeleted": false,
        "group": {
          "_id": "59e374332023830871913ebd",
          "name": "default",
          "descriptions": "default",
          "createdAt": "Sun Oct 15 2017 22:44:03 GMT+0800 (CST)"
        }
    }

登录

Authing.login(options)

• 参数:

  • {Object} options

    • email

    • password

    • unionid，若不使用 email 和 password 则 unioinid 必选

    • verifyCode，可选，频繁注册时会要求输入验证码，返回数据会包含

    • MFACode，可选，如果用户开启了 MFA 会要求输入 6 位动态口令，返回数据会出现 1635 错误代码

    • lastIP，可选，若连续出现验证码验证失败情况，请将客户端 IP 填入

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_userpool_id'
      });
      
      const userInfo = await authing.login({
        email: email,
        password: password
      }).catch((error) => {
        /* 如果错误信息提示需要输入验证码，则登录参数应为
          { 
            email: email, 
            password: password, 
            verifyCode: verifyCode 
          } 
         /* 
      });
    })();

• 返回数据:

  • {
        "_id": "59e5ff4935eebf1913cfe8a1",
        "email": "86700229ww6ss@163.com",
        "emailVerified": false,
        "username": "86700229ww6ss@163.com",
        "nickname": "",
        "company": "",
        "photo": "http://www.xiaohehe.net/uploads/allimg/150305/304-1503051H136.png",
        "browser": "",
        "token": null,
        "tokenExpiredAt": null,
        "loginsCount": 0,
        "lastLogin": "Tue Oct 17 2017 21:02:01 GMT+0800 (CST)",
        "lastIP": null,
        "signedUp": "Tue Oct 17 2017 21:02:01 GMT+0800 (CST)",
        "blocked": false,
        "isDeleted": false,
        "group": {
          "_id": "59e374332023830871913ebd",
          "name": "default",
          "descriptions": "default",
          "createdAt": "Sun Oct 15 2017 22:44:03 GMT+0800 (CST)"
        }
     }

发送手机验证码

此接口可结合使用手机验证码登录使用。

Authing.getVerificationCode(phone)

• 参数:

  • {String} phone

  • 手机号

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_userpool_id'
      });
      
      const userInfo = await authing.getVerificationCode('phone number')
        .catch((error) => { ... })
    })();

• 返回数据:

  • {
      code: 200, // 500 为失败
      message: '发送成功'
    }

短信模版

【Authing】{S8} 是你的验证码，有效时间为 {S2} 分钟。如非本人操作请忽略。

验证码接口可结合使用手机验证码登录使用。

使用手机验证码登录

Authing.loginByPhoneCode(options)

• 参数:

  • {Object} options

    • phone，必填，手机号

    • phoneCode，必填，使用发送短信接口获取

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_userpool_id'
      });
      
      const userInfo = await authing.loginByPhoneCode({
        phone: 'Your Phone',
        phoneCode: 'Your Phone Code',
      }).catch((error) => { ... })
    })();

• 返回数据:

  • {
        "_id": "59e5ff4935eebf1913cfe8a1",
        "email": "用户邮箱",
        "emailVerified": false,
        "username": "用户名",
        "nickname": "",
        "phone": "用户手机号",
        "company": "",
        "photo": "https://usercontents.authing.cn/client/logo@2.png",
        "browser": "",
        "token": null,
        "tokenExpiredAt": null,
        "loginsCount": 0,
        "lastLogin": "Tue Oct 17 2017 21:02:01 GMT+0800 (CST)",
        "lastIP": null,
        "signedUp": "Tue Oct 17 2017 21:02:01 GMT+0800 (CST)",
        "blocked": false,
        "isDeleted": false,
    }

使用 LDAP 登录

LDAP 服务的配置流程请参考配置 LDAP 服务。

Authing.loginByLDAP(options)

• 参数:

  • {Object} options

    • username，在 LDAP 服务中的登录名，可以是邮箱或用户名

    • password，在 LDAP 服务中的密码

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_userpool_id'
      });
      
      const userInfo = await authing.loginByLDAP({
        username: 'Your LDAP username',
        passowrd: 'Your LDAP password',
      }).catch((error) => { ... })
    })();

• 返回数据:

  • {
      "_id": "5cbe9a4347618069372e75ff",
      "username": "Nikola Tesla",
      "nickname": "Nikola Tesla",
      "oauth": "{\"dn\":\"uid=tesla,dc=example,dc=com\",\"controls\":[],\"objectClass\":[\"inetOrgPerson\",\"organizationalPerson\",\"person\",\"top\",\"posixAccount\"],\"cn\":\"Nikola Tesla\",\"sn\":\"Tesla\",\"uid\":\"tesla\",\"mail\":\"tesla@ldap.forumsys.com\",\"uidNumber\":\"88888\",\"gidNumber\":\"99999\",\"homeDirectory\":\"home\"}",
      "unionid": "uid=tesla,dc=example,dc=com",
      "registerMethod": "ldap:default::from-undefined",
      "email": "tesla@ldap.forumsys.com",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImVtYWlsIjoidGVzbGFAbGRhcC5mb3J1bXN5cy5jb20iLCJ1bmlvbmlkIjoidWlkPXRlc2xhLGRjPWV4YW1wbGUsZGM9Y29tIiwiaWQiOiI1Y2JlOWE0MzQ3NjE4MDY5MzcyZTc1ZmYiLCJjbGllbnRJZCI6IjVjYTQwMjdjOGEzNjJjODIyZTI2ZDA0ZiJ9LCJpYXQiOjE1NTU5OTY1MjUsImV4cCI6MTU1NzI5MjUyNX0.gcKasWAzO0ZS4ay_KGGp_ihPKG_GaGXk5iQKzP6R4_w",
      "company": ""
    }

验证用户 Token

Authing.checkLoginStatus(options)

• 参数:

  • {Object} options

    • user，必填，用户的 _id

• 使用方法:

  • (async () => {
        const authing = new Authing({
            userPoolId: 'your_userpool_id'
        });
        
        const result = await authing.checkLoginStatus('USER_JWT_TOKEN');
    })()

• 返回数据:

若 Token 合法，则返回数据为：

{
  status: false,
  code: 200,
  message: '已登录',
  token: {
    ... // Token 数据
  }
}

当 status 为 false 时，有三种情况，分别返回：

{
  status: false,
  code: 2020,
  message: '未登录'
}

{
  status: false,
  code: 2206,
  message: '登录信息已过期' 
}

{
  status: false,
  code: 2207,
  message: '登录信息有误'
}

退出

Authing.logout(uid)

• 参数:

  • {String} uid，必填，用户的 _id

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_client_id'
      });
      
      await authing.logout('59e5ff4935eebf1913cfe8a1')
        .catch((error) => { ... })
    })();

• 返回数据:

  • {
    	id: "59e5ff4935eebf1913cfe8a1"
    }

退出 SSO

如果你使用了 OAuth、OIDC 或 SAML 实现了单点登录，那么使用户退出登录需要跳转到一个 URL：

https://<你的域名>.authing.cn/login/profile/logout?app_id=<OAuth 应用 ID>&redirect_uri=<退出之后的回调地址>

其中 app_id 和 redirect_uri 都是必填选项，redirect_uri 是退出后你想要返回的地址。

获取单个用户资料

需要先调用登录函数，而且传入的用户 id 参数必须与登录用户的 id 一致才能获取信息。

Authing.user(options)

• 参数:

  • {Object} options

    • id，必填，用户的 _id

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_userpool_id'
      });
      // 先以用户身份登录，login 变量中保存的也是用户信息
      const login = await authing.login({
        email: 'test@test.com',
        password: '123456'
      })
      // 以后可以通过登录用户的 id 获取他的信息
      const userInfo = await authing.user({
        id: login._id
      })
        .catch((error) => { ... })
    })();

• 返回数据:

  • {
        "_id": "5a584dcd32e6510001a8f144", 
        "email": "1968198962@qq.com", 
        "emailVerified": false, 
        "username": "1968198962@qq.com", 
        "nickname": "", 
        "company": "", 
        "photo": "http://oxacbp94f.bkt.clouddn.com/user-avatars/Fqy_de1Jj5TmngEFiiY1-RsCCDcO", 
        "browser": "", 
        "registerInClient": "59f86b4832eb28071bdd9214", 
        "registerMethod": "default:username-password", 
        "oauth": "", 
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImVtYWlsIjoiMTk2ODE5ODk2MkBxcS5jb20iLCJpZCI6IjVhNTg0ZGNkMzJlNjUxMDAwMWE4ZjE0NCJ9LCJpYXQiOjE1MTcwMzI1MjV9.Ah0Oii741L_wJHhiE5KtWDgRU1Q3x_fNZBNNM5MhqDc", 
        "tokenExpiredAt": "Sat Jan 27 2018 13:55:25 GMT+0800 (CST)", 
        "loginsCount": 0, 
        "lastLogin": "Fri Jan 12 2018 13:55:25 GMT+0800 (CST)", 
        "lastIP": null, 
        "signedUp": "Fri Jan 12 2018 13:55:25 GMT+0800 (CST)", 
        "blocked": false, 
        "isDeleted": false, 
        "__typename": "ExtendUser"
    }

上传头像

Authing.selectAvatarFile(cb)

• 参数:

  • {function} cb

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_userpool_id'
      });
      
      authing.selectAvatarFile((avatarURL) => {
        // avatarURL 即为头像地址（公网 URL）
      })
    })();

• 结果:

  • 此 API 会打开文件选择窗口供用户选择文件，用户选取文件后，系统会自动上传，上传成功后会调用 cb，并把头像 URL 作为参数传入 cb 函数，开发者可将回调函数中的 avatarURL 作为 photo 参数传入 update 方法中修改用户头像。

修改密码

Authing.update(options)

• 参数:

  • {Object} options

    • password: {String}，必填，用户新密码

    • oldPassword: {String}，必填，用户原始密码

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_userpool_id'
      });
      // 以用户身份登录
      const login = await authing.login({
        email: 'test@test.com',
        password: '123456'
      })
      // 修改邮箱
      await authing.update({
        _id: login._id,
        oldPassword: 'abcdefg',
        password: '123456',
      });
    })();

• 返回数据:

  • ​
    {
        "_id": "59e5ff4935eebf1913cfe8a1",
        "email": "xxx@xxx.com",
        "emailVerified": false,
        "username": "premail@premail.com",
        "nickname": "",
        "company": "",
        "photo": "http://www.xiaohehe.net/uploads/allimg/150305/304-1503051H136.png",
        "browser": "",
        "token": null,
        "tokenExpiredAt": null,
        "loginsCount": 0,
        "lastLogin": "Tue Oct 17 2017 21:02:01 GMT+0800 (CST)",
        "lastIP": null,
        "signedUp": "Tue Oct 17 2017 21:02:01 GMT+0800 (CST)",
        "blocked": false,
        "isDeleted": false,
        "group": {
          "_id": "59e374332023830871913ebd",
          "name": "default",
          "descriptions": "default",
          "createdAt": "Sun Oct 15 2017 22:44:03 GMT+0800 (CST)"
        }
     }

修改用户资料

Authing.update(options)

此接口可以用来修改密码、昵称、头像等各种用户信息，调用前需要先调用登录函数，以用户身份登录，传入的用户 id 必须与登录用户的 id 一致。

• 参数:

  • {Object} options

    • _id {String} 必填

    • username: {String}，选填

    • nickname: {String}，选填

    • company: {String}，选填

    • oauth: {String}，选填，oauth 信息

    • photo: {String || file object}，选填，用户头像

    • browser: {String}，选填，用户注册时所用的浏览器

    • password: {String}，选填，用户密码

    • oldPassword: {String}（当有 password 时，旧密码参数必需填写）

    • token: {String}，选填

    • tokenExpiredAt: {String}，选填，token 过期时间

    • loginsCount: {Number}，选填，登录次数

    • lastLogin: {String}，选填，最后登录时间

    • lastIP: {String}，选填，最后登录 IP

    • signedUp: {String}，选填，注册时间

    • blocked: {Boolean}，选填，是否被锁定

    • isDeleted: {Boolean}，选填，是否被删除

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_userpool_id'
      });
      // 以用户身份登录
      const login = await authing.login({
        email: 'test@test.com',
        password: '123456'
      })
      // 修改邮箱
      await authing.update({
        _id: login._id,
        email: 'xxx@xxx.com',
      });
    })();

• 返回数据:

  • ​
    {
        "_id": "59e5ff4935eebf1913cfe8a1",
        "email": "xxx@xxx.com",
        "emailVerified": false,
        "username": "premail@premail.com",
        "nickname": "",
        "company": "",
        "photo": "http://www.xiaohehe.net/uploads/allimg/150305/304-1503051H136.png",
        "browser": "",
        "token": null,
        "tokenExpiredAt": null,
        "loginsCount": 0,
        "lastLogin": "Tue Oct 17 2017 21:02:01 GMT+0800 (CST)",
        "lastIP": null,
        "signedUp": "Tue Oct 17 2017 21:02:01 GMT+0800 (CST)",
        "blocked": false,
        "isDeleted": false,
        "group": {
          "_id": "59e374332023830871913ebd",
          "name": "default",
          "descriptions": "default",
          "createdAt": "Sun Oct 15 2017 22:44:03 GMT+0800 (CST)"
        }
     }

修改邮箱

如果用户已经绑定了邮箱，默认情况下，需要同时验证原有邮箱（目前账号绑定的邮箱）和当前邮箱（将要绑定的邮箱）。也就是说，用户 A 当前绑定的邮箱为 123456@qq.com，想修改为 1234567@qq.com，那么就需要同时验证这两个邮箱。

开发者也可以选择不开启 “验证原有邮箱“ ，可以在 Authing 控制台 的 基础配置 - 基础设置 页面的安全设置模块进行关闭。如下图所示：

验证码通过的 sendChangeEmailVerifyCode 接口发送。

Authing.updateEmail(options)

• 参数：

  • {Object} options

    • email : 当前邮箱，必填。

    • emailCode: 当前邮箱验证码，必填。

    • oldEmail：原有邮箱，选填。

    • oldEmailCode: 原有邮箱验证码，选填。

• 使用方法

(async function() {
  const authing = new Authing({
    userPoolId: 'your_userpool_id'
  });
  // 以用户身份登录
  const login = await authing.login({
    email: 'test@test.com',
    password: '123456'
  })
  await authing.updateEmail({
	email: "YOUR_NEW_EMAIL"
	emailCode: "YOUR_EMAIL_CODE"
  });
})();

• 返回数据：最新的用户信息

{
    "_id": "5a584dcd32e6510001a8f144", 
    "email": "1968198962@qq.com", 
    "emailVerified": false, 
    "username": "1968198962@qq.com", 
    "nickname": "", 
    "company": "", 
    "photo": "http://oxacbp94f.bkt.clouddn.com/user-avatars/Fqy_de1Jj5TmngEFiiY1-RsCCDcO", 
    "browser": "", 
    "registerInClient": "59f86b4832eb28071bdd9214", 
    "registerMethod": "default:username-password", 
    "oauth": "", 
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImVtYWlsIjoiMTk2ODE5ODk2MkBxcS5jb20iLCJpZCI6IjVhNTg0ZGNkMzJlNjUxMDAwMWE4ZjE0NCJ9LCJpYXQiOjE1MTcwMzI1MjV9.Ah0Oii741L_wJHhiE5KtWDgRU1Q3x_fNZBNNM5MhqDc", 
    "tokenExpiredAt": "Sat Jan 27 2018 13:55:25 GMT+0800 (CST)", 
    "loginsCount": 0, 
    "lastLogin": "Fri Jan 12 2018 13:55:25 GMT+0800 (CST)", 
    "lastIP": null, 
    "signedUp": "Fri Jan 12 2018 13:55:25 GMT+0800 (CST)", 
    "blocked": false, 
    "isDeleted": false, 
    "__typename": "ExtendUser"
}

发送修改邮箱验证码

开发者可以在 消息服务 - 邮件模版 中设置邮件模板，默认的邮件如下图所示：

开发者可以自定义 CSS 样式、主题等。

注意：如果请求发送的邮箱已经注册过了，会提示 “该邮箱已绑定，请换一个吧“ 错误。

Authing.sendChangeEmailVerifyCode(options)

• 参数：

  • {Object} options

    • email

• 使用方法

(async function() {
  const authing = new Authing({
    userPoolId: 'your_userpool_id'
  });
  // 以用户身份登录
  const login = await authing.login({
    email: 'test@test.com',
    password: '123456'
  })
  await authing.sendChangeEmailVerifyCode({
	email: "YOUR_NEW_EMAIL"
  });
})();

• 返回数据

成功示例

{
    code: 200,
    message: "成功"
}

失败示例：

{
    code: 2035,
    message: "该邮箱已绑定，请换一个吧"
}

修改手机号

和修改邮箱一样，默认情况下，如果用户当前已经绑定了手机号，需要同时验证原有手机号（目前账号绑定的手机号）和当前邮箱（将要绑定的手机号）。也就是说，用户 A 当前绑定的手机号为 15888888888，想修改为 15899999999，那么就需要同时验证这两个手机号。

开发者也可以选择不开启 “验证原有手机号“ ，可以在 Authing 控制台 的 基础配置 - 基础设置 页面的安全设置模块进行关闭。如下图所示：

手机号短信验证码通过 getVerificationCode 接口发送。

Authing.updatePhone(options)

• 参数：

  • {Object} options

    • phone : 当前手机号，必填。

    • emailCode: 当前手机号短信验证码，必填。

    • oldPhone：原有手机号，选填。

    • oldPhoneCode: 原有手机号短信验证码，选填。

• 使用方法

(async function() {
  const authing = new Authing({
    userPoolId: 'your_userpool_id'
  });
  // 以用户身份登录
  const login = await authing.login({
    email: 'test@test.com',
    password: '123456'
  })
  await authing.updateEmail({
	phone: "YOUR_NEW_PHONE_NUMBER"
	phoneCode: "YOUR_PHONE_CODE",
  oldPhone: "YOUR_CURRENT_PHONE_NUMBER",
  oldPhoneCode: "YOUR_CURRENT_PHONE_CODE"
  });
})();

• 返回数据：最新的用户信息。

重置密码

1. 发送验证码 Authing.sendResetPasswordEmail(options)

• 参数:

  • {Object} options

    • email

• 使用方法:

  • (async function() {
      const authing = new Authing({
        userPoolId: 'your_userpool_id'
      });
      
      // 发送验证码到指定邮箱
      await authing.sendResetPasswordEmail({
        email: 'xxx@xxx.com',
      });
    })();

• 返回数据:

  • {
      "message":"成功",
      "code":null,
      "__typename": "CommonMessage"
    }