此页面由 Cloud Translation API 翻译。

管理角色

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

以下是 Directory API 关于 Google Workspace 中 RBAC 的常用术语的列表：

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

角色和角色分配限制

您只能创建有限数量的自定义角色或角色分配，因此，如果相应角色或角色分配接近上限，请合并或移除它们以确保不超出该限制。角色和角色分配具有以下限制：

您可以为整个组织创建多达 750 个自定义角色。
您最多可以为每个组织部门 (OU) 创建 500 个角色分配，其中根组织被视为一个单元。例如，您可以在根组织中分配 350 个角色，在已定义的其他组织部门（例如公司某个部门）中分配 400 个角色。所有预构建的 Google Workspace 管理员角色都默认为组织范围。详细了解可在组织部门级别分配的权限限制。

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

您可以分配除超级用户以外的任何角色。
您最多可以向整个组织部门和每个组织部门中的群组分配 250 个角色。
该群组必须是贵组织的安全群组。
我们建议您仅限组织中的用户拥有群组成员资格。您可以添加组织外部的用户，但他们可能不会获得角色权限。如需了解详情，请参阅限制群组成员资格。

为群组分配角色

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

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 中获取。
如需将角色分配给服务帐号，请添加包含服务帐号的 unique_id（如 Identity and Access Management (IAM) 中所定义）、roleId（如获取现有角色中所述）和 scope_type 的 JSON 正文。
如需将角色分配给群组，请添加包含群组 group_id 的 JSON 正文，可从 groups.get()、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) 上的操作者 (assignedTo)。

如需将角色分配给用户，请使用以下 POST 方法并包含向请求授权中所述的授权。

添加 JSON 正文以及用户的 user_id（可以从 users.get() 获取）、roleId（如获取现有角色中所述）以及 condition。必须完整使用这两个条件字符串，如下所示，并且它们仅适用于 Groups Editor 和 Groups Reader 预构建的管理员角色。这些条件遵循 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'"
}