权限控制

此 模块的 API 可以分为两类:

一类是权限管理、配置接口:

  • 分组(Group)的增删改查接口

    • 支持批量、分页

  • 角色(Role)的增删改查接口

    • 支持批量、分页

  • 权限(Permission)的增删改查接口

    • 支持批量、分页

  • 分组内用户管理

  • 分组内角色管理

  • 角色内用户管理

  • 角色内权限管理

另一类是查询特定用户权限接口:

  • 查询特定用户所有权限列表

  • 查询特定用户所有角色列表

  • 查询特定用户所有分组列表

除了主动查询接口外,我们还支持将权限列表写入用户的 Token,开发者可以在本地使用应用密钥解密得到权限列表。最终的权限列表示例如下:

{
"permissionList": ["email:login", "email:read", "email:write", "email:send"]
}

其中 ​email:login​ 完全为用户自定义,我们推荐使用object:action的格式进行命名

开发者拿到用户权限列表之后,可以在业务代码层判断用户是否具备某一特定权限,如:

if not "email:login" in user.permissionList:
raise PermissionDeniedError

初始化

使用以下接口时,请先完成初始化工作,请参考:

异常处理

所有失败的操作,都需要使用 try catch 捕获异常。操作失败有两种情况:

  • 网络请求出错,常见情况包括:传递参数不合法,这会被 GraphQL 过滤层直接拦截;网络无法连接。

  • 业务逻辑出错,常见情况包括:密码不正确,删除某资源传递的 id 不存在等。

为了方便开发者快速定位出错原因,我们提供一个 formatError 函数:

function formatError(error) {
if (typeof error === 'string') return error;
if (error.request) {
// 网络请求错误
if(error.response)
return JSON.stringify(error.response.data);
else
return JSON.stringify(error.request);
} else if (typeof error.message === 'object') {
// 业务逻辑错误
if (error.message.message) {
return JSON.stringify(error.message.message);
} else {
return JSON.stringify(error.message);
}
} else {
return error;
}
}

示例如下:

try {
const res = await authing.authz.deleteGroup("不存在的 groupId")
console.log(res)
} catch (error) {
console.log(formatError(error))
}

分组增删改查

创建分组

Authing.authz.createGroup(input)

  • 参数

    • input <Object>

      • name <string> 名称,必填。

      • description <string> 描述,选填。

  • 使用方法

const group = await authing.authz.createGroup({
name: 'admin',
description: "系统管理员"
})
  • 返回数据

{
_id: '5e1edbd74b6419665991f51e',
name: '管理员835bdf92gth',
description: '描述信息',
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
}

修改分组

Authing.authz.updateGroup(input)

  • 参数

    • input <Object>

      • _id <string> 分组 ID,必填。

      • name <string> 名称,选填。

      • description <string> 描述,选填。

  • 使用方法

group = await authing.authz.updateGroup({
_id: "5e1edcb14b6419665991f595",
description: '新的描述'
})
  • 返回数据

{
_id: '5e1edcb14b6419665991f595',
name: 'admin',
description: '新的描述',
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
}

本页中的所有修改接口均遵循以下逻辑:

  • _id 参数必填

  • 出现在 input 中的字段值将替换原有值

  • 没有出现在 input 中的字段值保持不变

  • 传入 input 的多余字段将会被舍弃

查询分组

Authing.authz.group(_id)

  • 参数

    • _id <string> 分组 ID,必填。

  • 使用方法

const group = await authing.authz.group("5e1edcb14b6419665991f595")
  • 返回数据

{
_id: '5e1edcb14b6419665991f595',
name: 'admin',
description: '新的描述',
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
}

查询用户池分组列表

此方法支持分页、排序。

Authing.authz.groupList(options)

  • 参数

    • options <Object> 可选

      • sortBy <string> 排序方式,可选。默认为 CREATEDAT_DESC ,表示按照创建时间降序,也就是最新创建的排在最前面。全部的可选值为:

        • CREATEDAT_DESC:按照创建时间降序。

        • CREATEDAT_ASC :按照创建时间升序。

        • UPDATEDAT_DESC:按照修改时间降序。

        • UPDATEDAT_ASC:按照修改时间排序。

      • page <int> 页码,可选。默认为 0,zero-based。

      • count <int> 没页数目,可选。默认为 10。

  • 使用方法

