Overview

HBuilderX 3.5.0+ support

云函数公共模块是不同云函数共享代码的一种方式。如果你不了解什么是云函数公共模块，请另读文档公共模块

uni-id-common is a common module for token management in the uni-id system.

旧版本uni-id公共模块是一个大而全的公共模块，不适用被众多云函数引用。

新版的uni-id-common仅包含token校验、生成及刷新功能。而用户注册、登录、忘记密码等实现都挪到了uni-id-co云对象中。

This not only reduces the size of the common module, but also simplifies the learning cost.

Starting from HBuilderX 3.5, the uni-id-common dependency is automatically loaded when creating a new uniCloud project. That is, uni-id-common is built into every project by default.

一般开发者无需了解uni-id-common公共模块的API，直接使用uni-id-pages云端一体页面模板即可。

If you want to understand the internal implementation of the uni-id-common common module, you can read this chapter.

API list

Create uni-id instance

Note: Unlike the old version of uni-id common module, uni-id-common must call this interface to create an instance before calling interfaces such as checkToken

用法：uniID.createInstance(Object CreateInstanceOptions);

CreateInstanceOptions内可以传入云函数context，也可以传入clientInfo参数，作用和context类似。方便在云对象内获取clientInfo后直接传入，什么是云对象？。

// Cloud function code, pass in context
const uniID = require('uni-id-common')
exports.main = async function(event,context) {
  context.APPID = '__UNI__xxxxxxx' // 替换为当前客户端的APPID，通过客户端callFunction请求的场景可以使用context.APPID获取
  context.PLATFORM = 'web' // 替换为当前客户端的平台类型，通过客户端callFunction请求的场景可以使用context.PLATFORM获取
  context.LOCALE = 'zh-Hans' // 替换为当前客户端的语言代码，通过客户端callFunction请求的场景可以使用context.LOCALE获取
  const uniIDIns = uniID.createInstance({ // 创建uni-id实例
    context: context,
    // config: {} // Complete uni-id configuration information, no need to pass this parameter when using config.json for configuration
  })
  payload = await uniIDIns.checkToken(event.uniIdToken) // 后续使用uniIDIns调用相关接口
  if (payload.code) {
  	return payload
  }
}

// Cloud object code passes in clientInfo
const uniID = require('uni-id-common')
module.exports = {
	_before() {
		const clientInfo = this.getClientInfo()
		this.uniID = uniID.createInstance({ // 创建uni-id实例，其上方法同uniID
			clientInfo
		})
	},
	refreshToken() {
		// ...
    // this.uniID.refreshToken()
	}
}

Why do you need to create a uni-id instance yourself

By default, some interfaces of uni-id-common will automatically obtain the client's PLATFORM (platform, such as app, h5, mp-weixin) and other information from the global context.

在云函数单实例多并发的场景下可能无法正确获取（全局对象会被后面的请求覆盖，可能会导致前面一次请求使用了后面一次请求的PLATFORM信息）。因此推荐在开启云函数单实例多并发后，自行为uni-id传入context。

In addition, when the cloud function is urlized, the client information cannot be obtained, and it is also necessary to pass the client information into the uni-id in this way.

token verification

An API that verifies the uniIdToken that comes with the request initiated by the client (uniCloud.callFunction), and obtains the user's uid, token, token expiration time, role, and permissions.

This is a very high frequency and important API that is usually used in exchange for the user ID of the current cloud function.

think

If you have no experience in server-side development, you may think: Why do you need to exchange the user ID with a token, instead of letting the client pass the user ID directly? This involves security issues. There is a saying: "The parameters passed by the front end cannot be trusted." For example, if you go to the bank to withdraw money, the counter will ask to show your ID card to prove who you are, instead of telling the bank counter directly who you are. Otherwise this is a huge security hole. To sum up: All server-side operations involving account information related content need to be obtained by using tokens instead of parameters passed by the front-end.

Usage: uniIDIns.checkToken(String token, Object checkTokenOptions)

Parameter Description

Fields	Type	Required	Description
token	String	Yes	The token brought by the client callFunction
options	object	no	options for checkToken method
|- autoRefresh	boolean	No	Whether it is necessary to automatically determine the refresh token, the default is true

illustrate

• The permission returned when the role contains admin is an empty array, so when judging whether a user has permission, you should pay attention to the admin role for additional judgment

Response parameters

Field	Type	Description
errCode	Number|String	Error code, 0 means success
message	String	Details
uid	String	User ID, it will be returned after successful verification
token	String	When the user token is about to expire, the newly generated token will only have this behavior when the value of tokenExpiresThreshold is configured in config
role	Array	-
permission	Array	A list of user permissions.

uni-id uses jwt to generate a token. The token generated by jwt consists of three parts, and the stored information is plaintext information. uni-id only verifies whether the client token is legal based on the tokenSecret.

Role permissions will be cached in the token, which can reduce or eliminate the number of checkToken checks (effectively saving costs and reducing response time)

Notice:

• The client will automatically find the token in the storage and insert it during callFunction
• HBuilderX 2.9.5+ client allows developers to pass in uniIdToken when calling Function, and no longer get token from storage
• Since HBuilderX version 2.8.0, it is recommended to use the snake-shaped uni_id_token when the token is stored in the storage, which will be compatible with the camel-case uniIdToken for a period of time

Active refresh token

Added in uni-id 3.3.14

用法：uniIDIns.refreshToken(Object RefreshTokenOptions);

Parameter Description

Fields	Type	Required	Description
token	String	Yes	user token

Example

const {
  token,
  tokenExpired
} = await uniIDIns.refreshToken({
  token: 'xxx'
})

Notice

• The role permissions corresponding to the uid in the token will be automatically updated when the token is refreshed

Generate token

用法：uniIDIns.createToken(Object CreateTokenOptions)

Parameter Description

Fields	Type	Required	Description
uid	String	Yes	UserId
role	Array	no	Specifies the role cached in the token
permission	Array	No	Specifies the permissions cached in the role

Response parameters

Fields	Type	Required	Description
token	String	Yes	Generated token
tokenExpired	Number	Yes	Timestamp corresponding to token expiration time

illustrate

• If the role permission is not passed when creating the token, the role permission corresponding to the uid will be automatically obtained