管理用户角色和用户组¶

1.0 简介¶

角色和用户组可以扩展 Authany 为您的应用提供的访问管理能力。Authany 会在 UserInfo 端点的响应以及 JWT 访问令牌中包含用户的角色信息。

下面这个例子展示了如何使用角色为应用的不同用户群体提供不同的功能和界面。假设您有一个为交通运输业务提供支持的应用 XYZ，该应用拥有 admin、driver 和 passenger 三种角色。您可以使用 Authany 在 UserInfo 或 JWT 访问令牌中返回的值，仅向拥有 admin 角色的用户开放管理司机的功能。同样，您可以只允许拥有 driver 角色的用户查看管理车辆、乘客和行程的功能。最后，您可以限制拥有 passenger 角色的用户只能查看自己的车票和行程详情。

接下来，您将学习如何为 Authany 项目创建角色和用户组，以及如何管理它们。

您可以在 Authany 项目中创建一个用户组，并为该用户组添加一个或多个角色。用户组和角色都可以应用到用户身上。例如，如果您的 Authany 项目具有以下角色：

management
department_lead
team_member

以及一个 managers 用户组，您可以将 management 和 department_lead 角色添加到该用户组。这样，将用户加入 managers 用户组后，该用户就会同时获得 management 和 department_lead 两个角色。

下图展示了 Authany 中用户组、角色和用户之间的核心关系。

1.1 角色和用户组的属性¶

每个角色或用户组都有三个描述性属性，包括必填的 key，以及可选的 name 和 description。

1. 角色/用户组 Key¶

key 属性是角色或用户组的标识符。key 的值就是 Authany 在用户的 UserInfo 和 JWT 访问令牌中包含的内容。有效的 key 必须满足以下条件：

key 的值不能为空。
key 的长度必须在 1 到 40 个字符之间。
有效字符为 [a-zA-Z0-9:_]。
前缀 authgear: 保留给 Authany 内部使用。

以下是一些有效 key 的示例：

reader
app:editor
store_manager

2. 名称¶

名称是角色或用户组的可选标签，其值会显示在 Authany 管理台中。名称对字符的限制较宽松，例如可以包含空格。

3. 描述¶

描述也是可选属性，您可以用它补充角色或用户组的更多信息。

接下来，我们将介绍如何为您的项目创建角色和用户组。

1.2 UserInfo 端点响应中的角色示例¶

以下 JSON 文档展示了当您的应用请求 UserInfo 时，角色是如何返回的：

{
  "custom_attributes": [],
  "email": "user@example.com",
  "email_verified": true,
  "family_name": "John",
  "gender": "male",
  "given_name": "Doe",
  "https://authgear.com/claims/user/can_reauthenticate": true,
  "https://authgear.com/claims/user/is_anonymous": false,
  "https://authgear.com/claims/user/is_verified": true,
  "https://authgear.com/claims/user/roles": [
    "department_lead",
    "team_member"
  ],
  "sub": "e3079029-f230-4c24-91c1-c2cd63a6a4af",
  "updated_at": 1694947082,
  "x_web3": {
    "accounts": []
  }
}

https://authgear.com/claims/user/roles 属性的值是一个数组，包含当前用户的角色。

2.0 如何创建新角色¶

您可以根据自身需求和使用场景，为 Authany 项目创建角色。您可以通过 Authany 管理台，或使用 Admin API（通过 GraphQL）创建新角色。

2.1 通过 Authany 管理台创建角色¶

请按照以下步骤，通过管理台在 Authany 项目中创建新角色。

步骤 1¶

首先登录 Authany 管理台，选择您的项目，然后进入 用户管理 > 角色，打开角色页面。

步骤 2¶

点击角色页面中间的 创建角色 按钮（如果已有角色，则该按钮位于右上角），开始创建新角色。

在对应字段中输入新角色的名称、角色 Key 和描述，然后点击表单底部的创建按钮，完成新角色的创建。

重复上述步骤即可添加更多角色。

2.2 使用 Admin API 创建角色¶

如前所述，您也可以使用 Admin API 创建新角色。本节将介绍具体步骤。

步骤 1¶

在自定义代码中设置与 Admin API GraphQL 端点交互所需的授权。或者使用 Authany 提供的 GraphiQL Explorer（在 Authany 管理台中进入高级 > Admin API > GraphiQL Explorer 即可访问）。

步骤 2¶

运行以下 mutation 创建新角色：

QueryResponse

mutation {
  createRole(input: { key:"department_lead", name:"Team Lead", description: "Role for a leader of a specific department" }) {
    role {
      id
      key
    }
  }
}

{
  "data": {
    "createRole": {
      "role": {
        "id": "Um9sZTozNDM5MWQ1Ni00OTEwLTQ1ZDAtOTI1Yi1lMjQxODFhYmMxODc",
        "key": "department_lead"
      }
    }
  }
}

3.0 如何创建新用户组¶

与角色类似，您需要自行为 Authany 项目创建用户组。您可以通过 Authany 管理台或使用 Admin API 创建新用户组。

3.1 通过 Authany 管理台创建用户组¶

通过管理台创建新用户组的步骤与创建角色类似，具体如下：

步骤 1¶

首先登录 Authany 管理台，选择您的项目，然后进入 用户管理 > 用户组，打开 用户组 页面。

步骤 2¶

点击屏幕中间的 创建用户组 按钮（如果已有用户组，则该按钮位于右上角），打开 创建用户组 表单。

在用户组创建表单中输入名称、用户组 Key 和描述，然后点击创建按钮完成创建。

3.2 使用 Admin API 创建用户组¶

您也可以使用 Admin API GraphQL 创建新用户组。以下指南展示了具体步骤。

步骤 1¶

编写您自己的自定义代码，使其能够访问 Admin API 端点。您也可以使用 Authany 管理台中的 GraphiQL Explorer（进入高级 > Admin API > GraphiQL Explorer）。

步骤 2¶

执行以下 GraphQL mutation 创建新用户组：

QueryResponse

mutation {
  createGroup(input: { key:"managers", name:"Managers", description: "Group for managers with access to all departments" }) {
    group {
      id
      key
    }
  }
}

{
  "data": {
    "createGroup": {
      "group": {
        "id": "R3JvdXA6NDM2ZDg4OTctMmNjYi00ZjQ3LWJiOGYtN2U2MzE4ZTVhNDM3",
        "key": "managers"
      }
    }
  }
}