目录
简介
uni-id导入和配置
用户表与文章表关联foreignKey
字段级权限控制
指定数据集权限控制
权限规则的变量和运算符
uni-id
已完成的功能:
关于登录方式,目前已实现
由于三方登录很多,DCloud没有精力全部实现,在uni-id-co中留下了空实现,欢迎开发者自行补充、提交pr或发布扩展插件,共同完善uni-id
。。
后续计划:DCloud未来将内置 微信扫码登录和公众号登录、邮箱验证集成、facebook等海外主流社交账户登录、活体检测。
其他方面,各种常见开源项目如discuz、wordPress、ecshop的用户导入插件,不属于uni-id
主工程,欢迎开发者单独提交插件到插件市场。
uni-id
贯穿了uni-app前端到uniCloud后端的各个环节。
模块 | 说明 |
---|---|
前端uni-app框架的相关API | uniIdRouter页面路由、token管理客户端API |
前端页面uni-id-pages | 登录、注册、修改密码、忘记密码、个人中心、修改头像等前端页面 |
网络传输自动管理用户token | 自动保存、续期token、网络自动传输token |
云端云对象uni-id-co | 与uni-id-pages搭配的云对象,相关业务的云端部分 |
云端配置uni-config-center | 在uni-config-center下提供各种配置 |
云端公共模块uni-id-common | 用于云函数或云对象集成该模块验证token身份 |
云数据库的用户相关数据表 | uni-id-users等各种opendb数据表 |
uni-admin | Admin管理后台,包括用户角色权限管理、注册用户统计 |
- uni-id-pages(适用于uni-app的uni-id客户端)详情查看
- uni-id-pages-x(适用于uni-app x的uni-id客户端)详情查看
- uni-id-co(uni-id 的云对象)详情查看
uni-id的云端配置文件在uniCloud/cloudfunctions/common/uni-config-center/uni-id/config.json
中。
注意:
配置项:
passwordSecret
为用于加密密码入库的密钥tokenSecret
为生成token需要的密钥tokenExpiresIn
token有效期,以秒为单位passwordErrorLimit
密码错误重试次数,分ip记录密码错误次数,达到重试次数之后等待passwordErrorRetryTime
时间之后才可以重试passwordErrorRetryTime
单位为秒sendSmsCode
接口发送短信需要前往uniCloud控制台开通并充值,配置config.json
的service
字段,字段说明见下方示例下面的配置文件中所有时间的单位都是秒
!!!重要!!! passwordSecret与tokenSecret十分重要,切记妥善保存(不要直接使用下面示例中的passwordSecret与tokenSecret)。修改passwordSecret会导致老用户使用密码无法登录,修改tokenSecret会导致所有已经下发的token失效。如果重新导入uni-id切勿直接覆盖config.json相关配置
// 如果拷贝此内容切记去除注释
{
"passwordSecret": [
{
"type": "hmac-sha256",
"version": 1
}
], // 数据库中password字段是加密存储的,这里的passwordSecret即为加密密码所用的加密算法,详见[密码安全]
"passwordStrength": "medium", // 密码强度,新增于 uni-id-pages 1.0.8版本,见下方说明
"tokenSecret": "", // 生成token所用的密钥,注意修改为自己的,使用一个较长的字符串即可
"requestAuthSecret": "", // URL化请求鉴权签名密钥
"tokenExpiresIn": 7200, // 全平台token过期时间,未指定过期时间的平台会使用此值
"tokenExpiresThreshold": 3600, // 新增于uni-id 1.1.7版本,checkToken时如果token有效期小于此值且在有效期内则自动获取新token,请注意将新token返回给前端保存(云对象会自动保存符合uniCloud响应体规范的响应内的新token),如果不配置此参数则不开启自动获取新token功能
"maxTokenLength": 10, // 数据库用户记录token数组的最大长度,默认为10。新增于uni-id-common 1.0.16
"passwordErrorLimit": 6, // 密码错误最大重试次数
"passwordErrorRetryTime": 3600, // 密码错误重试次数超限之后的冻结时间
"autoSetInviteCode": false, // 是否在用户注册时自动设置邀请码,默认不自动设置
"forceInviteCode": false, // 是否强制用户注册时必填邀请码,默认为false
"idCardCertifyLimit": 1, // 实名认证相关; 限制每个身份证可以绑定几个账号
"realNameCertifyLimit": 5, // 实名认证相关; 限制用户每日认证次数,防止接口被刷
"sensitiveInfoEncryptSecret": "", // 敏感信息加密密钥(长度为32位的字符串),如使用实名认证功能需配置此密钥
"frvNeedAlivePhoto": false, // 实名认证相关;是否获取认证照片
"userRegisterDefaultRole": [], // 用户注册时的默认角色
"app": { // 如果你使用旧版本uni-id公共模块而不是uni-id-common这里可能配置的是app-plus,务必注意调整为app
"tokenExpiresIn": 2592000,
"tokenExpiresThreshold": 864000,
"oauth": {
// App微信登录所用到的appid、appsecret需要在微信开放平台获取,注意:不是公众平台而是开放平台
"weixin": {
"appid": "",
"appsecret": ""
},
// App QQ登录所用到的appid、appsecret需要在腾讯开放平台获取,注意:不是公众平台而是开放平台
"qq": {
"appid": "",
"appsecret": ""
},
"apple": { // 使用苹果登录时需要
"bundleId": ""
}
}
},
"web": { // 如果你使用旧版本uni-id公共模块而不是uni-id-common这里可能配置的是h5,务必注意调整为web
"tokenExpiresIn": 7200,
"tokenExpiresThreshold": 3600,
"oauth": {
"weixin-h5": { // 微信公众号登录配置
"appid": "",
"appsecret": ""
},
"weixin-web": { // 微信PC页面扫码登录配置
"appid": "",
"appsecret": ""
}
}
},
"mp-weixin": {
"tokenExpiresIn": 259200,
"tokenExpiresThreshold": 86400,
"oauth": {
// 微信小程序登录所用的appid、appsecret需要在对应的小程序管理控制台获取
"weixin": {
"appid": "",
"appsecret": ""
}
}
},
"mp-qq": {
"tokenExpiresIn": 259200,
"tokenExpiresThreshold": 86400,
"oauth": {
// QQ小程序登录所用的appid、appsecret需要在对应的小程序管理控制台获取
"qq": {
"appid": "",
"appsecret": ""
}
}
},
"mp-alipay": {
"tokenExpiresIn": 259200,
"tokenExpiresThreshold": 86400,
"oauth": {
// 支付宝小程序登录用到的appid、privateKey请参考支付宝小程序的文档进行设置或者获取,https://opendocs.alipay.com/open/291/105971#LDsXr
"alipay": {
"appid": "",
"privateKey": "", // 私钥
"keyType": "PKCS8" // 私钥类型,如果私钥类型不是PKCS8,需要填写此字段,否则会出现“error:0D0680A8:asn1 encoding routines:ASN1_CHECK_TLEN:wrong tag”错误
}
}
},
"service": {
"sms": {
"name": "", // 应用名称,对应短信模版的name
"codeExpiresIn": 180, // 验证码过期时间,单位为秒,注意一定要是60的整数倍
"smsKey": "", // uni-id-co 1.1.17及以上版本无需填写,短信密钥key,开通短信服务处可以看到
"smsSecret": "", // uni-id-co 1.1.17及以上版本无需填写,短信密钥secret,开通短信服务处可以看到
"scene": {
"bind-mobile-by-sms": { // 对绑定手机号场景的配置,短信验证码场景值参考:https://uniapp.dcloud.net.cn/uniCloud/uni-id/summary.html#sms-scene
"templateId": "", // 绑定手机号使用的短信验证码模板
"codeExpiresIn": 240 // 绑定手机号验证码过期时间
}
}
},
"univerify": {
"appid": "", // uni-id-co 1.1.17及以上版本无需填写,当前应用的appid,使用云函数URL化,此项必须配置
"apiKey": "", // uni-id-co 1.1.17及以上版本无需填写,apiKey 和 apiSecret 在开发者中心获取,开发者中心:https://dev.dcloud.net.cn/pages/uniLogin/index,文档:https://ask.dcloud.net.cn/article/37965
"apiSecret": ""
}
}
}
添加完配置后 注册登录 数据库会多出两张表 uni-id-log uni-id-users
uni_modules/uni-id-pages/pages/register/register 注册页
uni_modules/uni-id-pages/pages/login/login-withpwd 登录
关联关系 | foreignKey | String | 关联字段。表示该字段的原始定义指向另一个表的某个字段,值的格式为表名.字段名 ,比如订单表的下单用户uid字段指向uni-id-users表的_id字段,那么值为uni-id-users._id 。关联字段定义后可用于联表查询,通过关联字段合成虚拟联表,极大的简化了联表查询的复杂度 |
一个复杂的业务系统,有很多张数据表。表与表之间,存在的数据关联。foreignKey用于描述数据关联关系。
比如一个文章系统,至少需要用户表、文章分类表、文章表、评论表。opendb已经包含了这4张表,可以点击链接看这些表的结构:
分表
我们先不展开描述上面这几张表,首先讲解为什么分表、怎么分表。
user_id
配置了"foreignKey": "uni-id-users._id"
因为MongoDB的灵活性,理论上可以在用户表[uni-id-users]中新增一个字段articles,在articles下面通过数组来存放该作者的每一遍文章,然后在该文章中再来一个字段comments,存放该文章的每一条评论。
如下,uni-id-users表的数据内容,假使里面有2个用户,zhangsan和lisi,然后lisi写了1篇文章,这篇文章又被zhangsan评论了1条。
[{
"_id": "60b92a42e22fbe00018c359d",
"username": "zhangsan",
"password": "03caebb36670995fc261a275d212cad65e4bbebd",
"register_date": 1622747714731,
"register_ip": "192.168.0.1",
},
{
"_id": "60b9315801033700011ba9ed",
"username": "lisi",
"password": "03caebb36670995fc261a275d212cad65e4bbebd",
"register_date": 1622747714731,
"register_ip": "192.168.0.2",
"articles":[
{
"title": "文章标题",
"content": "文章内容",
"publish_date": 1617850851000,
"publish_ip": "192.168.0.2",
"comments":[
{
"user_id":"60b92a42e22fbe00018c359d",
"comment_content":"评论内容",
"comment_date":1617850851022,
"comment_ip": "192.168.0.1"
}
]
}
]
}]
可以看出,这个uni-id-users表形成了用户、文章、评论的三层嵌套。
虽然MongoDB可以这么嵌套,但实际业务中不该这样设计。会导致查询性能低下甚至某些查询条件无法实现。
数据库是数字系统的底层,它应该清晰有条理,人、文章、评论以及这3者的关系,都应该清晰且不冗余。
MongoDB的嵌套,更多的适用于不会被单独拎出来查询的、记录条数较少的场景。
比如简历表中的工作经历,就可以嵌套。因为工作经历数量较少、且不会出现单独查工作经历而不查人的情况。
但文章表,是一定需要独立的,因为文章数量会非常多,它会单独搜索;
评论表其实不太有单独搜索的需求,它总是伴随指定文章出现。但因为数量会很多,评论也需要分页查询,嵌套在文章表下不利于分页查询。
所以正确的数据库设计,还是分开这几张表。另外很多文章系统都会有文章分类,比如 社会、教育、娱乐、体育、科技...,所以还需要一个文章分类表。
opendb的这4张表,才是正确的分表设计。
可以看到注册用户都在uni-id-users表中,而文章内容在opendb-news-articles表中。一个用户可能写了很多文章,这些文章不会存入uni-id-users表。
表之间的关系
既然有了分表的概念,就存在表与表之间关系的概念了。
比如在文章表中,如何存放文章的作者信息?如何表示这篇文章是哪个用户写的?是存放作者的用户名吗?
实际上,文章表中的作者字段,也就是user_id
字段,存放的是用户表中的这个作者的_id
字段的值。_id
是uniCloud数据库每张表的每个记录都有的唯一字段。
可以看下用户表uni-id-users和文章表opendb-news-articles具体数据,直观感受下:
uni-id-users用户表,还是假使里面有2个作者,zhangsan和lisi
[{
"_id": "60b92a42e22fbe00018c359d",
"username": "zhangsan",
"password": "03caebb36670995fc261a275d212cad65e4bbebd",
"register_date": 1622747714731,
"register_ip": "127.0.0.1",
},
{
"_id": "60b9315801033700011ba9ed",
"username": "lisi",
"password": "03caebb36670995fc261a275d212cad65e4bbebd",
"register_date": 1622747714731,
"register_ip": "127.0.0.1",
}]
opendb-news-articles文章表,里面只有1篇文章,这篇文章是 lisi 写的,所以在字段user_id
中存的就是60b9315801033700011ba9ed
,这就是uni-id-users表中 lisi 对应的
{
"_id": "606e721280b8450001e773c6",
"category_id": "606e6feb653b8400017214a3",
"title": "这里是标题",
"content": "这里是正文",
"user_id": "60b9315801033700011ba9ed",
"publish_date": 1617850851000,
"publish_ip": "119.131.174.251"
}
只要user_id
这个关联关系映射起来,数据就清晰且完整了。
并不需要在文章表opendb-news-articles存放作者的用户名、昵称、头像、注册时间甚至密码,只需要存它的user_id
,就精准、最小冗余的表达数据关系。
当然也有的系统设计为了减少联表查询而在文章表里冗余存放作者昵称和头像,是否使用冗余可以视需求而定,但一定需要用user_id
来做数据表的关联。
foreignKey的用法
上面显示的是2个表的数据内容,但回到 DB Schema 中,如何在schema中表达这种关联关系?那就是foreignKey,外键。
文章表opendb-news-articles的 DB Schema 中的user_id
字段的描述如下:
"properties": {
"_id": {
"description": "存储文档 ID(用户 ID),系统自动生成"
},
"user_id": {
"bsonType": "string",
"description": "文章作者ID, 参考`uni-id-users` 表",
"foreignKey": "uni-id-users._id",
"defaultValue": {
"$env": "uid"
}
},
"title":{},
"content":{}
}
上面的重点,就在这个foreignKey,它的前半部分是另一张表的表名,中间用.
分割,后半部分是另一张表的字段名。
它代表文章表这个user_id
字段,在关系上实质指向uni-id-users表的_id
字段。也就是文章表的user_id
字段里存的值,其实是源自uni-id-users表的_id
字段里的值。
注意不要搞反,并不是在uni-id-users表的schema的_id
字段里配foreignKey。uni-id-users表的_id
字段是原值,不引用自任何地方。而是在其他引用uid的字段来配。
同样,评论表opendb-news-comments的schema里,
user_id
的foreignKey需指向"uni-id-users._id"
article_id
的foreignKey需指向"opendb-news-articles._id"
配置foreignKey,除了清晰描述数据关系,它最大的作用是联表查询。
JQL没有像SQL那样提供了join、leftjoin、innerjoin这些语法,只需要配置好数据关系,配好foreignKey,查询时就可以自动联表查询。
联表查询内容较多,详见
permission的字段级控制,包括读写两种权限,分别称为:read、write。
也就是对于一个指定的字段,可以控制什么样的角色可以读取该字段内容,什么样的角色可以修改写入字段内容。
以上述的user表为例,假如要限制前端禁止读取age字段,那么按如下配置,在字段age下面再写permission节点,设定read为false。
// user表的schema
{
"bsonType": "object",
"required": [],
"permission": {
"read": true, // 任何用户都可以读
"create": false, // 禁止新增数据记录(admin权限用户不受限)
"update": false, // 禁止更新数据(admin权限用户不受限)
"delete": false // 禁止删除数据(admin权限用户不受限)
},
"properties": {
"_id":{
},
"name":{
},
"age": {
"bsonType": "number",
"title": "年龄",
"permission": {
"read": false, // 禁止读取 age 字段的数据(admin权限用户不受限)
"write": false // 禁止写入 age 字段的数据(admin权限用户不受限)
}
}
}
}
按上述配置,前端查询数据时,如果不包含age字段,仍然可以查询。但如果查询请求包含age字段,该请求会被拒绝,提示无权访问。
子级会继承父级的权限,即需要同时满足父级权限以及本节点权限,方可操作此节点。例如上述schema中如果配置表级read权限为false,在为name设置read权限为true的情况下,name字段仍不可读
如果字段的bsonType配置为password,则clientDB完全不可操作此字段(即使是admin用户也不可以在客户端读写)。
// user表的schema
{
"bsonType": "object",
"required": [],
"permission": {
"read": true, // 任何用户都可以读
"create": false, // 禁止新增数据记录(admin权限用户不受限)
"update": false, // 禁止更新数据(admin权限用户不受限)
"delete": false // 禁止删除数据(admin权限用户不受限)
},
"properties": {
"_id":{
},
"name":{
},
"pwd": {
"bsonType": "password", // 即使不配置权限,此字段也无法在客户端读写
"title": "密码"
}
}
}
DB Schema
提供了一个内置变量doc,表示要意图操作的数据记录。并支持用各种表达式来描述指定的记录。
仍然以user表举例,假使该表有个字段叫status
表示用户是否被禁用。status
是bool值,true代表用户状态正常,false代表被禁用。
然后有个需求,JQL只能查用户状态正常的用户信息,禁用用户信息无法查。那么schema配置如下,表级控制的read节点的值不再是简单的true/false,而是变成一个表达式:"doc.status==true"
// user表的schema
{
"bsonType": "object",
"required": [],
"permission": {
"read": "doc.status==true", // 任何用户都可以读status字段的值为true的记录,其他记录不可读
"create": false, // 禁止新增数据记录(admin权限用户不受限)
"update": false, // 禁止更新数据(admin权限用户不受限)
"delete": false // 禁止删除数据(admin权限用户不受限)
},
"properties": {
"_id":{
},
"name":{
},
"pwd": {
"bsonType": "string",
"title": "密码",
"permission": {
"read": false, // 禁止读取 pwd 字段的数据(admin权限用户不受限)
"write": false // 禁止写入 pwd 字段的数据(admin权限用户不受限)
}
},
"status": {
"bsonType": "bool",
"title": "用户状态",
"description": "true代表用户正常。false代表用户被禁用"
}
}
}
根据这个配置,如JQL查询user表的所有数据,则会报权限校验失败;如JQL查询里在where条件里声明了只查询status字段为true的数据,则查询会放行。
除了上述例子提到的doc变量,事实上DB Schema
的权限规则支持很多变量和运算符,可以满足各种配置需求。
权限规则内可用的全局变量
变量名 | 说明 |
---|---|
auth.uid | 用户id |
auth.role | 用户角色数组,参考uni-id 角色权限,注意admin 为内置的角色,如果用户角色列表里包含admin 则认为此用户有完全数据访问权限 |
auth.permission | 用户权限数组,参考uni-id 角色权限 |
doc | 数据库中的目标数据记录,用于匹配记录内容/查询条件 |
now | 当前服务器时间戳(单位:毫秒),时间戳可以进行额外运算,如doc.publish_date > now - 60000表示publish_date在最近一分钟 |
action | 已废弃,使用数据库触发器替代action云函数 |
注意
auth
表示正在执行操作的用户对象auth.xxx
均由uni-id提供,依赖于uni-id公共模块doc.xxx
表示将要查询/修改/删除的每条数据(注意并不包括新增数据,新增数据应通过值域校验进行验证),如果将要访问的数据不满足permission规则将会拒绝执行uni-id
的角色和权限,也即auth.role和auth.permission是不一样的概念。注意阅读uni-id 角色权限权限规则内可以使用的运算符
运算符 | 说明 | 示例 | 示例解释(集合查询) |
---|---|---|---|
== | 等于 | auth.uid == 'abc' | 用户id为abc |
!= | 不等于 | auth.uid != null | 用户要处于登录状态 |
> | 大于 | doc.age>10 | 目标数据的 age 属性大于 10 |
>= | 大于等于 | doc.age>=10 | 目标数据的 age 属性大于等于 10 |
< | 小于 | doc.age<10 | 目标数据的 age 属性小于 10 |
<= | 小于等于 | doc.age<=10 | 目标数据的 age 属性小于等于 10 |
in | 存在在数组中 | doc.status in ['a','b'] | 目标数据的 status 是['a','b']中的一个,数组中所有元素类型需一致 |
! | 非 | !(doc.status in ['a','b']) | 目标数据的 status 不是['a','b']中的任何一个,数组中所有元素类型需一致 |
&& | 与 | auth.uid == 'abc' && doc.age>10 | 用户id 为 abc 并且目标数据的 age 属性大于 10 |
|| | 或 | auth.uid == 'abc'||doc.age>10 | 用户Id为abc或者目标数据的 age 属性大于 10 |
我们继续使用user表举例,目前需求如下,前端用户如果登录,那么该用户可以修改自己的name字段。此时需要在schema中配置name字段的permission为"write":"(doc._id == auth.uid)"
// user表的schema
{
"bsonType": "object",
"required": [],
"permission": {
"read": "doc.status==true", // 任何用户都可以读status字段的值为true的记录,其他记录不可读
"create": false, // 禁止新增数据记录(admin权限用户不受限)
"update": "'updateuser' in auth.permission", // 权限标记为updateuser的用户,和admin管理员,可以更新数据,其他人无权更新数据
"delete": false // 禁止删除数据(admin权限用户不受限)
},
"properties": {
"_id":{
},
"name":{
"bsonType": "string",
"title": "名称",
"permission": {
"read": true,
"write": "doc._id == auth.uid" // 允许登录的用户修改自己的name字段
}
},
"pwd": {
"bsonType": "string",
"title": "密码",
"permission": {
"read": false, // 禁止读取 pwd 字段的数据(admin权限用户不受限)
"write": false // 禁止写入 pwd 字段的数据(admin权限用户不受限)
}
},
"status": {
"bsonType": "bool",
"title": "用户状态",
"description": "true代表用户正常。false代表用户被禁用"
}
}
}
根据这个配置,如前端应用已经登录,且登录的用户发起修改自己的name的请求,则允许修改。其他修改数据请求则会被拒绝。
注意
要分清 数据权限permission
和 字段值域校验validator
的区别。
在权限规则的变量中只有数据库中的数据doc,并没有前端提交的待入库数据data。所以如果要对待入库的数据data做校验,应该在字段值域validator中校验,而不是在权限permission中校验。
如果想获取和判断目标数据记录doc之外的其他数据,则需要使用get方法,见下一章节。
forceDefaultValue属于数据校验的范畴,在数据写入时生效,但是如果配置forceDefaultValue为{"$env": "uid"}
也会进行用户身份的校验,未登录用户不可插入数据。
例如在news表新增一条记录,权限需求是“未登录用户不能创建新闻”,其实不需要在news表的create权限里写auth.uid != null
。只需把news表的uid字段的forceDefaultValue设为"$env": "uid"
,create权限配置为true即可,未登录用户自然无法创建。当然实际使用时你可能需要更复杂的权限,直接使用true作为权限规则时务必注意
permission和role的使用注意
在schema中使用uni-id的permission和role,首先需要在uniCloud admin中创建好权限,然后创建角色并给该角色分配权限,最后创建用户并授权角色。
这样用户登录后,uniCloud会自动分析它的permission和role,在schema里编写的关于permission和role的限制也可以一一对应上,进行有效管理。
admin中创建权限、角色和用户授权,另见文档