diff --git a/docs/uniCloud/uni-id-pages.md b/docs/uniCloud/uni-id-pages.md index 7d2c060305ba3dc68d019292dae82ab5ef1b6f5c..35e56df0b873977ff0191c25b321c48c9e4c54cd 100644 --- a/docs/uniCloud/uni-id-pages.md +++ b/docs/uniCloud/uni-id-pages.md @@ -603,46 +603,6 @@ await uniIDCo.logout() |errCode |string|number |错误码 | |errMsg |string |错误信息 | -#### 获取支持的登录方式@get-supported-login-type - -**接口形式** - -```js -await uniIDCo.getSupportedLoginType({ - appId, - platform -}) -``` - -**参数说明** - -|参数名 |类型 |必填 |说明 | -|-- |-- |-- |-- | -|appId |string |否 |要查询登录方式的应用DCloud AppId，不传时为当前应用 | -|platform |string |否 |要查询登录方式的应用平台，不传时为当前平台 | - -**返回值** - -|参数名 |类型 |说明 | -|-- |-- |-- | -|errCode |string|number |错误码 | -|errMsg |string |错误信息 | -|supportedLoginType |array |支持的登录方式列表，见下方说明 | - -**supportedLoginType** - -|登录方式 |说明 | -|--- |--- | -|username-password |用户名密码登录 | -|mobile-password |手机号密码登录 | -|email-password |邮箱密码登录 | -|mobile-code |手机号验证码登录 | -|univerify |App一键登录 | -|weixin |微信登录 | -|qq |QQ登录 | -|apple |苹果登录 | -|alipay |支付宝登录 | - ### 绑定账号@bind #### 使用短信验证码绑定手机号@bind-mobile-by-sms @@ -1259,6 +1219,264 @@ await uniIDCo.setAuthorizedApp({ - 此接口为管理端接口 - 仅在用户token即将过期时返回新newToken +### 开发接口@dev + +#### 获取支持的登录方式@get-supported-login-type + +**接口形式** + +```js +await uniIDCo.getSupportedLoginType({ + appId, + platform +}) +``` + +**参数说明** + +|参数名 |类型 |必填 |说明 | +|-- |-- |-- |-- | +|appId |string |否 |要查询登录方式的应用DCloud AppId，不传时为当前应用 | +|platform |string |否 |要查询登录方式的应用平台，不传时为当前平台 | + +**返回值** + +|参数名 |类型 |说明 | +|-- |-- |-- | +|errCode |string|number |错误码 | +|errMsg |string |错误信息 | +|supportedLoginType |array |支持的登录方式列表，见下方说明 | + +**supportedLoginType** + +|登录方式 |说明 | +|--- |--- | +|username-password |用户名密码登录 | +|mobile-password |手机号密码登录 | +|email-password |邮箱密码登录 | +|mobile-code |手机号验证码登录 | +|univerify |App一键登录 | +|weixin |微信登录 | +|qq |QQ登录 | +|apple |苹果登录 | +|alipay |支付宝登录 | + +## uni-id-common公共模块的API列表@api + +自`uni-id 4.0.0`起uni-id公共模块内的大部分接口实现移至uni-id-co内，公共模块内仅保留token相关接口 + +一般开发者无需了解uni-id-common公共模块的API，直接使用[uni-id-pages]()即可（**需要补充链接**）。 + +如果想了解uni-id-common公共模块内部实现，可以阅读本章节。 + +### 基础功能@base + +#### 创建uni-id实例@create-instance + +用法：`uniID.createInstance(Object CreateInstanceParams);` + +CreateInstanceParams内可以传入云函数context，也可以传入clientInfo参数，作用和context类似。方便在云对象内获取clientInfo后直接传入，[什么是云对象？](uniCloud/cloud-obj.md)。 + +```js +// 云函数代码，传入context +const uniID = require('uni-id-common') +exports.main = async function(event,context) { + context.APPID = '__UNI__xxxxxxx' // 替换为当前客户端的APPID，通过客户端callFunction请求的场景可以使用context.APPID获取 + context.PLATFORM = 'h5' // 替换为当前客户端的平台类型，通过客户端callFunction请求的场景可以使用context.PLATFORM获取 + context.LOCALE = 'zh-Hans' // 替换为当前客户端的语言代码，通过客户端callFunction请求的场景可以使用context.LOCALE获取 + const uniIDIns = uniID.createInstance({ // 创建uni-id实例 + context: context, + // config: {} // 完整uni-id配置信息，使用config.json进行配置时无需传此参数 + }) + payload = await uniIDIns.checkToken(event.uniIdToken) // 后续使用uniIDIns调用相关接口 + if (payload.code) { + return payload + } + const res = await uniIDIns.updateUser({ + uid: payload.uid, + nickname: 'user nickname' + }) + return res +} + +// 云对象代码传入clientInfo +const uniID = require('uni-id-common') +module.exports = { + _before() { + const clientInfo = this.getClientInfo() + this.uniID = uniID.createInstance({ // 创建uni-id实例，其上方法同uniID + clientInfo + }) + }, + login() { + // ... + // this.uniID.login() + } +} +``` + +**为什么需要自行创建uni-id实例** + +默认情况下uni-id-common某些接口会自动从全局context内获取客户端的PLATFORM（平台，如：app、h5、mp-weixin）等信息。 + +在单实例多并发的场景下可能无法正确获取（全局对象会被后面的请求覆盖，可能会导致前面一次请求使用了后面一次请求的PLATFORM信息）。因此推荐在开启云函数单实例多并发后，自行为uni-id传入context。 + +此外云函数url化时无法获取客户端信息，也需要使用这种方式将客户端信息传入uni-id。 + +#### token校验@checktoken + +一个校验客户端发起请求（uniCloud.callFunction）自带的uniIdToken，获得用户的uid、token、token的过期时间、角色、权限、用户信息(uni-id-users全部字段)的API。 + +这是非常高频且重要的API通常用于换取操作当前云函数的用户Id。 + +##### 思考 + +如果你并没有服务端开发经验，可能会想：为什么需要通过token去换取用户Id，而不是让客户端直接传递用户Id更方便？ +这里就涉及到安全问题，有一句话叫做：“前端传递的参数都是不可信任的”。比如：你去银行取款，柜台会要求出示你的身份证来证明你是谁，而不是你直接告诉银行柜台你是谁就管用。否则这是一个极大的安全漏洞。 +综上所述：所有服务端操作涉及账户信息相关内容，都需要使用token来获得，而不是使用前端传递的参数。 + +用法：`uniID.checkToken(String token, Object checkTokenOptions)` + +**参数说明** + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| token | String | 是 |客户端callFunction带上的token | +| options | object | 否 |checkToken方法的选项 | +|  |- autoRefresh| boolean | 否 |是否需要自动判断刷新token，默认true | + +**说明** + +- 角色内包含admin时返回的permission是一个空数组，因此判断一个用户是否有权限时应注意admin角色额外进行判断 + +请务必阅读一下此文档：[关于缓存角色权限的说明](uniCloud/uni-id.md?id=cache-permission-in-token) + +**响应参数** + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| errCode | Number|String|错误码，0表示成功 | +| message | String |详细信息 | +| uid | String |用户Id，校验成功之后会返回 | +| token | String |用户token快要过期时，新生成的token，只有在config内配置了`tokenExpiresThreshold`的值时才会有此行为 | +| tokenExpired | TimeStamp |新token的过期时间，单位毫秒 | +| role | Array |- | +| permission | Array |用户权限列表。 | + +uni-id使用jwt生成token，jwt所生成的token包含三部分，其中存储的信息为明文信息，uni-id只根据tokenSecret来校验客户端token是否合法。 + + +角色权限将被缓存在token中，此举能减少或消除checkToken的查库次数（有效节省费用、减少响应时间） + +**注意：** + +- 客户端会自动查找storage内的token在callFunction时插入 +- HBuilderX 2.9.5+ 客户端允许开发者自行在callFunction时传入uniIdToken，此时不再从storage获取token +- HBuilderX 2.8.0版本起token存储在storage内推荐使用使用蛇形`uni_id_token`，会在一段时间内兼容驼峰形式`uniIdToken` + +#### 主动刷新token@refresh-token + +> 新增于uni-id 3.3.14 + +用法：`uniID.refreshToken(Object RefreshTokenParams);` + +**参数说明** + +| 字段| 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| token | String| 是 |用户token| + +**示例** + +```js +const { + token, + tokenExpired +} = await uniID.refreshToken({ + token: 'xxx' +}) +``` + +**注意** + +- 刷新token时会自动更新token内uid对应的角色权限 + +#### 生成token@createtoken + +用法：`uniID.createToken(Object CreateTokenParams)` + +**参数说明** + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| uid | String| 是 |用户Id | +| role | Array | 否 |指定缓存在token内的角色| +| permission| Array | 否 |指定缓存在角色内的权限 | + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| token | String| 是 |生成的token | +| tokenExpired| Number| 是 |token过期时间对应的时间戳| + +**说明** + +- 创建token时如果未传角色权限会自动获取uid对应的角色权限 + +## uniIdRouter自动路由@uni-id-router + +> 新增于 HBuilderX 3.5.0 + +开发者可以在项目的`pages.json`内配置需要登录的页面，登录页面路径等信息，uniCloud会自动在需要登录且客户端登录状态过期或未登录时跳转到登录页面。 + +结合以下代码及注释了解如何使用`uniIDRouter` + +```json +{ + "pages": [ + { + "path": "pages/index/index", + "style": { + "navigationBarTitleText": "uni-app" + }, + "needLogin": false // 当前页面是否需要登录才可以访问，此配置优先级高于uniIDRouter下的needLogin + }, { + "path": "pages/list/list", + "style": { + "navigationBarTitleText": "uni-app" + }, + "needLogin": false + }, { + "path": "pages/detail/detail", + "style": { + "navigationBarTitleText": "uni-app" + } + } + ], + "globalStyle": { + "navigationBarTextStyle": "black", + "navigationBarTitleText": "uni-app", + "navigationBarBackgroundColor": "#F8F8F8", + "backgroundColor": "#F8F8F8" + }, + "uniIDRouter": { + "loginPage": "pages/index/index", // 登录页面路径 + "needLogin": [ + "pages/detail/.*" // 需要登录才可访问的页面列表，可以使用正则语法 + ], + "resToLogin": true // 自动解析云对象及clientDB的错误码，如果是客户端token不正确或token过期则自动跳转配置的登录页面，配置为false则关闭此行为，默认true + } +} + +``` + +与此功能对应的有两个uniCloud客户端api，`uniCloud.onNeedLogin()`和`uniCloud.offNeedLogin()`，开发者在监听onNeedLogin事件后，框架就不再自动跳转到登录页面，而是由开发者在onNeedLogin事件内自行处理。详情参考：[uniCloud.onNeedLogin](uniCloud/client-sdk.md?id=on-need-login) + +**注意** + +- pages.json内有`uniIDRouter`节点上述逻辑才会生效，自HBuilderX 3.5.0起创建空项目模板会自动配置空的`uniIDRouter`节点 + ## 错误码@errcode |错误码 |错误信息 |说明 |