主體存取邊界 (PAB) 政策可限制一組主體可存取的資源。本頁面說明如何建立及套用主體存取邊界政策。
事前準備
設定驗證方法。
請根據您打算如何使用本頁範例,選取對應的分頁標籤:
控制台
使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時,不需要設定驗證機制。
gcloud
在 Google Cloud 控制台啟用 Cloud Shell。
Google Cloud 控制台底部會開啟 Cloud Shell 工作階段,並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境,並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
REST
如要在本機開發環境中使用本頁的 REST API 範例,請使用您提供給 gcloud CLI 的憑證。
安裝 Google Cloud CLI。
若您採用的是外部識別資訊提供者 (IdP),請先使用聯合身分登入 gcloud CLI。
詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」一節。
閱讀主體存取邊界政策總覽。
建立主體存取邊界政策所需的角色
如要取得建立主體存取邊界政策所需的權限,請要求管理員授予您組織的主體存取邊界管理員 (roles/iam.principalAccessBoundaryAdmin) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
這個預先定義的角色具備 iam.principalaccessboundarypolicies.create 權限,可建立主體存取邊界政策。
套用主體存取邊界政策所需的角色
套用主體存取邊界政策所需的權限,取決於要套用政策的主體集。
如要取得套用主體存取邊界政策所需的權限,請要求管理員授予您下列 IAM 角色:
- 組織的主體存取邊界使用者 (
roles/iam.principalAccessBoundaryUser) -
將主體存取邊界政策套用至員工身分集區:目標員工身分集區的 IAM 員工集區管理員 (
roles/iam.workforcePoolAdmin) -
將主體存取邊界政策套用至 workload identity pool:在擁有目標 Workload Identity Federation 集區的專案中,具備身分與存取權管理 workload identity pool 管理員 (
roles/iam.workloadIdentityPoolAdmin) 角色 -
取得長時間執行的作業狀態,以便將主體存取邊界政策套用至 workload identity pool:目標 workload identity pool 所屬專案的 IAM 作業檢視者 (
roles/iam.operationViewer) -
將主體存取邊界政策套用至 Google Workspace 網域:組織的工作區集區 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 集區所屬的專案上 -
取得長時間執行的作業狀態,將主體存取權邊界政策套用至 workload identity pool:
iam.operations.get在擁有目標 workload identity pool 的專案上 -
將主體存取邊界政策套用至 Google Workspace 網域:
iam.workspacePools.createPolicyBinding組織 -
將主體存取邊界政策套用至專案的主體集:
resourcemanager.projects.createPolicyBinding在專案上 -
取得長時間執行的作業狀態,以便將主體存取邊界政策套用至專案的主體集:
iam.operations.get(位於專案) -
將主體存取邊界政策套用至資料夾的主體集:
resourcemanager.folders.createPolicyBinding在資料夾上 -
將主體存取邊界政策套用至組織的主體集:
resourcemanager.organizations.createPolicyBinding組織
建立主體存取邊界政策
您可以使用 Google Cloud 控制台、gcloud CLI 或 IAM REST API 建立主體存取權邊界政策。
控制台
前往 Google Cloud 控制台的「Principal Access Boundary policies」(主體存取權邊界政策) 頁面。
選取要建立主體存取邊界政策的組織。
按一下「 建立政策」。
在政策中新增主體存取邊界規則:
- 按一下「 新增邊界規則」。
- 在「Description」(說明) 欄位中,新增主體存取邊界政策規則的說明。說明長度上限為 256 個半形字元。
在「Resources」(資源) 區段中,輸入您要允許主體存取的所有 Resource Manager 資源 (專案、資料夾和組織)。凡是受這項政策規範的主體,都能存取這些資源。
每項主體存取邊界政策中,所有規則最多可參照 500 項資源。
按一下「完成」。
如要新增其他政策規則,請重複執行上述步驟。每項主體存取邊界政策最多可有 500 項規則。
在「Policy name」(政策名稱) 部分,輸入政策名稱。名稱長度上限為 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 執行政策時使用的主體存取邊界政策版本。強制執行版本會決定 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 執行政策時使用的主體存取邊界政策版本。強制執行版本會決定 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
}
將主體存取邊界政策套用至主體集
如要將主體存取邊界政策套用至主體集,請建立政策繫結資源,將政策繫結至主體集。建立政策繫結後,系統會對繫結中的主體強制執行繫結中的主體存取邊界政策。
您可以使用 Google Cloud 控制台、gcloud CLI 或 IAM REST API 建立政策繫結。
控制台
前往 Google Cloud 控制台的「Principal Access Boundary policies」(主體存取權邊界政策) 頁面。
選取擁有主體存取邊界政策的組織,以便建立繫結。
按一下要建立繫結的主體存取邊界政策 ID。
按一下「繫結」分頁標籤,然後點選「新增繫結」圖示 。
輸入繫結詳細資料:
- 選用:在「Display name」(顯示名稱) 欄位中,輸入繫結的顯示名稱。顯示名稱長度上限為 63 個字元。
- 在「Binding ID」(繫結 ID) 欄位中,輸入繫結的專屬名稱,例如
example-binding。 在「Target principal set」(目標主體組合) 部分,輸入要繫結政策的主體組合類型和 ID。建立政策繫結後,就無法變更這個值。
如要進一步瞭解各主體組合包含的主體,請參閱「支援的主體組合」。
選用:如要指定主體存取邊界政策對主體集中的哪些主體強制執行,請在繫結中新增條件:
- 按一下「 新增條件」。
- 在「Title」(標題) 欄位中,輸入條件用途的簡短摘要。
- 選用:在「Description」(說明) 欄位中,輸入較長的條件說明。
- 在「Expression」(運算式) 欄位中,輸入使用一般運算語言 (CEL) 語法的條件運算式。運算式必須參照
principal.type或principal.subject屬性。不支援其他屬性。 - 按一下「儲存」。
選用:如要使用 Policy Simulator 測試主體存取邊界政策繫結的變更,請按一下「Test changes」(測試變更)。查看模擬結果,並視需要更新政策繫結。
如要進一步瞭解如何使用 Policy Simulator 測試主體存取邊界政策,請參閱「主體存取邊界政策的 Policy Simulator」。
如要建立繫結,請按一下「Add」(新增)。
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 時,代表作業已完成,您可以停止取得作業。