本頁面由 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`
[Organizational Units] (機構單位)	`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。
如果您是經銷商且能取得您其中一個客戶的權限，請使用 Fetch user 作業傳回的客戶 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 主體 (如身分與存取權管理 (IAM) 中所定義)、roleId (如取得現有角色) 和 scope_type 中所述。
如要將角色指派給群組，請新增包含 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 新增 JSON 主體，此物件可透過 users.get()、roleId、取得現有角色一節所述的 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'"
}