管理角色

Directory API 可讓您 角色式存取權控管 (RBAC) ，管理 Google Workspace 網域功能的存取權。您可以建立 具備權限的自訂角色，可更明確地限制管理員存取權 預先建立的角色你可以指派角色 提供給使用者或安全性群組本指南說明如何執行 基本角色相關任務

以下是 Directory API 搭配 有關 Google Workspace 中的 RBAC：

權限

在叢集內執行工作或作業所需的權限 Google Workspace 網域。代表 Privilege 資源。有 則是與這項資源相關聯的永久資料。

角色

一組授予實體該角色的權限 執行特定工作或作業的能力代表 Role 資源。

角色指派

指派給使用者或群組的特定角色記錄。代表 RoleAssignment 資源。

安全性群組

一種 Cloud Identity 群組 用於控管機構對應用程式的 再複習一下，機構節點 是所有 Google Cloud Platform 資源的根節點安全性群組可包含個別使用者和群組。

角色和角色指派限制

您只能建立有限數量的自訂角色或指派角色。 即將達到上限，請整併或移除這些規則，以免超過 我們會自動向帳單帳戶扣款 並每月或在您達到用量上限時發送帳單角色和角色指派具有以下限制：

• 您可以為整個機構建立最多 750 個自訂角色。
• 每個最多可建立 1000 個角色指派設定 機構單位 (OU)，根機構視同單位。 舉例來說，您可以在根機構指派 600 個角色和 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
[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

應用實例範例

事前準備

完成 驗證與授權 步驟。

取得網域權限清單

如要取得網域中支援權限的分頁清單，請使用 privileges.list()敬上 方法。

• 如果您是管理員並授予自有網域的權限，請使用 客戶 ID 為 my_customer。

• 如果您是經銷商取得某位客戶的權限， 請使用擷取 user 作業。

要求

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 要求，並加入 授權中授權 要求。

• 如果您是管理員，且要取得自有網域中的角色，請使用 客戶 ID 為 my_customer。

• 如為經銷商取得客戶角色，請使用 使用擷取 user 作業。

要求

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 可能會傳回包含網頁權杖的空白結果 參數。您應該繼續分頁，直到沒有任何頁面符記 。

• 如果您是管理員，且負責授予所屬網域指派角色的權限，請使用 客戶 ID 為 my_customer。

• 如果您是經銷商，且為某位客戶取得角色指派權限， 請使用擷取 user 作業。

要求

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 可能會傳回包含頁面符記的空白結果。請繼續進行 直到沒有傳回頁面符記為止。

• 如果您是管理員，且負責授予所屬網域指派角色的權限，請使用 客戶 ID 為 my_customer。

• 如果您是經銷商，且為某位客戶取得角色指派權限， 請使用擷取 user 作業。

• 將 USER_KEY 換成可用來識別 傳回的使用者。詳情請參閱 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。

• 如要將角色指派給群組，請新增 JSON 主體，並加上 group_id 是可以取得的 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 如 請參閱「取得現有角色」和「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'"
}