创建和应用主账号访问边界政策

借助 Principal Access Boundary (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.

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 的凭据。
如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。
阅读主账号访问权限边界政策概览。

创建 Principal Access Boundary Policy 所需的角色

如需获得创建主账号访问权限边界政策所需的权限，请让您的管理员为您向组织授予 Principal Access Boundary Admin (roles/iam.principalAccessBoundaryAdmin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含创建主账号访问权限边界政策所需的 iam.principalaccessboundarypolicies.create 权限。

您也可以使用自定义角色或其他预定义角色来获取此权限。

应用主账号访问权限边界政策所需的角色

您需要具备的权限取决于您要将主账号访问边界政策应用到的主账号集。

如需获得应用主账号访问权限边界政策所需的权限，请让您的管理员向您授予以下 IAM 角色：

组织的主账号访问边界用户 (roles/iam.principalAccessBoundaryUser)
将主账号访问权限边界政策应用于员工身份联合网关池：目标员工身份联合池的 IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin)
将主账号访问权限边界政策应用于工作负载身份联合池：拥有目标员工身份联合池的项目的 IAM Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin)
将主账号访问权限边界政策应用于 Google Workspace 网域：组织的 Workspace Pool IAM Admin (roles/iam.workspacePoolAdmin)
将主账号访问权限边界政策应用于项目的主账号集：项目的 Project IAM Admin (roles/resourcemanager.projectIamAdmin)
将主账号访问权限边界政策应用于文件夹的主账号集：文件夹的 Folder IAM Admin (roles/resourcemanager.folderIamAdmin)
将主账号访问权限边界政策应用于组织的主账号集：组织的 Organization Administrator (roles/resourcemanager.organizationAdmin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含应用主账号访问权限边界政策所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

您需要具备以下权限才能应用主账号访问权限边界政策：

针对组织的 iam.principalaccessboundarypolicies.bind 权限
将主账号访问权限边界政策应用于员工身份联合池：目标员工身份联合池的 iam.workforcePools.createPolicyBinding
将主账号访问权限边界政策应用于工作负载身份联合池：拥有目标员工身份联合池的项目的 iam.workloadIdentityPools.createPolicyBinding
将主账号访问权限边界政策应用于 Google Workspace 网域：组织的 iam.workspacePools.createPolicyBinding
将主账号访问权限边界政策应用于项目的主账号集：项目的 resourcemanager.projects.createPolicyBinding
将主账号访问权限边界政策应用于文件夹的主账号集：文件夹的 resourcemanager.folders.createPolicyBinding
将主账号访问权限边界政策应用于组织的主账号集：组织的 resourcemanager.organizations.createPolicyBinding

您也可以使用自定义角色或其他预定义角色来获取这些权限。

创建 Principal Access Boundary Policy

您可以使用 Google Cloud 控制台、gcloud CLI 或 IAM REST API 创建主账号访问权限边界政策。

控制台

在 Google Cloud 控制台中，前往主账号访问权限边界政策页面。

前往“主账号访问权限边界政策”
选择要为其创建主账号访问边界政策的组织。
点击 创建政策。
向政策添加主账号访问边界规则：
1. 点击 添加边界规则。
2. 在说明字段中，添加对主账号访问权限边界政策规则的说明。说明最多可包含 256 个字符。
3. 在资源部分中，输入您希望主账号有权访问的所有资源管理器资源（项目、文件夹和组织）。任何受此政策约束的主账号都有权访问这些资源。
  
  每个主账号访问权限边界政策在政策中的所有规则中最多可以引用 500 个资源。
4. 点击完成。
5. 如需添加其他政策规则，请重复执行上述步骤。每个主账号访问边界政策最多可以包含 500 条规则。
在政策名称部分中，输入政策的名称。名称最多可以包含 63 个字符。
在强制执行版本列表中，选择相应政策的强制执行版本。主账号访问权限边界政策版本决定了 IAM 会针对哪些权限强制执行主账号访问权限边界政策。

如需详细了解强制执行版本，请参阅主账号访问边界强制执行版本。
点击创建。

gcloud

gcloud beta 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 beta 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 beta 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 beta 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/v3beta/organizations/ORG_ID/locations/global?principalAccessBoundaryPolicyId=PAB_POLICY_ID

请求 JSON 正文：

{
  "displayName": DISPLAY_NAME,
  "details": {
    "rules": [
      PAB_RULES
    ],
    "effect": ALLOW
    }
  ],
  "enforcementVersion": "ENFORCEMENT_VERSION"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v3beta/organizations/ORG_ID/locations/global?principalAccessBoundaryPolicyId=PAB_POLICY_ID"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v3beta/organizations/ORG_ID/locations/global?principalAccessBoundaryPolicyId=PAB_POLICY_ID" | Select-Object -Expand Content

响应包含表示您的请求的长时间运行的操作。

{
  "name": "organizations/123456789012/locations/global/operations/operation-1715373120647-6181f6d8371d2-83309b71-2b8a7532",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3beta.OperationMetadata",
    "createTime": "2024-05-10T20:32:00.898809495Z",
    "target": "organizations/123456789012/locations/global/policyBindings/example-policy",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3beta"
  },
  "done": false
}