const groupList = await authing.authz.groupList()
// 自定义排序方式 / 分页
const {totalCount, list} = await authing.authz.groupList({
sortBy: "CREATEDAT_DESC",
page: 1,
count: 10,
})
  • 返回数据

    • totalCount 总数

    • list 当前页列表

{
totalCount: 2,
list: [
{
_id: '5e1fff324b6419665991f6b4',
name: 'employee',
description: '正式员工。',
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
},
{
_id: '5e1edcb34b6419665991f5d9',
name: 'intern',
description: '实习生。',
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
},
]
}

删除分组

Authing.authz.deleteGroup(_id)

  • 参数

    • _id 分组 ID,必填。

  • 使用方法

const res = await authing.authz.deleteGroup("5e20082f4b6419665991fa57")
  • 返回数据

操作成功示例

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

删除分组会将其与角色、用户之间的关系连带一起删除(角色、用户本身不会删除),不可撤回,请谨慎操作。

且此操作为原子化操作,要么成功,要么全部 rollback。

批量删除分组

Authing.authz.deleteGroupBatch(idList)

  • 参数

    • idList: <Array> 分组 ID 列表。

  • 使用方法

const res = await authing.authz.deleteGroupBatch([
"5e1fff324b6419665991f6b4",
"5e1edcb34b6419665991f5d9"
])
  • 返回参数

操作成功示例:

{
message: '操作成功',
code: 200
}

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

此操作不可撤回,请谨慎操作。

角色增删改查

创建角色

Authing.authz.createRole(input)

  • 参数

    • input <Object>

      • name: 名称,必填。

      • description: 描述,必填。

  • 使用方法

const role = await authing.authz.createRole({
name: 'Invoice Submitter',
description: '能使用发票工具创建并读取发票工具记录'
})
  • 返回数据

{
_id: '5e20082f4b6419665991fa57',
name: 'Invoice Submitter',
description: '能使用发票工具创建并读取发票工具记录',
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
}

分组(Group)和角色(Role)有什么区别?

  • 角色是一组权限的集合。

  • 分组侧重于管理用户,一个分组通常拥有多个角色,分组内的用户会继承分组内所有角色的所有权限。

常见的 Group 和 Role 示例:

  • Group

    • admin: 系统管理员,通常包含系统维护者。

    • employee: 正式雇员。

    • employer: 面试官。

    • hr

    • intern: 实习生

    • ops_engineer: 运维工程师

  • Role

    • Invoice Submitter: 具备发票报销的相关权限。

    • Vacation Requester: 具备申请假期的相关权限。

    • Corporation Email User: 具备使用公司邮箱的的相关权限。

    • Production Server Operator: 具备线上服务器的操作权限。

    • HR App User: 具备使用 HR 系统的相关权限。

举例来说:可以这样建立 Role 和 Group 之间的关系:

  • intern 具备 Corporation Email User 这个角色,但是不具备 Vacation Requester 和 Invoice Submitter 这两个角色。

  • employee 拥有发票报销和申请假期角色,但是不具备线上服务器的操作权限。

  • ops_engineer 拥有发票报销、申请假期、线上服务器的角色。

推荐使用 Group organize 用户,用 Role organize 权限,不要直接赋予单个用户某个权限。如果是某个用户临时需要具备某个角色,可以临时授予,结束之后再收回。

修改角色

Authing.authz.updateRole(input)

  • 参数

    • input <Object>

      • _id: 角色 ID,必填。

      • name: 角色名称,选填。

      • description:角色描述,选填。

  • 使用方法

const role = await authing.authz.updateRole({
_id: "5e20082f4b6419665991fa57",
name: "Invoice Submitter",
description: '能使用发票工具创建并读取发票工具记录。'
})
  • 返回数据

{
_id: '5e20082f4b6419665991fa57',
name: 'Invoice Submitter',
description: '能使用发票工具创建并读取发票工具记录。',
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
}

查询角色

Authing.authz.role(_id)

  • 参数

    • _id <string> 角色 ID,必填。

  • 使用方法

const role = await authing.authz.role("5e20082f4b6419665991fa57")
  • 返回数据

{
_id: '5e20082f4b6419665991fa57',
name: 'Invoice Submitter',
description: '能使用发票工具创建并读取发票工具记录。'
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
}

查询用户池角色列表

此方法支持分页、排序。

