管理角色

借助 Directory API，您可以使用基于角色的访问权限控制 (RBAC) 来管理对 Google Workspace 网域中功能的访问权限。您可以创建具有权限的自定义角色，以比 Google Workspace 提供的预构建角色更具体地限制管理员访问权限。您可以向用户或安全群组分配角色。本指南介绍了如何执行一些与角色相关的基本任务。

以下是 Directory API 在 Google Workspace 中针对 RBAC 使用的常用术语列表：

权限
在 Google Workspace 网域中执行任务或操作所需的权限。由 Privilege 资源表示。此资源未关联任何持久性数据。
角色
一组权限，用于向具有相应角色的实体授予执行特定任务或操作的权限。由 Role 资源表示。
角色分配
向用户或群组授予的特定角色的记录。由 RoleAssignment 资源表示。
安全组
一种 Cloud Identity 群组，用于控制对组织资源的访问权限。安全群组可以同时包含个人用户和群组。

角色和角色分配限制

您只能创建一定数量的自定义角色或角色分配，因此如果您即将达到上限，请合并或移除这些角色，以免超出上限。角色和角色分配存在以下限制：

  • 您最多可以为整个组织创建 750 个自定义角色。
  • 您最多可为每个组织部门 (OU) 创建 1,000 项角色分配，其中根组织也被视为一个部门。例如，您可以在根组织中分配 600 个角色，并在您定义的其他 OU（例如公司部门）中分配 700 个角色。所有 Google Workspace 预构建的管理员角色均默认设为组织级范围。详细了解可在 OU 级别分配的权限限制。

群组的角色和角色分配存在以下限制：

  • 您可以分配除超级用户以外的任何角色。
  • 在整个组织部门级别和每个组织部门中，您总共最多可以向群组执行 250 次角色分配操作。
  • 群组必须是贵组织的安全群组。
  • 我们建议将群组成员资格限制为组织中的用户。您可以添加贵组织外部的用户，但这些用户可能无法获得角色特权。有关详情，请参阅限制群组成员资格。### 向群组分配角色

如果您需要在 OU 中分配 1000 个以上的角色，则可以向安全群组添加多个成员，并为群组分配角色。群组角色分配有一些额外的限制，如需了解具体信息，请参阅管理员帮助中心。

Google 管理控制台角色与权限的映射

如需为通过管理控制台访问权限的用户分配角色，您可能需要授予某些额外权限。例如，若要向用户授予通过管理控制台创建其他用户的权限，不仅需要 USERS_CREATE 权限，还需要 USERS_UPDATE 和 ORGANIZATION_UNITS_RETRIEVE 权限。下表将管理控制台功能与管理用户和组织部门所需的权限授予进行了对应。

管理控制台功能 所需权限
组织部门 - 读取 ORGANIZATION_UNITS_RETRIEVE
组织部门 - 创建 ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE
组织部门 - 更新 ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE
组织部门 - 删除 ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE
单位部门 ORGANIZATION_UNITS_ALL
用户 - 读取 USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
用户 - 创建 USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
用户 - 更新 USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
用户 - 移动用户 USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
用户 - 重命名用户 USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
用户 - 重置密码 USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
用户 - 强制更改密码 USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
用户 - 添加/移除别名 USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
用户 - 暂停用户 USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
群组 GROUPS_ALL
安全 - 用户安全管理 USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE

使用场景示例

准备工作

完成 Google Workspace 的身份验证和授权步骤。

获取网域权限列表

如需获取网域中受支持特权的分页列表，请使用 privileges.list() 方法。

  • 如果您是管理员，并在自己的网域中获得权限，请使用 my_customer 作为客户 ID。

  • 如果您是转销商，要为某个客户获取权限，请使用获取用户操作返回的客户 ID。

请求

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

响应

成功的响应会返回 HTTP 200 状态代码。除了状态代码以外，响应还会返回网域中支持的特权：

{
  "kind": "admin\#directory\#privileges",
  "etag": ...,
  "items": [
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "02afmg282jiquyg",
      "privilegeName": "APP_ADMIN",
      "isOuScopable": false
    },
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "04f1mdlm0ki64aw",
      "privilegeName": "MANAGE_USER_SETTINGS",
      "isOuScopable": true,
      "childPrivileges": [
        {
          "kind": "admin\#directory\#privilege",
          "etag": ...,
          "serviceId": "04f1mdlm0ki64aw",
          "privilegeName": "MANAGE_APPLICATION_SETTINGS",
          "isOuScopable": true
        }
      ]
    },
    ...
  ]
}

获取现有角色

如需获取现有角色的列表，请使用以下 GET 请求，并在其中添加授权请求中所述的授权。

  • 如果您是管理员，要在自己的网域中获取角色，请使用 my_customer 作为客户 ID。

  • 如果您是转销商，则使用通过获取用户操作获取的客户 ID。

请求

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

响应

成功的响应会返回 HTTP 200 状态代码。除了状态代码以外，响应还会返回网域中存在的角色：

