管理角色

您可以使用 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 預先建立的管理員角色預設為全機構範圍。進一步瞭解可在 OU 層級指派的權限限制。

群組的角色和角色指派有下列限制：

  • 您可以指派超級管理員以外的任何角色。
  • 您可以在整個 OU 和每個 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
[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。

  • 如果您是經銷商，並要為某位客戶取得權限，請使用擷取使用者作業傳回的客戶 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 (如 Get existing roles 所述) 和 scope_type。

  • 如要將角色指派給群組，請新增 JSON 主體，並加入群組的 group_id，您可以從 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()、Get existing roles 中所述的 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'"
}