Authing.authz.roleList(options)

  • 参数

    • options <Object> 可选

      • sortBy <string> 排序方式,可选。默认为 CREATEDAT_DESC ,表示按照创建时间降序,也就是最新创建的排在最前面。全部的可选值为:

        • CREATEDAT_DESC:按照创建时间降序。

        • CREATEDAT_ASC :按照创建时间升序。

        • UPDATEDAT_DESC:按照修改时间降序。

        • UPDATEDAT_ASC:按照修改时间排序。

      • page <int> 页码,可选。默认为 0,zero-based。

      • count <int> 没页数目,可选。默认为 10。

  • 使用方法

const roleList = await authing.authz.roleList()
// 自定义排序方式 / 分页
const {totalCount, list} = await authing.authz.roleList({
sortBy: 'CREATEDAT_DESC',
page: 2,
count: 10
})
  • 返回数据

    • totalCount 总数

    • list 当前页列表

{
totalCount: 2,
list: [
{
_id: '5e20082f4b6419665991fa57',
name: 'Invoice Submitter',
description: '能使用发票工具创建并读取发票工具记录。'
},
{
_id: '5e20082f4b6419665991fa58',
name: 'Vacation Requester',
description: '能使用假期申请工具申请假期。'
},
]
}

删除角色

Authing.authz.deleteRole(_id)

  • 参数

    • _id 角色 ID,必填。

  • 使用方法

const res = await authing.authz.deleteRole("Role ID")
  • 返回数据

操作成功示例

