通过主账号访问边界 (PAB) 政策,您可以限制一组主账号有资格访问的资源。本页面介绍了如何创建和应用主账号访问权限边界政策。
准备工作
设置身份验证。
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
REST
如需在本地开发环境中使用本页面上的 REST API 示例,请使用您提供给 gcloud CLI 的凭据。
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
如需了解详情,请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。
创建主账号访问权限边界政策所需的角色
如需获得创建主账号访问权限边界政策所需的权限,请让您的管理员为您授予组织的 Principal Access Boundary Admin (
roles/iam.principalAccessBoundaryAdmin
) IAM 角色。如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。此预定义角色可提供创建主账号访问权限边界政策所需的
iam.principalaccessboundarypolicies.create
权限。应用主账号访问权限边界政策所需的角色
应用主账号访问权限边界政策所需的权限取决于您要应用该政策的主账号集。
如需获得应用主账号访问权限边界政策所需的权限,请让您的管理员为您授予以下 IAM 角色:
-
针对组织的 Principal Access Boundary User (
roles/iam.principalAccessBoundaryUser
) - 将主账号访问权限边界政策应用于员工身份池:针对目标员工身份池的 IAM Workforce Pool Admin (
roles/iam.workforcePoolAdmin
) -
将主账号访问权限边界政策应用于工作负载身份池:针对拥有目标工作负载身份池的项目的 IAM Workload Identity Pool Admin (
roles/iam.workloadIdentityPoolAdmin
) -
获取针对工作负载身份池应用主账号访问权限边界政策的长时间运行操作的状态:针对拥有目标工作负载身份池的项目的 IAM Operation Viewer (
roles/iam.operationViewer
) -
将主账号访问权限边界政策应用于 Google Workspace 网域:组织的 Workspace Pool IAM Admin (
roles/iam.workspacePoolAdmin
) -
将主账号访问权限边界政策应用于项目的主账号集:项目的 Project IAM Admin (
roles/resourcemanager.projectIamAdmin
) -
获取将主账号访问权限边界政策应用于项目的主账号集的长时间运行操作的状态:针对项目的 IAM Operation Viewer (
roles/iam.operationViewer
) -
将主账号访问权限边界政策应用于文件夹的主账号集:文件夹的 Folder IAM Admin (
roles/resourcemanager.folderIamAdmin
) -
将主账号访问权限边界政策应用于组织的主账号集:针对组织的 Organization Administrator (
roles/resourcemanager.organizationAdmin
)
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
这些预定义角色包含应用主账号访问权限边界政策所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
应用主账号访问权限边界政策需要以下权限:
-
针对组织的
iam.principalaccessboundarypolicies.bind
权限 -
将主账号访问权限边界政策应用于员工身份联合池:目标员工身份联合池的
iam.workforcePools.createPolicyBinding
-
将主账号访问权限边界政策应用于工作负载身份联合池:拥有目标员工身份联合池的项目的
iam.workloadIdentityPools.createPolicyBinding
-
获取针对工作负载身份池应用主账号访问权限边界政策的长时间运行操作的状态:针对拥有目标工作负载身份池的项目的
iam.operations.get
-
将主账号访问权限边界政策应用于 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 控制台中,前往主账号访问权限边界政策页面。
选择要为其创建主账号访问权限边界政策的组织。
点击
创建政策。向政策添加主账号访问边界规则:
- 点击 添加边界规则。
- 在说明字段中,添加主账号访问权限边界政策规则的说明。说明最多可包含 256 个字符。
在资源部分,输入您希望主账号有资格访问的所有 Resource Manager 资源(项目、文件夹和组织)。任何受此政策约束的主账号都有权访问这些资源。
每个主账号访问权限边界政策在其所有规则中最多可以引用 500 个资源。
点击完成。
如需添加其他政策规则,请重复执行上述步骤。每个主账号访问权限边界政策最多可以包含 500 条规则。
在政策名称部分中,输入政策的名称。名称最多可以包含 63 个字符。
在强制执行版本列表中,选择相应政策的强制执行版本。主账号访问权限边界政策版本决定了 IAM 会针对哪些权限强制执行主账号访问权限边界政策。
如需详细了解强制执行版本,请参阅主账号访问权限边界强制执行版本。
点击创建。
gcloud
gcloud iam principal-access-boundary-policies create
命令可创建主账号访问权限边界政策。在使用下面的命令数据之前,请先进行以下替换:
ORG_ID
:您要在其中创建主账号访问权限边界政策的组织的 ID。组织 ID 是数字,例如123456789012
。-
PAB_POLICY_ID
:主账号访问权限边界政策的唯一 ID,例如example-policy
。: 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
和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
和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 ], "effect": ALLOW } ], "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 控制台中,前往主账号访问权限边界政策页面。
选择拥有您要为其创建绑定的主账号访问权限边界政策的组织。
点击要为其创建绑定的主账号访问权限边界政策的政策 ID。
点击绑定关系标签页,然后点击
添加绑定关系。输入绑定详细信息:
- 可选:在显示名称字段中,输入该绑定的显示名称。显示名称最多可以包含 63 个字符。
- 在绑定 ID 字段中,输入绑定的唯一名称,例如
example-binding
。 在目标主账号集部分中,输入您要将政策绑定到的主账号集的类型和 ID。创建政策绑定后,您无法更改此值。
如需详细了解每个主账号集中包含的主账号,请参阅支持的主账号集。
(可选)如需指定要为主账号集中的哪些主账号强制执行主账号访问权限边界政策,请向绑定添加条件:
- 点击 添加条件。
- 在标题字段中,输入条件目的的简要摘要。
- 可选:在说明字段中,输入条件的详细说明。
- 在表达式字段中,输入使用通用表达式语言 (CEL) 语法的条件表达式。该表达式必须引用
principal.type
或principal.subject
属性。不支持其他属性。 - 点击保存。
如需创建绑定,请点击添加。
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
:您要将其绑定到主账号集的主账号访问权限边界政策的 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_ID \ --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_ID ` --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_ID ^ --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
:您要将其绑定到主账号集的主账号访问权限边界政策的 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/principalAccessBoundaryPolicies/example-policy", "verb": "create", "requestedCancellation": false, "apiVersion": "v3" }, "done": true, "response": { PAB_POLICY } }
如果操作的
done
字段不存在,请重复获取操作,以持续监控其状态。使用截断指数退避算法在每个请求之间引入延迟。当done
字段设置为true
时,操作完成,您可以停止获取操作。后续步骤
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-02-18。