修改 Unified Access Policies

借助 Unified Access Policies (UAP),您可以向主账号授予或拒绝其对Google Cloud 资源的访问权限。本文档介绍了如何修改现有 UAP 以及如何修改 UAP 适用的资源。

准备工作

  1. 设置身份验证。

    选择标签页以了解您打算如何使用本页面上的示例:

    控制台

    当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时,无需设置身份验证。

    gcloud

    在 Google Cloud 控制台中,激活 Cloud Shell。

    激活 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 时进行身份验证。

  2. 验证是否已为您的 Google Cloud 项目启用结算功能。

  3. 可选。阅读 UAP 概览。

所需的角色

如需获得修改 UAP 所需的权限,请让管理员向您授予您要修改的 UAP 所属的项目、文件夹或组织的 Access Policy Admin (roles/iam.accessPolicyAdmin) IAM 角色。 如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含修改 UAP 所需的权限。如需查看所需的确切权限,请展开所需权限部分:

所需权限

修改 UAP 需要以下权限:

  • iam.accesspolicies.update
  • 在 Google Cloud 控制台中修改 UAP:
    • iam.accesspolicies.get
    • iam.accessPolicies.list

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

修改现有的统一访问权限政策

您可以修改 UAP,以更新其显示名称或规则。

您可以使用 Google Cloud 控制台、gcloud CLI 或 IAM REST API 修改 UAP。

控制台

  1. 在 Google Cloud 控制台中,前往 Unified Access Policies 页面。

    前往“Unified Access Policies”
  2. 选择拥有您要修改的 UAP 的项目、文件夹或组织。
  3. 点击您要修改的 UAP 的政策 ID。
  4. 如需添加规则,请点击 添加规则,然后添加规则的详细信息。如需保存规则,请点击添加规则。

    如需详细了解规则的字段,请参阅创建 UAP。

  5. 如需修改 UAP 的其他字段,请点击 修改政策。
  6. 修改以下任一字段:

    • 政策名称:为 UAP 输入新的显示名称。
    • 规则:更新、添加或移除 UAP 中的规则。
  7. 修改完 UAP 后,点击更新政策。

gcloud

gcloud iam access-policies update 命令可更新现有的 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。
  • FIELD_TO_UPDATE=UPDATED_VALUE:您要更新的字段及其对应的更新值。

    以下是可用于更新政策中的字段的标志示例:

    • --display-name=DISPLAY_NAME:将 UAP 的显示名称替换为指定名称。
    • --details-rules=RULES_FILE:将 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 群组添加到包含的主账号列表中,然后排除属于该群组的特定用户。

        如需查看支持的主账号标识符列表,请参阅 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,则该规则不适用于访问尝试。

        如需查看支持状态属性及其服务的列表,请参阅支持的条件属性。

    • --add-details-rules=RULES_FILE:将指定文件中的规则附加到 UAP 中的现有规则。

    • --remove-details-rules=RULES_FILE:从 UAP 中的现有规则中移除指定文件中的规则。系统仅会移除与指定文件中某个规则完全匹配的规则。

    • --clear-details-rules:从 UAP 中清除所有规则。

    如需查看可用于更新 UAP 的标志的完整列表,请参阅 gcloud iam access-policies update 命令参考文档。某些标志是互斥的。

  • FORMAT:响应的格式。请使用 json 或 yaml。

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud iam access-policies update UAP_ID \
    --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID \
    --location=global --FIELD_TO_UPDATE=UPDATED_VALUE \
    --format=FORMAT

Windows (PowerShell)

gcloud iam access-policies update UAP_ID `
    --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID `
    --location=global --FIELD_TO_UPDATE=UPDATED_VALUE `
    --format=FORMAT

Windows (cmd.exe)

gcloud iam access-policies update UAP_ID ^
    --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ^
    --location=global --FIELD_TO_UPDATE=UPDATED_VALUE ^
    --format=FORMAT

响应包含表示请求的长时间运行的操作。操作完成后,响应会输出更新后的 UAP。

Request issued for: [example-policy]
Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374208720-6181fae5e2034-2d8a712b-5c92e5b9] to complete...done.
Updated accessPolicy [example-policy].
{
  "createTime": "2026-08-31T21:43:39.822441Z",
  "details": {
    "rules": [
      {
        "conditions": {
          "iam.googleapis.com": {
            "expression": "resource.matchTag('environment', 'prod')"
          }
        },
        "description": "Grant non-delete compute permissions to compute admins in prod",
        "effect": "ALLOW",
        "excludedPrincipals": [
          "principal://goog/subject/access-restricted@example.com"
        ],
        "operation": {
          "excludedPermissions": [
            "*/*.delete"
          ],
          "permissions": [
            "role:roles/compute.admin"
          ]
        },
        "principals": [
          "principalSet://goog/group/compute-admins@example.com"
        ]
      }
    ]
  },
  "displayName": "Updated display name",
  "etag": "W/\"YZtdQgtulCVzvTwlBTFjPQ==\"",
  "name": "projects/0123456789012/locations/global/accessPolicies/example-policy",
  "uid": "puid_0123456789012345678",
  "updateTime": "2026-08-31T21:43:39.822441Z"
}

REST

accessPolicies.patch 方法可更新现有的 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 方法和网址:

PATCH https://iam.googleapis.com/v3/UAP_PARENT_RESOURCE_TYPE/UAP_PARENT_RESOURCE_ID/locations/global/accessPolicies/UAP_ID

请求 JSON 正文:

{
  "displayName": "DISPLAY_NAME",
  "details": {
    "rules": [
      UAP_RULES
    ]
  }
}

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

响应包含表示请求的长时间运行的操作。如需了解如何获取长时间运行的操作的状态,请参阅本页面上的检查长时间运行的操作的状态。

{
  "name": "organizations/123456789012/locations/global/operations/operation-1715626721931-6185a7953ef76-76f80ee4-19cd1bf7",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2026-05-13T18:58:43.721277235Z",
    "target": "organizations/123456789012/locations/global/accessPolicies/example-policy",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": false
}

更改政策适用的资源

为 UAP 创建绑定后,您将无法更改绑定中的政策 ID 或资源。因此,如果您要更改 UAP 适用的资源,则必须执行以下操作之一:

检查长时间运行的操作的状态

使用 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 时,操作完成,您可以停止获取操作。

后续步骤