{
message: '操作成功',
code: 200,
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

删除角色会将其与权限、用户之间的关系连带一起删除(权限、用户本身不会删除),不可撤回,请谨慎操作。

且此操作为原子化操作,要么成功,要么全部 rollback。

批量删除角色

Authing.authz.deleteRoleBatch(idList)

  • 参数

    • idList: <Array> 分组 ID 列表。

  • 使用方法

const res = await authing.authz.deleteRoleBatch([
"5e1fff324b6419665991f6b4",
"5e1edcb34b6419665991f5d9"
])
  • 返回参数

操作成功示例:

{
message: '操作成功',
code: 200
}

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

此操作不可撤回,请谨慎操作。

权限增删改查

创建权限

Authing.authz.createPermission(input)

  • 参数

    • input <Object>

      • name <string> 名称,必填。

      • description <string> 描述,选填。

  • 使用方法

const group = await authing.authz.createPermission({
name: 'invoice:submit',
description: "提交发票报销申请"
})
  • 返回数据

{
_id: '5e1edbd74b6419665991f51e',
name: 'invoice:submit',
description: '提交发票报销申请'
}

推荐使用 subject:action 这类形式命名权限。如:

  • invoice:submit 提交发票报销申请

  • invoice:revoke 撤回发票报销申请

  • invoice:update 修改发起申请详情

  • invoice:list 查看发起申请历史记录

  • invoice:read 查看发票申请详情

修改权限

Authing.authz.updatePermission(input)

  • 参数

    • input <Object>

      • _id: 角色 ID,必填。

      • name: 角色名称,选填。

      • description:角色描述,选填。

  • 使用方法

const role = await authing.authz.updatePermission({
_id: "5e20082f4b6419665991fa57",
name: "invoice:submit",
description: '提交发票报销申请。'
})
  • 返回数据

{
_id: '5e20082f4b6419665991fa57',
name: "invoice:submit",
description: '提交发票报销申请。'
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
}

查询权限

Authing.authz.permission(_id)

  • 参数

    • _id <string> 权限 ID,必填。

  • 使用方法

const group = await authing.authz.permission("5e20082f4b6419665991fa57")
  • 返回数据

{
_id: '5e20082f4b6419665991fa57',
name: "invoice:submit",
description: '提交发票报销申请。',
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
}

查询用户池权限列表

此方法支持分页、排序。

Authing.authz.permissionList(options)

  • 参数

    • options <Object> 可选

      • sortBy <string> 排序方式,可选。默认为 CREATEDAT_DESC ,表示按照创建时间降序,也就是最新创建的排在最前面。全部的可选值为:

        • CREATEDAT_DESC:按照创建时间降序。

        • CREATEDAT_ASC :按照创建时间升序。

        • UPDATEDAT_DESC:按照修改时间降序。

        • UPDATEDAT_ASC:按照修改时间排序。

      • page <int> 页码,可选。默认为 0,zero-based。

      • count <int> 没页数目,可选。默认为 10。

  • 使用方法

const permissionList = await authing.authz.permissionList()
const permissionList = await authing.authz.permissionList({
sortBy: 'CREATEDAT_DESC',
page: 2,
count: 10
})
  • 返回数据

    • totalCount 总数

    • list 当前页列表

{
totalCount: 1,
list: [
{
_id: '5e20082f4b6419665991fa57',
name: "invoice:submit",
description: '提交发票报销申请。',
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
}
]
}

删除权限

Authing.authz.deletePermission(_id)

  • 参数

    • _id 权限 ID,必填。

  • 使用方法

const res = await authing.authz.deletePermission("Permission ID")
  • 返回数据

操作成功示例

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

删除角色会将其与权限、用户之间的关系连带一起删除(权限、用户本身不会删除),不可撤回,请谨慎操作。

且此操作为原子化操作,要么成功,要么全部 rollback。

批量删除权限

Authing.authz.deletePermissionBatch(idList)

  • 参数

    • idList: <Array> 分组 ID 列表。

  • 使用方法

const res = await authing.authz.deletePermissionBatch([
"5e1fff324b6419665991f6b4",
"5e1edcb34b6419665991f5d9"
])
  • 返回参数

操作成功示例:

{
message: '操作成功',
code: 200
}

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

此操作不可撤回,请谨慎操作。

分组内角色管理

推荐使用 Group 管理用户,用 Role 管理权限,不要直接赋予单个用户某个权限。如果是某个用户临时需要具备某个角色,可以临时授予,结束之后再收回。

查询分组角色列表

Authing.authz.groupRoleList(_id)

  • 参数

    • _id <string> 分组 ID

  • 使用方法

const {totalCount, list} = await authing.authz.groupRoleList()
  • 返回数据

{
list: [
{
_id: '5e351f8815e7ca5a3577b6f7',
createdAt: '2020-02-01T14:49:44+08:00',
description: '描述',
name: '角色itbv3w6jrgk',
updatedAt: '2020-02-01T14:49:44+08:00',
},
],
totalCount: 1,
}

分组添加角色

Authing.authz.addRoleToGroup(input, options)

  • 参数:

    • input <Object> 必填

      • groupId: <string> 分组 ID,必填。

      • roleId: <string> 角色 ID,必填。

    • options <Object> 选填

      • fetchRoles <boolean> 是否在结果中返回最新的角色列表。选填,默认为 false。

  • 使用方法

// 默认,不返回最新的角色列表
const res = await authing.authz.addRoleToGroup({
roleId: "xxx",
groupId: "xxx"
})
const res = await authing.authz.addRoleToGroup({
roleId: "xxx",
groupId: "xxx"
}, {
fetchRoles: true
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}
// 返回最新角色列表
{
code: 200,
message: '操作成功',
data: {
totalCount: 1,
list: [
{
createdAt: '2020-01-16T20:47:04+08:00',
updatedAt: '2020-01-16T20:47:04+08:00'
}
]
}
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

分组删除角色

authing.authz.removeRoleFromGroup(input, options)

  • 参数

    • input <Object>

      • groupId 分组 ID,必填。

      • roleId 角色 ID, 必填。

    • options <Object> 选填

      • fetchRoles <boolean> 是否在结果中返回最新的角色列表。选填,默认为 false。

  • 使用方法

await authing.authz.removeRoleFromGroup({
roleId: "xxx",
groupId: "xxx"
})
const res = await authing.authz.removeRoleFromGroup({
roleId: "xxx",
groupId: "xxx"
}, {
fetchRoles: true
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}
// 返回最新角色列表
{
code: 200,
message: '操作成功',
data: {
totalCount: 1,
list: [
{
_id: '5e2148ddce7f3e37be7c86d4',
createdAt: '2020-01-17T13:40:45+08:00',
description: '描述',
name: '角色km4ia4a7a4o',
updatedAt: '2020-01-17T13:40:45+08:00',
}
]
}
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

分组批量添加角色

Authing.authz.addRoleToGroupBatch(input, options)

  • 参数:

    • input <Object> 必填

      • groupId: 分组 ID,必填。

      • roleIdList: 角色 ID 列表,必填。

    • options <Object> 选填

      • fetchRoles <boolean> 是否在结果中返回最新的角色列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.addRoleToGroupBatch({
roleIdList: [
"id1",
"id2"
],
groupId: "id"
})
const res = await authing.authz.addRoleToGroupBatch({
roleIdList: [
"id1",
"id2"
],
groupId: "id"
}{
fetchRoles: true
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}
// 返回最新的角色列表
{
message: '操作成功',
code: 200,
data: {
list: [
{
_id: '5e2148ddce7f3e37be7c86d4',
createdAt: '2020-01-17T13:40:45+08:00',
description: '描述',
name: '角色km4ia4a7a4o',
updatedAt: '2020-01-17T13:40:45+08:00',
},
{
_id: '5e2148ddce7f3e37be7c86d2',
createdAt: '2020-01-17T13:40:45+08:00',
description: '描述',
name: '角色fwhlsn81uku',
updatedAt: '2020-01-17T13:40:45+08:00',
},
{
_id: '5e2148ddce7f3e37be7c86ca',
createdAt: '2020-01-17T13:40:45+08:00',
description: '描述',
name: '角色7eoxpb0km7y',
updatedAt: '2020-01-17T13:40:45+08:00',
},
{
_id: '5e2148ddce7f3e37be7c86c9',
createdAt: '2020-01-17T13:40:45+08:00',
description: '描述',
name: '角色gqgp9vzfey',
updatedAt: '2020-01-17T13:40:45+08:00',
},
],
totalCount: 4,
}
}

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

分组批量删除角色

Authing.authz.removeRoleFromGroupBatch(input, options)

  • 参数

    • input <Object> 必填

      • groupId: 分组 ID,必填。

        roleIdList: 角色 ID 列表,必填。

    • options <object> 选填

      • fetchRoles <boolean> 是否在结果中返回最新的角色列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.removeRoleFromGroupBatch({
roleIdList: [
"id1",
"id2"
],
groupId: "id"
})
const res = await authing.authz.removeRoleFromGroupBatch({
roleIdList: [
"id1",
"id2"
],
groupId: "id"
}, {
fetchRoles: true
})
  • 返回参数

操作成功示例:

{
message: '操作成功',
code: 200
}
// 返回最新角色列表
{
code: 200,
message: '操作成功',
data: {
totalCount: 1,
list: [
{
_id: '5e2148ddce7f3e37be7c86d4',
createdAt: '2020-01-17T13:40:45+08:00',
description: '描述',
name: '角色km4ia4a7a4o',
updatedAt: '2020-01-17T13:40:45+08:00',
}
]
}
}

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

此操作不可撤回,请谨慎操作。

分组内用户管理

查询分组内用户列表

此方法支持分页、排序。

Authing.authz.groupUserList(_id, options)

  • 参数

    • _id: 分组ID

    • options <Object> 可选

      • sortBy <string> 排序方式,可选。默认为 CREATEDAT_DESC ,表示按照创建时间降序,也就是最新创建的排在最前面。全部的可选值为:

        • CREATEDAT_DESC:按照创建时间降序。

        • CREATEDAT_ASC :按照创建时间升序。

        • UPDATEDAT_DESC:按照修改时间降序。

        • UPDATEDAT_ASC:按照修改时间排序。

      • page <int> 页码,可选。默认为 0,zero-based。

      • count <int> 没页数目,可选。默认为 10。

  • 使用方法

const {totalCount, list} = await authing.authz.groupUserList("xxxx")
// 或者
const {totalCount, list} = await authing.authz.groupUserList("xxx", {
sortBy: 'CREATEDAT_DESC',
page: 2,
count: 10
})
  • 返回数据

    • totalCount 总数

    • list 当前页列表

{
list: [
{
_id: '5e35239215e7ca5a3577b8af',
blocked: false,
browser: '',
company: '',
email: 'o2sozsya3mm@authing.cn',
emailVerified: false,
isDeleted: false,
lastIP: null,
lastLogin: '2020-02-01T15:06:58+08:00',
loginsCount: 0,
nickname: '',
oauth: '',
phone: '',
photo: 'https://usercontents.authing.cn/authing-avatar.png',
registerInClient: '5e1be38ab1599657b6477022',
registerMethod: 'default:username-password',
signedUp: '2020-02-01T15:06:58+08:00',
token: null,
tokenExpiredAt: 'Invalid date',
unionid: null,
userLocation: null,
userLoginHistory: null,
username: 'o2sozsya3mm@authing.cn',
},
],
totalCount: 15,
}

分组添加用户

Authing.authz.addUserToGroup(input, options)

  • 参数:

    • input <Object>

      • groupId: 分组 ID,必填。

      • userId: 用户 ID,必填。

    • options <object> 选填

      • fetchUsers <boolean> 是否在结果中返回最新的用户列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.addUserToGroup({
userId: "",
groupId: ""
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

分组删除用户

Authing.authz.removeUserFromGroup(input, options)

  • 参数:

    • input: <Object>

      • groupId: <string> 分组 ID,必填。

      • userId: <string> 用户 ID,必填。

    • options <object> 选填

      • fetchUsers <boolean> 是否在结果中返回最新的用户列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.removeUserFromGroup({
userId: "",
groupId: ""
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

分组批量添加用户

Authing.authz.addUserToGroupBatch(input, options)

  • 参数:

    • input: <Object>

      • groupId: 分组 ID,必填。

      • userIdList: 用户 ID,必填。

    • options <object> 选填

      • fetchUsers <boolean> 是否在结果中返回最新的用户列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.addUserToGroup({
userIdList: ["", ""],
groupId: ""
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

分组批量删除用户

Authing.authz.removeUserFromGroupBatch(input, options)

  • 参数:

    • input: <Object>

      • groupId: 分组 ID,必填。

      • userIdList: 用户 ID 列表,必填。

    • options <object> 选填

      • fetchUsers <boolean> 是否在结果中返回最新的用户列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.removeUserFromGroupBatch({
userIdList: ["", ""],
groupId: ""
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

此操作不可撤回,请谨慎操作。

角色内用户管理

查询具备某角色的用户列表

此方法支持分页、排序。

Authing.authz.roleUserList(_id, options)

  • 参数

    • _id: 角色ID

    • options <Object> 可选

      • sortBy <string> 排序方式,可选。默认为 CREATEDAT_DESC ,表示按照创建时间降序,也就是最新创建的排在最前面。全部的可选值为:

        • CREATEDAT_DESC:按照创建时间降序。

        • CREATEDAT_ASC :按照创建时间升序。

        • UPDATEDAT_DESC:按照修改时间降序。

        • UPDATEDAT_ASC:按照修改时间排序。

      • page <int> 页码,可选。默认为 0,zero-based。

      • count <int> 没页数目,可选。默认为 10。

  • 使用方法

const {totalCount, list} = await authing.authz.roleUserList("xxxx")
// 或者
const {totalCount, list} = await authing.authz.roleUserList("xxx", {
sortBy: 'CREATEDAT_DESC',
page: 2,
count: 10
})
  • 返回数据

    • totalCount 总数

    • list 当前页列表

{
list: [
{
_id: '5e35239215e7ca5a3577b8af',
blocked: false,
browser: '',
company: '',
email: 'o2sozsya3mm@authing.cn',
emailVerified: false,
isDeleted: false,
lastIP: null,
lastLogin: '2020-02-01T15:06:58+08:00',
loginsCount: 0,
nickname: '',
oauth: '',
phone: '',
photo: 'https://usercontents.authing.cn/authing-avatar.png',
registerInClient: '5e1be38ab1599657b6477022',
registerMethod: 'default:username-password',
signedUp: '2020-02-01T15:06:58+08:00',
token: null,
tokenExpiredAt: 'Invalid date',
unionid: null,
userLocation: null,
userLoginHistory: null,
username: 'o2sozsya3mm@authing.cn',
},
],
totalCount: 15,
}

授权用户某角色

Authing.authz.assignRoleToUser(input, options)

  • 参数:

    • options <Object> 必填

      • userId: <string> 用户 ID,必填。

      • roleId: <string> 角色 ID,必填。

    • input <Object> 选填

      • fetchUsers <boolean> 是否在结果中返回角色中包含的最新用户列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.assignRoleToUser({
roleId: "",
userId: ""
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

一个用户最多同时具有 50 个角色。

批量授权用户某角色

Authing.authz.assignRoleToUserBatch(input, options)

  • 参数:

    • input <Object> 必填

      • userId: <string> 用户 ID,必填。

      • roleId: <string> 角色 ID,必填。

    • options <Object> 选填

      • fetchUsers <boolean> 是否在结果中返回角色中包含的最新用户列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.assignRoleToUserBatch({
roleId: "",
userIdList: []
})
// 返回最新列表
const res = await authing.authz.assignRoleToUserBatch({
roleId: "",
userIdList: []
}, {
fecthUsers: true
)
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

撤权用户某角色

Authing.authz.revokeRoleFromUser(input, options)

  • 参数:

    • input <Object> 必填

      • userId: <string> 用户 ID,必填。

      • roleId: <string> 角色 ID,必填。

    • options <Object> 选填

      • fetchUsers <boolean> 是否在结果中返回角色中包含的最新用户列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.revokeRoleFromUser({
roleId: "",
userId: ""
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

批量撤权用户某角色

Authing.authz.revokeRoleFromUser(input, options)

  • 参数:

    • input <Object> 必填

      • userId: <string> 用户 ID,必填。

      • roleId: <string> 角色 ID,必填。

    • options <Object> 选填

      • fetchUsers <boolean> 是否在结果中返回角色中包含的最新用户列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.revokeRoleFromUser({
roleId: "",
userIdList: []
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

角色内权限管理

查询某角色具备的所有权限

此方法支持分页、排序。

Authing.authz.rolePermissionList(_id)

  • 参数

    • _id: <string> 角色ID

  • 使用方法

const {totalCount, list} = await authing.authz.rolePermissionList("xxxx")
// 或者
const {totalCount, list} = await authing.authz.rolePermissionList("xxx"})
  • 返回数据

    • totalCount 总数

    • list 当前页列表

{
list: [
{
_id: '5e35259315e7ca5a3577b9d9',
createdAt: '2020-02-01T15:15:31+08:00',
description: '描述',
name: '权限cassasb4vz',
updatedAt: '2020-02-01T15:15:31+08:00',
},
],
totalCount: 1,
}

角色添加权限

Authing.authz.addPermissionToRole(input, options)

  • 参数:

    • input <Object>

      • permissionId: <string> 权限 ID,必填。

      • roleId: <string> 角色 ID,必填。

    • options <object> 选填

      • fetchPermissions <boolean> 是否在结果中返回最新的权限列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.addPermissionToRole({
roleId: "",
permissionId: ""
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

角色批量添加权限

Authing.authz.addPermissionToRoleBatch(input, options)

  • 参数:

    • input <Object>

      • permissionIdList: <Array> 权限 ID 列表,必填。

      • roleId: <string> 角色 ID,必填。

    • options <object> 选填

      • fetchPermissions <boolean> 是否在结果中返回最新的权限列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.addPermissionToRole({
roleId: "",
permissionIdList: ["",""]
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

角色删除权限

Authing.authz.removePermissionFromRole(input, options)

  • 参数:

    • input <Object>

      • permissionId: <string> 权限 ID,必填。

      • roleId: <string> 角色 ID,必填。

    • options <object> 选填

      • fetchPermissions <boolean> 是否在结果中返回最新的权限列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.removePermissionFromRole({
roleId: "",
permissionId: ""
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

角色批量删除权限

Authing.authz.removePermissionFromRoleBatch(input, options)

  • 参数:

    • input <Object>

      • permissionId: <string> 权限 ID,必填。

      • roleId: <string> 角色 ID,必填。

    • options <object> 选填

      • fetchPermissions <boolean> 是否在结果中返回最新的权限列表。选填,默认为 false。

  • 使用方法

const res = await authing.authz.removePermissionFromRoleBatch({
roleId: "",
permissionIdList: ["",""]
})
  • 返回数据

操作成功示例:

{
message: '操作成功',
code: 200
}

如果操作失败,需要使用 try catch 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 try/catch 捕获异常,详情见异常处理部分。

错误码

角色权限管理的相关错误码以 39xx 开头。

如何获取错误码? 如下所示:

try {
const group = await authing.authz.group("NOGTEXIST")
} catch (error) {
const errcode = error.message.code
assert(errcode === 3901)
}

错误码

说明

2020

尚未登录,无访问权限

3901

Group 不存在

3902

无权操作此 Group

3903

Role 不存在

3904

无权操作此 Role

3905

Permission 不存在

3906

无权操作此 Permission

3907

删除 Group 失败

3910

Role ${role.name} 已在 Group ${group.name} 中了

3911

Role ${role.name} 不在 Group ${group.name} 中

3912

User ${user._id} 已在 Group ${group.name} 中了

3913

User ${user._id} 不在 Group ${group.name} 中

3914

删除 Permission 失败

3915

删除 Role 失败

3916

Permission ${permission.name} 已在 Role ${role.name} 中了

3917

Permission ${permission.name} 不在 Role ${role.name} 中

3918

User ${user._id} 已具备 Role ${role.name}

3919

User ${user._id} 不具备 Role ${role.name}