管理角色

借助 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_UPDATEORGANIZATION_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 状态代码。除了状态代码之外,该响应还会返回网域中分配的所有角色,以及 assigneeTypeuser 还是 group

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

创建角色

如需创建新角色,请使用以下 POST 请求并添加为请求授权中所述的授权。为应授予此角色的每项权限分别添加一个 privilegeNameserviceId。如需了解请求和响应属性,请参阅 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 方法并包含向请求授权中所述的授权。

添加包含用户的 user_id(您可以从 users.get() 获取)的 JSON 正文、获取现有角色中所述的 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'"
}