您可以透過統一存取政策 (UAP),授予及拒絕主體對Google Cloud 資源的存取權。本文說明如何建立及套用 UAP。
事前準備
設定驗證方法。
請根據您打算如何使用本頁範例,選取對應的分頁標籤:
控制台
使用 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 進行驗證」一節。
選用:閱讀 UAP 總覽。
建立統一存取政策所需的角色
如要取得建立 UAP 所需的權限,請要求管理員在您要建立政策的專案、資料夾或組織中,授予您存取權政策管理員 (roles/iam.accessPolicyAdmin) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
這個預先定義的角色具備建立 UAP 所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:
所需權限
必須具備下列權限,才能建立 UAP:
-
iam.accesspolicies.create -
在 Google Cloud 控制台中建立 UAP:
iam.accesspolicies.list
套用統一存取政策所需的角色
如要取得將 UAP 繫結至資源所需的權限,請要求管理員授予您下列 IAM 角色:
- 擁有 UAP 的資源存取權政策管理員 (
roles/iam.accessPolicyAdmin)。這個角色包含iam.accesspolicies.bind權限,這是建立繫結的必要權限。 具備
SERVICE.RESOURCE.createPolicyBinding權限的角色,其中RESOURCE是要繫結政策的資源類型,SERVICE則是擁有該資源的服務。如要找出具備必要權限的角色,請在角色和權限參考資料中搜尋該權限,然後按一下權限名稱,查看具備該權限的角色。
您必須在資源或其上層資源中具備這個角色。
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
建立統一存取政策
您可以使用 Google Cloud 控制台、gcloud CLI 或 IAM REST API 建立 UAP。
控制台
-
在 Google Cloud 控制台中,前往「統一存取政策」 頁面。
前往「Unified Access Policies」(統一存取政策) 頁面 - 選取要建立 UAP 的專案、資料夾或組織。如需建立 UAP 的位置指南,請參閱「建立 UAP 的位置」。
- 按一下「 Create policy」(建立政策)。
-
在「Policy name」(政策名稱) 欄位中,輸入 UAP 的名稱,例如
Example policy。名稱長度上限為 63 個字元。 - 選用:在「Policy ID」(政策 ID) 欄位中,自訂 UAP 的 ID。
-
在政策中新增規則。針對每項規則,執行下列操作:
- 選用:在「Description」(說明) 欄位中輸入規則說明。
- 在「Principals」(主體) 欄位中,輸入要納入規則的主體。
- 選用:在「Excluded principals」(排除的主體) 欄位中,輸入不想納入規則的主體。即使這些主體屬於「主體」欄位中的群組,也不會包含在內。
-
選取規則要產生的效果:
- 如要將指定權限授予指定主體,請選取「允許」效果。
- 如要禁止指定主體使用指定權限,請選取「Deny」(拒絕) 效果。
-
選取要納入規則的權限:
- 如果規則的效果為「允許」,您可以指定要納入或排除的角色和權限。如要進一步瞭解可納入的角色和權限,請參閱「UAP 規則中的角色和權限」。
- 如果規則的效果為「拒絕」,請指定要納入或排除的權限。如要進一步瞭解可納入的權限,請參閱「UAP 規則中的角色和權限」。
-
選用:新增規則適用的條件。如要進一步瞭解支援的條件屬性,請參閱「UAP 中的條件」。
- 規則編輯完成後,按一下「完成」。
- 如要新增其他規則,請按一下「新增規則」,然後新增規則詳細資料。
- 規則新增完畢後,按一下「建立政策」。
gcloud
gcloud iam access-policies create 指令會建立 UAP。
使用下列任何指令資料前,請先替換以下項目:
-
UAP_ID:UAP 的專屬 ID,例如example-policy。 -
UAP_PARENT_RESOURCE_TYPE:要建立 UAP 的 Resource Manager 資源類型 (專案、資料夾或組織)。請使用project、folder或organization值。 -
UAP_PARENT_RESOURCE_ID:要建立 UAP 的專案、資料夾或組織 ID。專案 ID 是英數字串,例如my-project。資料夾和組織 ID 則為數字,例如123456789012。 DISPLAY_NAME:選用。UAP 的人類可讀說明,例如Example policy。顯示名稱長度上限為 63 個字元。-
FILE_PATH:JSON 檔案的路徑,其中包含 UAP 規則詳細資料。每項規則都應採用下列格式:{ "description": "DESCRIPTION", "effect": "EFFECT", "principals": [ INCLUDED_PRINCIPALS ], "excludedPrincipals": [ EXCLUDED_PRINCIPALS ], "operation": { "permissions": [ INCLUDED_PERMISSIONS ], "excludedPermissions": [ EXCLUDED_PERMISSIONS ] }, CONDITIONS }
替換下列值:
-
DESCRIPTION:規則的人類可讀說明。 -
EFFECT:規則對存取權的影響。支援的值為ALLOW和DENY:-
ALLOW:將指定權限授予指定主體。 -
DENY:禁止指定的主體使用指定權限。
-
-
替換下列值,指定規則中包含的主體:
-
INCLUDED_PRINCIPALS:要納入規則的主體。 -
EXCLUDED_PRINCIPALS:選用。要從規則中排除的主體,即使這些主體位於納入的主體清單中也一樣。舉例來說,您可以將 Google 群組新增至納入的主體清單,然後排除屬於該群組的特定使用者。
如需支援的主體 ID 清單,請參閱「UAP 的主體類型」。
-
-
替換下列值,指定要納入規則的權限:
-
INCLUDED_PERMISSIONS:要納入規則的權限。 -
EXCLUDED_PERMISSIONS:選用。要從規則中排除的權限,即使這些權限位於納入的權限清單中。舉例來說,您可以將某個角色新增至納入的權限清單,然後排除該角色中的特定權限。
建立這些權限清單時,您可以參照權限名稱、角色名稱和權限群組。詳情請參閱「UAP 規則中的角色和權限」。
-
-
CONDITIONS:選用。規則的適用條件。請使用下列格式:"conditions": { "SERVICE": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
替換下列值:
-
SERVICE:提供條件運算式所用屬性的服務。 -
CONDITION_TITLE:選用。條件用途的簡短摘要。 -
CONDITION_DESCRIPTION:選用。條件的詳細說明。 -
CONDITION_EXPRESSION:參照存取嘗試屬性的布林運算式,例如存取嘗試中附加至資源的標記。如果運算式評估結果為true,則規則會套用至存取嘗試。如果評估結果為false,則規則不適用於存取嘗試。
如需支援屬性及其服務清單,請參閱「支援的條件屬性」。
-
-
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud iam access-policies create UAP_ID \ --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID \ --location=global --display-name=DISPLAY_NAME \ --details-rules=FILE_PATH
Windows (PowerShell)
gcloud iam access-policies create UAP_ID ` --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ` --location=global --display-name=DISPLAY_NAME ` --details-rules=FILE_PATH
Windows (cmd.exe)
gcloud iam access-policies create UAP_ID ^ --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ^ --location=global --display-name=DISPLAY_NAME ^ --details-rules=FILE_PATH
回應會包含代表要求的長時間執行的作業。如要瞭解如何取得長時間執行的作業狀態,請參閱本頁的「查看長時間執行的作業狀態」一節。
Create request issued for: [example-policy] Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715373988044-6181fa136df85-3b06a30a-4816d25b] to complete...done. Created accessPolicy [example-policy].
REST
accessPolicies.create 方法會建立 UAP。
使用任何要求資料之前,請先修改下列項目的值:
-
UAP_PARENT_RESOURCE_TYPE:要建立 UAP 的 Resource Manager 資源類型 (專案、資料夾或組織)。請使用projects、folders或organizations值。 -
UAP_PARENT_RESOURCE_ID:要建立 UAP 的專案、資料夾或組織 ID。專案 ID 是英數字串,例如my-project。資料夾和組織 ID 則為數字,例如123456789012。 -
UAP_ID:UAP 的專屬 ID,例如example-policy。 DISPLAY_NAME:選用。UAP 的人類可讀說明,例如Example policy。顯示名稱長度上限為 63 個字元。-
UAP_RULES:UAP 規則清單,定義要授予或拒絕的存取權,以及要授予或拒絕存取權的主體。一項 UAP 最多可有 100 項規則。每項規則的格式如下:{ "description": "DESCRIPTION", "effect": "EFFECT", "principals": [ INCLUDED_PRINCIPALS ], "excludedPrincipals": [ EXCLUDED_PRINCIPALS ], "operation": { "permissions": [ INCLUDED_PERMISSIONS ], "excludedPermissions": [ EXCLUDED_PERMISSIONS ] }, CONDITIONS }
替換下列值:
-
DESCRIPTION:規則的人類可讀說明。 -
EFFECT:規則對存取權的影響。支援的值為ALLOW和DENY:-
ALLOW:將指定權限授予指定主體。 -
DENY:禁止指定的主體使用指定權限。
-
-
替換下列值,指定規則中包含的主體:
-
INCLUDED_PRINCIPALS:要納入規則的主體。 -
EXCLUDED_PRINCIPALS:選用。要從規則中排除的主體,即使這些主體位於納入的主體清單中也一樣。舉例來說,您可以將 Google 群組新增至納入的主體清單,然後排除屬於該群組的特定使用者。
如需支援的主體 ID 清單,請參閱「UAP 的主體類型」。
-
-
替換下列值,指定要納入規則的權限:
-
INCLUDED_PERMISSIONS:要納入規則的權限。 -
EXCLUDED_PERMISSIONS:選用。要從規則中排除的權限,即使這些權限位於納入的權限清單中。舉例來說,您可以將某個角色新增至納入的權限清單,然後排除該角色中的特定權限。
建立這些權限清單時,您可以參照權限名稱、角色名稱和權限群組。詳情請參閱「UAP 規則中的角色和權限」。
-
-
CONDITIONS:選用。規則的適用條件。請使用下列格式:"conditions": { "SERVICE": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
替換下列值:
-
SERVICE:提供條件運算式所用屬性的服務。 -
CONDITION_TITLE:選用。條件用途的簡短摘要。 -
CONDITION_DESCRIPTION:選用。條件的詳細說明。 -
CONDITION_EXPRESSION:參照存取嘗試屬性的布林運算式,例如存取嘗試中附加至資源的標記。如果運算式評估結果為true,則規則會套用至存取嘗試。如果評估結果為false,則規則不適用於存取嘗試。
如需支援屬性及其服務清單,請參閱「支援的條件屬性」。
-
-
HTTP 方法和網址:
POST https://iam.googleapis.com/v3/UAP_PARENT_RESOURCE_TYPE/UAP_PARENT_RESOURCE_ID/locations/global/accessPolicies?accessPolicyId=UAP_ID
JSON 要求主體:
{
"displayName": "DISPLAY_NAME",
"details": {
"rules": [
UAP_RULES
]
}
}
請展開以下其中一個選項,以傳送要求:
回應會包含代表要求的長時間執行的作業。如要瞭解如何取得長時間執行的作業狀態,請參閱本頁的「查看長時間執行的作業狀態」一節。
{
"name": "organizations/123456789012/locations/global/operations/operation-1715373120647-6181f6d8371d2-83309b71-2b8a7532",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2026-05-10T20:32:00.898809495Z",
"target": "organizations/123456789012/locations/global/accessPolicies/example-policy",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": false
}
將統一存取政策套用至資源
如要將 UAP 套用至資源,請建立繫結。建立政策繫結之後,指定的資源及資源的子項目就會實行該項政策的規則。
建立繫結前,請先確認 iam.managed.disableAccessPolicyBinding 組織政策限制已停用。如要瞭解如何啟用或停用這項限制,請參閱「在組織政策中使用代管限制」。
您可以使用 Google Cloud 控制台、gcloud CLI 或 IAM REST API,將 UAP 套用至專案、資料夾和組織。如要將 UAP 套用至其他資源,請使用 gcloud CLI 或 IAM REST API。
控制台
-
在 Google Cloud 控制台中,前往「統一存取政策」 頁面。
前往「Unified Access Policies」(統一存取政策) 頁面 - 選取要套用的 UAP 所屬專案、資料夾或組織。
- 按一下要套用的 UAP ID。
- 選取「繫結」分頁標籤,然後按一下「 新增繫結」 。
-
在「Add binding」(新增繫結) 窗格中,編輯繫結詳細資料:
- 在「Binding location」(繫結位置) 選單中,選取要套用 UAP 的資源。
-
選用:在「Binding display name」(繫結顯示名稱) 欄位中,輸入繫結的人類可讀說明,例如
Example binding。顯示名稱長度上限為 63 個字元。 -
在「Binding ID」(繫結 ID) 欄位中,輸入繫結的專屬名稱,例如
example-binding。
- 按一下「Add binding」(新增繫結)。
gcloud
gcloud iam policy-bindings create 指令會建立繫結。
使用下列任何指令資料前,請先替換以下項目:
-
BINDING_ID:繫結的專屬名稱,例如example-binding。 -
BINDING_PARENT_RESOURCE_TYPE:繫結所屬 Resource Manager 資源 (專案、資料夾或組織) 的類型。請使用project、folder或organization值。繫結的父項資源取決於繫結中的目標資源。詳情請參閱「支援的資源」一文。
-
BINDING_PARENT_RESOURCE_ID:政策繫結所屬的專案、資料夾或組織 ID。專案 ID 是英數字串,例如my-project。資料夾和組織 ID 則為數字,例如123456789012。 -
POLICY_PARENT_RESOURCE:建立 UAP 的資源,格式為RESOURCE_TYPE/RESOURCE_ID。例如:organizations/0123456789012。您可以在專案、資料夾或組織中建立 UAP。資料夾和組織 ID 必須是數字。專案 ID 可以是數字或英數字元。 -
UAP_ID:要繫結至資源的 UAP ID,例如example-uap。建立繫結後,即無法變更這個值。 -
TARGET_RESOURCE:要繫結 UAP 的資源。如需有效資源清單,請參閱「支援的資源」。建立繫結後,就無法變更這個值。 DISPLAY_NAME:選用。繫結的人類可讀說明,例如Example binding。顯示名稱長度上限為 63 個字元。
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud iam policy-bindings create BINDING_ID \ --BINDING_PARENT_RESOURCE_TYPE=BINDING_PARENT_RESOURCE_ID --location=global \ --policy="POLICY_PARENT_RESOURCE/locations/global/accessPolicies/UAP_ID" \ --target-resource=TARGET_RESOURCE \ --display-name=DISPLAY_NAME
Windows (PowerShell)
gcloud iam policy-bindings create BINDING_ID ` --BINDING_PARENT_RESOURCE_TYPE=BINDING_PARENT_RESOURCE_ID --location=global ` --policy="POLICY_PARENT_RESOURCE/locations/global/accessPolicies/UAP_ID" ` --target-resource=TARGET_RESOURCE ` --display-name=DISPLAY_NAME
Windows (cmd.exe)
gcloud iam policy-bindings create BINDING_ID ^ --BINDING_PARENT_RESOURCE_TYPE=BINDING_PARENT_RESOURCE_ID --location=global ^ --policy="POLICY_PARENT_RESOURCE/locations/global/accessPolicies/UAP_ID" ^ --target-resource=TARGET_RESOURCE ^ --display-name=DISPLAY_NAME
回應會包含代表要求的長時間執行的作業。如要瞭解如何取得長時間執行的作業狀態,請參閱本頁的「查看長時間執行的作業狀態」一節。
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 方法會建立繫結。
使用任何要求資料之前,請先修改下列項目的值:
-
BINDING_PARENT_RESOURCE_TYPE:繫結所屬 Resource Manager 資源 (專案、資料夾或組織) 的類型。請使用projects、folders或organizations值。繫結的父項資源取決於繫結中的目標資源。詳情請參閱「支援的資源」一文。
-
BINDING_PARENT_RESOURCE_ID:政策繫結所屬的專案、資料夾或組織 ID。專案 ID 是英數字串,例如my-project。資料夾和組織 ID 則為數字,例如123456789012。 -
BINDING_ID:繫結的專屬名稱,例如example-binding。 DISPLAY_NAME:選用。繫結的人類可讀說明,例如Example binding。顯示名稱長度上限為 63 個字元。-
TARGET_RESOURCE:要繫結 UAP 的資源。如需有效資源清單,請參閱「支援的資源」。建立繫結後,就無法變更這個值。 -
POLICY_PARENT_RESOURCE:建立 UAP 的資源,格式為RESOURCE_TYPE/RESOURCE_ID。例如:organizations/0123456789012。您可以在專案、資料夾或組織中建立 UAP。資料夾和組織 ID 必須是數字。專案 ID 可以是數字或英數字元。 -
UAP_ID:要繫結至資源的 UAP ID,例如example-uap。建立繫結後,即無法變更這個值。
HTTP 方法和網址:
POST https://iam.googleapis.com/v3/BINDING_PARENT_RESOURCE_TYPE/BINDING_PARENT_RESOURCE_ID/locations/global/policyBindings?policyBindingId=BINDING_ID
JSON 要求主體:
{
"displayName": "DISPLAY_NAME",
"target": {
"resource": "TARGET_RESOURCE"
},
"policyKind": "ACCESS",
"policy": "POLICY_PARENT_RESOURCE/locations/global/accessPolicies/UAP_ID"
}
請展開以下其中一個選項,以傳送要求:
回應會包含代表要求的長時間執行的作業。如要瞭解如何取得長時間執行的作業狀態,請參閱本頁的「查看長時間執行的作業狀態」一節。
{
"name": "organizations/123456789012/locations/global/operations/operation-1715373120647-6181f6d8371d2-83309b71-2b8a7532",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2026-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 時,代表作業已完成,您可以停止取得作業。