您可以使用 Directory API 透過角色式存取控管 (RBAC) 管理 Google Workspace 網域中各項功能的存取權。您可以建立具備權限的自訂角色，比 Google Workspace 提供的預先建立角色更精確地限制管理員存取權。您可以將角色指派給使用者或安全性群組。本指南說明如何執行一些與角色相關的基本工作。
以下列出 Directory API 針對 Google Workspace 內 RBAC 使用的常見詞彙：
- 權限
- 在 Google Workspace 網域中執行工作或作業所需的權限。以
Privilege資源表示。這項資源沒有任何相關聯的長存資料。 - 角色
- 權限集合，可授予具備該角色的實體執行特定工作或作業的能力。以
Role資源表示。 - 指派角色
- 指派給使用者或群組的特定角色記錄。由
RoleAssignment資源代表。 - 安全性群組
- 用來控管機構資源存取權的Cloud Identity 群組類型。安全性群組可以包含個別使用者和群組。
角色和角色指派限制
自訂角色或角色指派的數量有限，因此如果快要達到上限，請合併或移除角色，以免超出限制。角色和角色指派作業有下列限制：
- 您最多可為整個機構建立 750 個自訂角色。
- 每個機構單位 (OU) 最多可建立 1,000 個角色指派作業，根機構也視為一個單位。舉例來說，您可以在根機構中指派 600 個角色，並在您定義的其他 OU (例如公司部門) 中指派 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() 方法。
要求
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 要求，並附上「授權要求」一節中所述的授權。
要求
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 可能會傳回含有頁面權杖的空白結果。您應繼續分頁，直到系統未傳回任何頁面權杖為止。
要求
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。將
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(如身分與存取權管理 (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 方法，並附上「授權要求」一節中所述的授權。
新增 JSON 主體，其中包含使用者的 user_id (可透過 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'"
}