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'"
}