{
  "kind": "admin\#directory\#roles",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/DywA6_jaJCYw-f0lFs2-g17UWe8\"",
  "items": [
    {
      "kind": "admin\#directory\#role",
      "etag": ... ,
      "roleId": "3894208461012993",
      "roleName": "_SEED_ADMIN_ROLE",
      "roleDescription": "Google Workspace Administrator Seed Role",
      "rolePrivileges": [
        {
          "privilegeName": "SUPER_ADMIN",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ROOT_APP_ADMIN",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_APIS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        ...
      ],
      "isSystemRole": true,
      "isSuperAdminRole": true
    },
    {
      "kind": "admin\#directory\#role",
      "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/bTXiZXfuK1NGr_f4paosCWXuHmw\"",
      "roleId": "3894208461012994",
      "roleName": "_GROUPS_ADMIN_ROLE",
      "roleDescription": "Groups Administrator",
      "rolePrivileges": [
        {
          "privilegeName": "CHANGE_USER_GROUP_MEMBERSHIP",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "USERS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "GROUPS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_DASHBOARD",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ORGANIZATION_UNITS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        }
      ],
      "isSystemRole": true
    },
    ...
  ]
}

列出所有角色分配

如需获取所有直接角色分配的分页列表，请使用 roleAssignments.list() 方法。设置 userKey 参数后，API 可能会返回包含页面令牌的空结果。您应继续分页，直到系统不再返回页面令牌。

  • 如果您是管理员，并且要在自己的网域中获取角色分配，请使用 my_customer 作为客户 ID。

  • 如果您是转销商，要获取某个客户的角色分配信息，请使用获取用户操作返回的客户 ID。

请求

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

响应

成功的响应会返回 HTTP 200 状态代码。除了状态代码以外，响应还会返回在该网域中分配的所有角色：

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

列出所有间接角色分配

如需获取所有角色分配（包括因用户所属的群组而间接分配给用户的角色）的分页列表，请使用 roleAssignments.list() 方法。

API 可能会返回包含页面令牌的空结果。您应继续分页，直到系统不再返回页面令牌。

  • 如果您是管理员，并且要在自己的网域中获取角色分配，请使用 my_customer 作为客户 ID。

  • 如果您是转销商，要获取某个客户的角色分配信息，请使用获取用户操作返回的客户 ID。

  • 将 USER_KEY 替换为用于在 API 请求中标识用户的值。如需了解详情，请参阅 users.get。

请求

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

响应

成功的响应会返回 HTTP 200 状态代码。除了状态代码以外，响应还会返回在网域中分配的所有角色，以及 assigneeType 是 user 还是 group：

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

创建角色

如需创建新角色，请使用以下 POST 请求，并在其中添加为请求授权中所述的授权。为应通过此角色授予的每个权限添加 privilegeName 和 serviceId。如需了解请求和响应属性，请参阅 API 参考文档。

请求

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

{
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

响应

成功的响应会返回 HTTP 200 状态代码。除了状态代码以外，响应还会返回新角色的属性：

{
  "kind": "admin\#directory\#role",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/uX9tXw0qyijC9nUKgCs08wo8aEM\"",
  "roleId": "3894208461013031",
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

创建角色分配

如需分配角色，请使用以下 POST 方法，并在其中添加授权请求中所述的授权。

  • 如需向用户分配角色，请添加包含用户 user_id 的 JSON 正文，您可以从 users.get()、roleId（如获取现有角色中所述）和 scope_type 获取 user_id。

  • 如需向服务账号分配角色，请添加 JSON 正文，其中包含服务账号的 unique_id（如 Identity and Access Management (IAM) 中所定义）、roleId（如获取现有角色中所述）和 scope_type。

  • 如需向群组分配角色，请添加包含群组 group_id 的 JSON 正文，您可以从 groups.get()、roleId（如获取现有角色中所述）和 scope_type 获取 group_id。

请求

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

响应

成功的响应会返回 HTTP 200 状态代码。除了状态代码以外，响应还会返回新角色分配的属性：

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

创建带有条件的角色分配

您可以授予角色来执行符合特定条件的操作。目前仅支持两种条件：

  • 仅适用于安全群组
  • 不适用于安全群组

设置 condition 后，只有当要访问的资源满足相应条件时，它才会生效。如果 condition 为空，系统会将角色 (roleId) 无条件地应用于作用域 (scopeType) 中的操作者 (assignedTo)。

如需向用户分配角色，请使用以下 POST 方法，并在其中添加授权请求中所述的授权。

添加一个 JSON 正文，其中包含用户的 user_id（可从 users.get() 获取）、获取现有角色中所述的 roleId 和 condition。这两个条件字符串必须照原样使用（如下所示），并且仅适用于“群组编辑者”和“群组读者”预构建的管理员角色。这些条件遵循 Cloud IAM 条件语法。

请求

仅适用于安全群组
POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}
不适用于安全群组
POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}

响应

成功的响应会返回 HTTP 200 状态代码。除了状态代码以外，响应还会返回新角色分配的属性：

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}