主體存取邊界 (PAB) 政策可限制一組主體可存取的資源。本頁說明如何建立及套用主體存取權範圍政策。
事前準備
設定驗證方法。
選取這個頁面上範例的預計用途分頁:
控制台
使用 Cloud de Confiance 控制台存取 Cloud de Confiance by S3NS 服務和 API 時,不需要設定驗證。
gcloud
安裝 Google Cloud CLI,然後 使用聯合身分登入 gcloud CLI。登入後,執行下列指令來初始化 Google Cloud CLI:
gcloud initREST
如要在本機開發環境中使用本頁的 REST API 範例,請使用您提供給 gcloud CLI 的憑證。
安裝 Google Cloud CLI,然後 使用聯合身分登入 gcloud CLI。
詳情請參閱 Cloud de Confiance 驗證說明文件中的「使用 REST 進行驗證」。
閱讀主體存取邊界政策總覽。
建立主體存取邊界政策所需的角色
如要取得建立主體存取權範圍政策所需的權限,請要求管理員授予您機構的主體存取權範圍管理員 (roles/iam.principalAccessBoundaryAdmin) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
這個預先定義的角色具備 iam.principalaccessboundarypolicies.create 權限,可建立主體存取邊界政策。
套用主體存取邊界政策所需的角色
如要套用主體存取邊界政策,您需要的權限取決於要套用政策的主體組合。
如要取得套用主體存取權範圍政策所需的權限,請要求管理員授予您下列 IAM 角色:
- 機構的主體存取邊界使用者 (
roles/iam.principalAccessBoundaryUser) -
將主體存取權範圍政策套用至工作團隊身分集區:
目標工作團隊身分集區的身分與存取權管理工作團隊集區管理員 (
roles/iam.workforcePoolAdmin) -
將主體存取權界線政策套用至 workload identity pool:
在擁有目標 Workload Identity Federation pool 的專案中,身分與存取權管理 Workload Identity Pool 管理員 (
roles/iam.workloadIdentityPoolAdmin) -
取得將主體存取邊界政策套用至 workload identity pool 的長時間執行的作業狀態:
專案的 IAM 作業檢視者 (
roles/iam.operationViewer),該專案擁有目標 workload identity pool -
將主體存取權界線政策套用至 Google Workspace 網域:
Workspace Pool IAM 管理員 (
roles/iam.workspacePoolAdmin) 組織 -
將主體存取權範圍政策套用至專案的主體集:
專案的專案 IAM 管理員 (
roles/resourcemanager.projectIamAdmin) -
取得將主體存取邊界政策套用至專案主體集的長時間執行的作業狀態:
專案的「IAM 作業檢視者 」(
roles/iam.operationViewer) -
將主體存取權範圍政策套用至資料夾的主體集:
資料夾 IAM 管理員 (
roles/resourcemanager.folderIamAdmin) 位於資料夾 -
對機構的主體集套用主體存取邊界政策:
機構的機構管理員 (
roles/resourcemanager.organizationAdmin)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
這些預先定義的角色具備套用主體存取邊界政策所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:
所需權限
如要套用主體存取邊界政策,必須具備下列權限:
-
iam.principalaccessboundarypolicies.bind組織 -
將主體存取權界線政策套用至員工身分聯盟集區:
iam.workforcePools.createPolicyBinding在目標員工身分聯盟集區上 -
將主體存取邊界政策套用至 Workload Identity Federation 集區:
iam.workloadIdentityPools.createPolicyBinding在擁有目標 Workload Identity Federation 集區的專案中 -
取得將 Principal Access Boundary 政策套用至工作負載身分集區的長時間執行作業狀態:
iam.operations.get在擁有目標工作負載身分集區的專案中 -
將主體存取邊界政策套用至 Google Workspace 網域:
iam.workspacePools.createPolicyBinding在機構上 -
將主體存取邊界政策套用至專案的主體集:
resourcemanager.projects.createPolicyBinding在專案上 -
取得將主體存取邊界政策套用至專案主體集的長時間執行的作業狀態:
iam.operations.get專案 -
將主體存取邊界政策套用至資料夾的主體集:
resourcemanager.folders.createPolicyBinding在資料夾上 -
將主體存取邊界政策套用至機構的主體集:
resourcemanager.organizations.createPolicyBinding在機構上
建立主體存取邊界政策
您可以使用 Cloud de Confiance 控制台、gcloud CLI 或 IAM REST API 建立主體存取權界線政策。
控制台
前往 Cloud de Confiance 控制台的「Principal Access Boundary policies」(主體存取邊界政策) 頁面。
選取要建立主體存取邊界政策的機構。
按一下 「建立政策」。
在政策中新增主體存取邊界規則:
- 按一下 「新增邊界規則」。
- 在「Description」(說明) 欄位中,新增主體存取邊界政策規則的說明。說明不得超過 256 個半形字元。
在「資源」部分中,輸入您希望主體有權存取的所有 Resource Manager 資源 (專案、資料夾和機構)。受這項政策約束的任何主體,都有權存取這些資源。
每項主體存取邊界政策最多可參照政策中所有規則的 500 項資源。
按一下「完成」。
如要新增其他政策規則,請重複上述步驟。每項主體存取邊界政策最多可有 500 項規則。
在「政策名稱」部分,輸入政策名稱。名稱長度上限為 63 個字元。
在「Enforcement version」(強制執行版本) 清單中,選取政策的強制執行版本。主體存取邊界政策版本會決定 IAM 對主體存取邊界政策強制執行的權限。
如要進一步瞭解如何設定及管理強制執行版本,請參閱「管理強制執行版本」。
點選「建立」。
gcloud
gcloud iam principal-access-boundary-policies create
指令會建立主體存取邊界政策。
使用下列任何指令資料之前,請先替換以下項目:
-
PAB_POLICY_ID:主體存取邊界政策的專屬 ID,例如「example-policy」。 ORG_ID:您要在其中建立主體存取權範圍政策的機構 ID。機構 ID 為數字,例如123456789012。DISPLAY_NAME:選用。主體存取邊界政策的易讀說明,例如「Example policy」。顯示名稱長度上限為 63 個半形字元。-
FILE_PATH:包含主體存取邊界政策規則詳細資料的 JSON 檔案路徑。每項規則的格式應如下:{ "description": "DESCRIPTION", "resources": [ RESOURCES ], "effect": "ALLOW" }
替換下列值:
DESCRIPTION:選用。主體存取邊界政策規則的說明。說明不得超過 256 個半形字元。-
RESOURCES:您希望主體有權存取的 Resource Manager 資源清單 (專案、資料夾和機構)。凡是受這項政策約束的主體,都有權存取這些資源。每項主體存取邊界政策最多可參照政策中所有規則的 500 項資源。
-
ENFORCEMENT_VERSION:IAM 在強制執行政策時使用的 Principal Access Boundary 政策版本。強制執行版本會決定 IAM 對主體存取邊界政策強制執行的權限。可接受的值為
1、2、3、4和latest。如要進一步瞭解如何設定及管理強制執行版本,請參閱「強制執行版本管理」。
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud iam principal-access-boundary-policies create PAB_POLICY_ID \ --organization=ORG_ID --location=global \ --display-name=DISPLAY_NAME --details-rules=FILE_PATH.json \ --details-enforcement-version=ENFORCEMENT_VERSION
Windows (PowerShell)
gcloud iam principal-access-boundary-policies create PAB_POLICY_ID ` --organization=ORG_ID --location=global ` --display-name=DISPLAY_NAME --details-rules=FILE_PATH.json ` --details-enforcement-version=ENFORCEMENT_VERSION
Windows (cmd.exe)
gcloud iam principal-access-boundary-policies create PAB_POLICY_ID ^ --organization=ORG_ID --location=global ^ --display-name=DISPLAY_NAME --details-rules=FILE_PATH.json ^ --details-enforcement-version=ENFORCEMENT_VERSION
回應會包含代表您要求的長時間執行的作業。如要瞭解如何取得長時間執行的作業狀態,請參閱本頁面的「檢查長時間執行的作業狀態」。
Create request issued for: [example-policy] Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715373988044-6181fa136df85-3b06a30a-4816d25b] to complete...done. Created principalAccessBoundaryPolicy [example-policy].
REST
principalAccessBoundaryPolicies.create
方法會建立主體存取邊界政策。
使用任何要求資料之前,請先修改下列項目的值:
ORG_ID:您要在其中建立主體存取權範圍政策的機構 ID。機構 ID 為數字,例如123456789012。-
PAB_POLICY_ID:主體存取邊界政策的專屬 ID,例如「example-policy」。 DISPLAY_NAME:選用。主體存取邊界政策的易讀說明,例如「Example policy」。顯示名稱長度上限為 63 個半形字元。-
PAB_RULES:主體存取邊界規則清單,定義受影響主體可存取的資源。主體存取邊界政策最多可有 500 條規則。每項規則的格式如下:{ "description": "DESCRIPTION", "resources": [ RESOURCES ], "effect": "ALLOW" }
替換下列值:
DESCRIPTION:選用。主體存取邊界政策規則的說明。說明不得超過 256 個半形字元。-
RESOURCES:您希望主體有權存取的 Resource Manager 資源清單 (專案、資料夾和機構)。凡是受這項政策約束的主體,都有權存取這些資源。每項主體存取邊界政策最多可參照政策中所有規則的 500 項資源。
-
ENFORCEMENT_VERSION:IAM 在強制執行政策時使用的 Principal Access Boundary 政策版本。強制執行版本會決定 IAM 對主體存取邊界政策強制執行的權限。可接受的值為
1、2、3、4和latest。如要進一步瞭解如何設定及管理強制執行版本,請參閱「強制執行版本管理」。
HTTP 方法和網址:
POST https://iam.googleapis.com/v3/organizations/ORG_ID/locations/global?principalAccessBoundaryPolicyId=PAB_POLICY_ID
JSON 要求主體:
{
"displayName": "DISPLAY_NAME",
"details": {
"rules": [
PAB_RULES
],
"enforcementVersion": "ENFORCEMENT_VERSION"
}
}
請展開以下其中一個選項,以傳送要求:
回應會包含代表您要求的長時間執行的作業。如要瞭解如何取得長時間執行的作業狀態,請參閱本頁面的「檢查長時間執行的作業狀態」。
{
"name": "organizations/123456789012/locations/global/operations/operation-1715373120647-6181f6d8371d2-83309b71-2b8a7532",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2024-05-10T20:32:00.898809495Z",
"target": "organizations/123456789012/locations/global/policyBindings/example-policy",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": false
}
將主體存取邊界政策套用至主體集
如要將主體存取邊界政策套用至主體集,請建立政策繫結資源,將政策繫結至主體集。建立政策繫結後,繫結中的主體存取邊界政策就會對繫結中的主體強制執行。
您可以使用 Cloud de Confiance 控制台、gcloud CLI 或 IAM REST API 建立政策繫結。
控制台
前往 Cloud de Confiance 控制台的「Principal Access Boundary policies」(主體存取邊界政策) 頁面。
選取要建立繫結的主體存取邊界政策所屬機構。
按一下要建立繫結的主體存取邊界政策的政策 ID。
按一下「繫結」分頁,然後點選 「新增繫結」。
輸入繫結詳細資料:
- 選用:在「Display name」(顯示名稱) 欄位中,輸入繫結的顯示名稱。顯示名稱不得超過 63 個半形字元。
- 在「Binding ID」(繫結 ID) 欄位中,輸入繫結的專屬名稱,例如
example-binding。 在「目標主體組合」部分,輸入要繫結政策的主體組合類型和 ID。建立政策繫結後,就無法變更這個值。
如要進一步瞭解各主體組合包含的主體,請參閱「支援的主體組合」。
選用:如要指定主體集中哪些主體會強制執行主體存取邊界政策,請在繫結中新增條件:
- 按一下「新增條件」。
- 在「Title」(標題) 欄位中,簡要說明條件的用途。
- 選用:在「Description」(說明) 欄位中輸入條件的詳細說明。
- 在「運算式」欄位中,輸入使用一般運算語言 (CEL) 語法的條件運算式。運算式必須參照
principal.type或principal.subject屬性。系統不支援其他屬性。 - 按一下 [儲存]。
選用:如要使用 Policy Simulator 測試主體存取邊界政策繫結的變更,請按一下「測試變更」。查看模擬結果,並視需要更新政策繫結。
如要進一步瞭解如何使用 Policy Simulator 測試主體存取邊界政策,請參閱「主體存取邊界政策的 Policy Simulator」。
如要建立繫結,請按一下「新增」。
gcloud
gcloud iam policy-bindings create
指令會建立政策繫結。
使用下列任何指令資料之前,請先替換以下項目:
-
BINDING_ID:政策繫結的專屬名稱,例如example-binding。 -
RESOURCE_TYPE:政策繫結所屬的 Resource Manager 資源類型 (專案、資料夾或機構)。使用project、folder或organization值資源類型取決於政策繫結中設定的主體。如要瞭解應使用哪種資源類型,請參閱「支援的主體類型」。
-
RESOURCE_ID:政策繫結所屬專案、資料夾或機構的 ID。專案 ID 是英數字元字串,例如my-project。資料夾和機構 ID 都是數字,例如123456789012。 -
ORG_ID:擁有主體存取邊界政策的機構 ID,您要將該政策繫結至主體組合。機構 ID 為數字,例如123456789012。 -
PAB_POLICY_ID:要繫結至主體集的 Principal Access Boundary 政策 ID,例如example-pab-policy。建立政策繫結後,就無法變更這個值。 -
PRINCIPAL_SET:要將政策繫結至的主體組合。如需有效主體類型清單,請參閱「支援的主體集」。建立政策繫結後,您就無法變更這個值。 DISPLAY_NAME:選用。繫結的人類可讀說明,例如Example binding。顯示名稱的長度上限為 63 個半形字元。-
CONDITION_DETAILS:選用。條件運算式,指定要對主體集中的哪些主體強制執行主體存取邊界政策。包含下列欄位:-
expression:使用一般運算語言 (CEL) 語法的條件運算式。運算式必須參照principal.type或principal.subject屬性。不支援其他屬性。運算式最多可包含 10 個邏輯運算子 (
&&、||、!),長度最多為 250 個字元。 -
title:選用。簡短說明條件的用途。 -
description:選用。情況的詳細說明。
-
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud iam policy-bindings create BINDING_ID \ --RESOURCE_TYPE=RESOURCE_ID --location=global \ --policy="organizations/ORG_ID/locations/global/principalAccessBoundaryPolicies/PAB_POLICY_ID" \ --target-principal-set=PRINCIPAL_SET \ --display-name=DISPLAY_NAME \ CONDITION_DETAILS
Windows (PowerShell)
gcloud iam policy-bindings create BINDING_ID ` --RESOURCE_TYPE=RESOURCE_ID --location=global ` --policy="organizations/ORG_ID/locations/global/principalAccessBoundaryPolicies/PAB_POLICY_ID" ` --target-principal-set=PRINCIPAL_SET ` --display-name=DISPLAY_NAME ` CONDITION_DETAILS
Windows (cmd.exe)
gcloud iam policy-bindings create BINDING_ID ^ --RESOURCE_TYPE=RESOURCE_ID --location=global ^ --policy="organizations/ORG_ID/locations/global/principalAccessBoundaryPolicies/PAB_POLICY_ID" ^ --target-principal-set=PRINCIPAL_SET ^ --display-name=DISPLAY_NAME ^ CONDITION_DETAILS
回應會包含代表您要求的長時間執行的作業。如要瞭解如何取得長時間執行的作業狀態,請參閱本頁面的「檢查長時間執行的作業狀態」。
Create request issued for: [example-binding] Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374545618-6181fc272c6f9-55ff07f4-97d0ac76] to complete...done. Created policyBinding [example-binding].
REST
policyBindings.create
方法會建立政策繫結。
使用任何要求資料之前,請先修改下列項目的值:
-
RESOURCE_TYPE:政策繫結所屬的 Resource Manager 資源類型 (專案、資料夾或機構)。使用projects、folders或organizations值資源類型取決於政策繫結中設定的主體。如要瞭解應使用哪種資源類型,請參閱「支援的主體類型」。
-
RESOURCE_ID:政策繫結所屬專案、資料夾或機構的 ID。專案 ID 是英數字元字串,例如my-project。資料夾和機構 ID 都是數字,例如123456789012。 -
BINDING_ID:政策繫結的專屬名稱,例如example-binding。 DISPLAY_NAME:選用。繫結的人類可讀說明,例如Example binding。顯示名稱的長度上限為 63 個半形字元。-
PRINCIPAL_SET:要將政策繫結至的主體組合。如需有效主體類型清單,請參閱「支援的主體集」。建立政策繫結後,您就無法變更這個值。 -
ORG_ID:擁有主體存取邊界政策的機構 ID,您要將該政策繫結至主體組合。機構 ID 為數字,例如123456789012。 -
PAB_POLICY_ID:要繫結至主體集的 Principal Access Boundary 政策 ID,例如example-pab-policy。建立政策繫結後,就無法變更這個值。 -
CONDITION_DETAILS:選用。條件運算式,指定要對主體集中的哪些主體強制執行主體存取邊界政策。包含下列欄位:-
expression:使用一般運算語言 (CEL) 語法的條件運算式。運算式必須參照principal.type或principal.subject屬性。不支援其他屬性。運算式最多可包含 10 個邏輯運算子 (
&&、||、!),長度最多為 250 個字元。 -
title:選用。簡短說明條件的用途。 -
description:選用。情況的詳細說明。
-
HTTP 方法和網址:
POST https://iam.googleapis.com/v3/RESOURCE_TYPE/RESOURCE_ID/locations/global/policyBindings?policyBindingId=BINDING_ID
JSON 要求主體:
{
"displayName": "DISPLAY_NAME",
"target": {
"principalSet": "PRINCIPAL_SET"
},
"policyKind": "PRINCIPAL_ACCESS_BOUNDARY",
"policy": "organizations/ORG_ID/locations/global/principalAccessBoundaryPolicies/PAB_POLICY_ID",
"condition": {
CONDITION_DETAILS
}
}
請展開以下其中一個選項,以傳送要求:
回應會包含代表您要求的長時間執行的作業。如要瞭解如何取得長時間執行的作業狀態,請參閱本頁面的「檢查長時間執行的作業狀態」。
{
"name": "organizations/123456789012/locations/global/operations/operation-1715373120647-6181f6d8371d2-83309b71-2b8a7532",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2024-05-10T20:32:00.898809495Z",
"target": "organizations/123456789012/locations/global/policyBindings/example-binding",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": false
}
查看長時間執行的作業狀態
使用 REST API 或用戶端程式庫時,任何會變更政策或繫結的方法都會傳回長時間執行的作業 (LRO)。長時間執行的作業會追蹤要求狀態,並指出政策或繫結的變更是否完成。
REST
operations.get
方法會傳回長時間執行的作業的狀態。
使用任何要求資料之前,請先修改下列項目的值:
-
OPERATION_NAME:作業的完整名稱。您會在原始要求的相關回覆中收到這個名稱。作業名稱的格式如下:
RESOURCE_TYPE/RESOURCE_ID/locations/global/operations/OPERATION_ID
HTTP 方法和網址:
GET https://iam.googleapis.com/v3/OPERATION_NAME
請展開以下其中一個選項,以傳送要求:
您應該會收到如下的 JSON 回覆:
{
"name": "organizations/314340013352/locations/global/operations/operation-1732752311821-627edd607a3df-9a62cdea-2a7d9f07",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2024-11-28T00:05:12.006289686Z",
"endTime": "2024-11-28T00:05:12.192141801Z",
"target": "organizations/314340013352/locations/global/POLICY_TYPE/POLICY_ID",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": true,
"response": {
POLICY
}
}
如果作業的 done 欄位不存在,請繼續重複取得作業,以監控其狀態。請使用部分指數輪詢,在每次要求之間加入延遲。當 done 欄位設為 true 時,即代表作業完成,您可以停止取得作業。