借助 Unified Access Policies (UAP),您可以向主账号授予或拒绝其对Google Cloud 资源的访问权限。本文档介绍了如何创建和应用 UAP。
准备工作
设置身份验证。
选择标签页以了解您打算如何使用本页面上的示例:
控制台
当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时,无需设置身份验证。
gcloud
在 Google Cloud 控制台中,激活 Cloud Shell。
Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动,并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。
REST
如需在本地开发环境中使用本页面上的 REST API 示例,请使用您提供给 gcloud CLI 的凭证。
安装 Google Cloud CLI。
如果您使用的是外部身份提供方 (IdP),则必须先使用联合身份登录 gcloud CLI。
如需了解详情,请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。
可选:阅读 UAP 概览。
创建 Unified Access Policies 所需的角色
如需获得创建 UAP 所需的权限,请让管理员向您授予您要在其中创建政策的项目、文件夹或组织的 Access Policy Admin (roles/iam.accessPolicyAdmin) IAM 角色。
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
此预定义角色包含创建 UAP 所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
创建 UAP 需要以下权限:
-
iam.accesspolicies.create -
在 Google Cloud 控制台中创建 UAP:
iam.accesspolicies.list
应用 Unified Access Policies 所需的角色
如需获得将 UAP 绑定到资源所需的权限,请让您的管理员为您授予以下 IAM 角色:
- 拥有 UAP 的资源上的 Access Policy Admin (
roles/iam.accessPolicyAdmin)。此角色包含创建绑定所需的iam.accesspolicies.bind权限。 包含
SERVICE.RESOURCE.createPolicyBinding权限的角色,其中RESOURCE是您要将政策绑定到的资源类型,SERVICE是拥有该资源的 Service。如需查找包含所需权限的角色,请在角色和权限参考文档中搜索该权限,点击该权限名称,然后查看包含该权限的角色。
您需要对该资源或其某个祖先资源拥有此角色。
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
创建 Unified Access Policies
您可以使用 Google Cloud 控制台、gcloud CLI 或 IAM REST API 创建 UAP。
控制台
-
在 Google Cloud 控制台中,前往 Unified Access Policies 页面。
前往“Unified Access Policies” - 选择要在其中创建 UAP 的项目、文件夹或组织。如需了解在何处创建 UAP,请参阅在何处创建 UAP。
- 点击 创建政策。
-
在政策名称字段中,输入 UAP 的名称,例如
Example policy。 名称最多可以包含 63 个字符。 - 可选:在政策 ID 字段中,自定义 UAP 的 ID。
-
向政策添加规则。对于每条规则,请执行以下操作:
- 可选:在说明字段中,输入规则的说明。
- 在主账号字段中,输入要包含在规则中的主账号。
- 可选:在排除的主账号字段中,输入您不想包含在规则中的主账号。即使这些主账号属于主账号字段中的某个群组,也不会被包含在内。
-
选择您希望规则产生的效果:
- 如需向指定主账号授予指定权限,请选择允许效果。
- 如需阻止指定的主账号使用指定权限,请选择拒绝效果。
-
选择要在规则中包含的权限:
- 对于具有允许效果的规则,您可以指定要在规则中包含或排除的角色和权限。如需详细了解可以包含的角色和权限,请参阅 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:包含 UAP 规则详情的 JSON 文件的路径。每条规则应采用以下格式:{ "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 群组添加到包含的主账号列表中,然后排除属于该群组的特定用户。
如需查看支持的主账号标识符列表,请参阅 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 群组添加到包含的主账号列表中,然后排除属于该群组的特定用户。
如需查看支持的主账号标识符列表,请参阅 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
}
将 Unified Access Policies 应用于资源
如需将 UAP 应用于资源,您需要创建绑定。为政策创建绑定后,该政策中的规则将对指定资源及其所有后代资源生效。
在创建绑定之前,请确保已停用 iam.managed.disableAccessPolicyBinding 组织政策限制条件。如需了解如何启用或停用此限制条件,请参阅在组织政策中使用托管式限制条件。
您可以使用 Google Cloud 控制台、gcloud CLI 或 IAM REST API 将 UAP 应用于项目、文件夹和组织。如需将 UAP 应用于其他资源,您必须使用 gcloud CLI 或 IAM REST API。
控制台
-
在 Google Cloud 控制台中,前往 Unified Access Policies 页面。
前往“Unified Access Policies” - 选择拥有您要应用的 UAP 的项目、文件夹或组织。
- 点击要应用的 UAP 的 ID。
- 选择绑定关系标签页,然后点击 添加绑定关系。
-
在添加绑定窗格中,修改绑定详细信息:
- 在绑定位置菜单中,选择要应用 UAP 的资源。
-
可选:在绑定显示名称字段中,输入绑定的直观易懂说明,例如
Example binding。显示名称最多可以包含 63 个字符。 -
在绑定 ID 字段中,输入绑定的唯一名称,例如
example-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 时,操作完成,您可以停止获取操作。