此页面由 Cloud Translation API 翻译。

管理角色

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

以下是 Directory API 在 Google Workspace 中使用的一些与 RBAC 相关的常用术语：

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

角色和角色分配限制

您只能创建有限数量的自定义角色或角色分配，因此，如果您即将达到上限，请整合或移除这些角色，以保持在上限范围内。角色和角色分配存在以下限制：

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

对于群组，角色和角色分配存在以下限制：

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

如果您需要在组织部门中分配 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`

使用场景示例

准备工作

在运行本指南中的示例之前，请设置身份验证和授权。

配置 OAuth 同意屏幕。
创建访问凭据。

获取网域权限列表

如需获取网域中受支持的权限的分页列表，请使用 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 方法，并添加授权请求中所述的授权。

如需向用户分配角色，请添加包含以下内容的 JSON 正文：用户的 user_id（可从 users.get() 获取）、roleId（如获取现有角色中所述）和 scope_type。
如需向服务账号分配角色，请添加一个 JSON 正文，其中包含服务账号的 unique_id（如 Identity and Access Management (IAM) 中所定义）、roleId（如获取现有角色中所述）和 scope_type。
如需将角色分配给群组，请添加包含群组 group_id 的 JSON 正文（您可以从 groups.get() 中获取该 group_id）、roleId（如获取现有角色中所述）和 scope_type。

请求

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) 内的 actor (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'"
}

响应