借助 Unified Access Policies (UAP),您可以向主账号授予或拒绝其对Cloud de Confiance 资源的访问权限。本文档介绍了如何创建和应用 UAP。
准备工作
设置身份验证。
选择标签页以了解您打算如何使用本页面上的示例:
控制台
当您使用 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 时进行身份验证。
可选:阅读 UAP 概览。
创建 Unified Access Policies 所需的角色
如需获得创建 UAP 所需的权限,请让管理员向您授予您要在其中创建政策的项目、文件夹或组织的 Access Policy Admin (roles/iam.accessPolicyAdmin) IAM 角色。
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
此预定义角色包含创建 UAP 所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
创建 UAP 需要以下权限:
-
iam.accesspolicies.create -
在 Cloud de Confiance 控制台中创建 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
您可以使用 Cloud de Confiance 控制台、gcloud CLI 或 IAM REST API 创建 UAP。
控制台
-
在 Cloud de Confiance 控制台中,前往 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 组织政策限制条件。如需了解如何启用或停用此限制条件,请参阅在组织政策中使用托管式限制条件。
您可以使用 Cloud de Confiance 控制台、gcloud CLI 或 IAM REST API 将 UAP 应用于项目、文件夹和组织。如需将 UAP 应用于其他资源,您必须使用 gcloud CLI 或 IAM REST API。
控制台
-
在 Cloud de Confiance 控制台中,前往 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 时,操作完成,您可以停止获取操作。