将主账号访问权限边界政策应用于主账号集

如需将 Principal Access Boundary Policy 应用于主账号集，请创建将该政策绑定到主账号集的政策绑定资源。创建政策绑定后，系统会对绑定中的主账号强制执行绑定中的主要账号访问边界政策。

您可以使用 Google Cloud 控制台、gcloud CLI 或 IAM REST API 创建政策绑定。

控制台

在 Google Cloud 控制台中，前往主账号访问权限边界政策页面。

前往“主账号访问权限边界政策”
选择拥有您要为其创建绑定的主账号访问边界政策的组织。
点击要为其创建绑定的 Principal Access Boundary Policy 的政策 ID。
点击绑定关系标签页，然后点击 添加绑定关系。
输入绑定详情：
1. 可选：在显示名称字段中，输入该绑定的显示名称。显示名称最多可以包含 63 个字符。
2. 在绑定 ID 字段中，输入绑定的唯一名称，例如 example-binding。
3. 在目标主账号集部分中，输入要将政策绑定到的主账号集的类型和 ID。创建政策绑定后，您无法更改此值。
  
  如需详细了解每个主账号集中包含的主账号，请参阅支持的主账号集。
可选：如需指定要针对哪些主账号设置主账号访问权限边界政策，请向绑定添加条件：
1. 点击 添加条件。
2. 在标题字段中，输入条件用途的简要摘要。
3. 可选：在说明字段中，输入条件的详细说明。
4. 在表达式字段中，输入使用通用表达式语言 (CEL) 语法的条件表达式。表达式必须引用 principal.type 或 principal.subject 属性。不支持其他属性。
5. 点击保存。
如需创建绑定，请点击添加。

gcloud

gcloud beta 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 beta 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 beta 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 beta 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/v3beta/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
  }
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v3beta/RESOURCE_TYPE/RESOURCE_ID/locations/global/policyBindings?policyBindingId=BINDING_ID"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v3beta/RESOURCE_TYPE/RESOURCE_ID/locations/global/policyBindings?policyBindingId=BINDING_ID" | Select-Object -Expand Content

响应包含表示您的请求的长时间运行的操作。

{
  "name": "organizations/123456789012/locations/global/operations/operation-1715373120647-6181f6d8371d2-83309b71-2b8a7532",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3beta.OperationMetadata",
    "createTime": "2024-05-10T20:32:00.898809495Z",
    "target": "organizations/123456789012/locations/global/policyBindings/example-binding",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3beta"
  },
  "done": false
}

创建和应用主账号访问边界政策

准备工作

Console

gcloud

REST

创建 Principal Access Boundary Policy 所需的角色

应用主账号访问权限边界政策所需的角色

所需权限

创建 Principal Access Boundary Policy

控制台

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

将主账号访问权限边界政策应用于主账号集

控制台

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

后续步骤