管理角色

Directory API 可讓您使用角色型存取權控管 (RBAC) 功能，管理 Google Workspace 網域功能的存取權。您可以使用權限建立自訂角色，限制除了 Google Workspace 提供的預建角色外，限制更嚴格的管理員存取權。您可以將角色指派給使用者或安全性群組。本指南說明如何執行一些基本的角色相關工作。

下列是 Directory API 常用的詞彙清單，其中與 Google Workspace 中的 RBAC 有關：

權限
在 Google Workspace 網域中執行工作或作業的必要權限。由 Privilege 資源代表。這項資源沒有任何相關聯的永久資料。
角色
這組權限可以授予擁有該角色的實體，進而執行特定工作或作業。由 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。

  • 如果您是經銷商，且要取得客戶的權限，請使用擷取使用者作業傳回的客戶 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。

  • 如要將角色指派給服務帳戶，請新增 JSON 主體，當中包含服務帳戶 (如身分與存取權管理 (IAM) 中定義的)、roleId (如「取得現有角色」一節所述) 和 scope_type 的 JSON 主體。unique_id

  • 如要將角色指派給群組，請新增含有群組的 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'"
}