Edit principal access boundary policies

Principal access boundary (PAB) policies let you limit the resources that a set of principals are eligible to access. This page explains how to edit existing principal access boundary policies, and how to edit policy bindings for principal access boundary policies to change who the policies apply to.

Before you begin

  • Set up authentication.

    Select the tab for how you plan to use the samples on this page:

    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

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

  • Read the overview of principal access boundary policies.

Roles required to edit principal access boundary policies

To get the permission that you need to edit principal access boundary policies, ask your administrator to grant you the Principal Access Boundary Admin (roles/iam.principalAccessBoundaryAdmin) IAM role on your organization. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the iam.principalaccessboundarypolicies.update permission, which is required to edit principal access boundary policies.

You might also be able to get this permission with custom roles or other predefined roles.

Roles required to edit principal access boundary policy bindings

The permissions that you need in order to edit policy bindings for principal access boundary policies depends on the principal set that's bound to the policy.

To get the permissions that you need to edit policy bindings for principal access boundary policies, ask your administrator to grant you the following IAM roles:

  • Principal Access Boundary User (roles/iam.principalAccessBoundaryUser) on your organization
  • Edit policy bindings for principal access boundary policies bound to Workforce Identity Federation pools: IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin) on the target Workforce Identity Federation pool
  • Edit policy bindings for principal access boundary policies bound to Workload Identity Federation pools: IAM Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) on the project that owns the target Workforce Identity Federation pool
  • Edit policy bindings for principal access boundary policies bound to a Google Workspace domain: Workspace Pool IAM Admin (roles/iam.workspacePoolAdmin) on the organization
  • Edit policy bindings for principal access boundary policies bound to a project's principal set: Project IAM Admin (roles/resourcemanager.projectIamAdmin) on the project
  • Edit policy bindings for principal access boundary policies bound to a folder's principal set: Folder IAM Admin (roles/resourcemanager.folderIamAdmin) on the folder
  • Edit policy bindings for principal access boundary policies bound to an organization's principal set: Organization Administrator (roles/resourcemanager.organizationAdmin) on the organization

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to edit policy bindings for principal access boundary policies. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to edit policy bindings for principal access boundary policies:

  • iam.principalaccessboundarypolicies.bind on the organization
  • Edit policy bindings for principal access boundary policies bound to Workforce Identity Federation pools: iam.workforcePools.updatePolicyBinding on the target Workforce Identity Federation pool
  • Edit policy bindings for principal access boundary policies bound to Workload Identity Federation pools: iam.workloadIdentityPools.updatePolicyBinding on the project that owns the target Workforce Identity Federation pool
  • Edit policy bindings for principal access boundary policies bound to a Google Workspace domain: iam.workspacePools.updatePolicyBinding on the organization
  • Edit policy bindings for principal access boundary policies bound to a project's principal set: resourcemanager.projects.updatePolicyBinding on the project
  • Edit policy bindings for principal access boundary policies bound to a folder's principal set: resourcemanager.folders.updatePolicyBinding on the folder
  • Edit policy bindings for principal access boundary policies bound to an organization's principal set: resourcemanager.organizations.updatePolicyBinding on the organization

You might also be able to get these permissions with custom roles or other predefined roles.

Edit an existing principal access boundary policy

If you want to add rules to a principal access boundary policy, remove rules from a principal access boundary policy, or modify a principal access boundary policy's metadata, edit the principal access boundary policy.

You can edit a principal access boundary policy using the Google Cloud console, the gcloud CLI, or the IAM REST API.

Console

  1. In the Google Cloud console, go to the Principal Access Boundary policies page.

    Go to Principal Access Boundary policies

  2. Select the organization that owns the principal access boundary policy that you want to edit.

  3. Click the policy ID of the principal access boundary policy that you want to edit.

  4. Click Edit policy.

  5. To edit the policy's rules, do the following:

    1. Click the rule that you want to edit.
    2. Edit the rule's description, or the resources included in the rule.
    3. Click Done.

  6. To delete a rule from the policy, click Delete in that rule's row.

  7. To edit the policy's display name, edit the Display name field.

  8. To edit the policy's enforcement version, click the Enforcement version list and choose a new value.

  9. Click Save.

gcloud

The gcloud beta iam principal-access-boundary-policies update command updates an existing principal access boundary policy.

Before using any of the command data below, make the following replacements:

  • PAB_POLICY_ID: The ID of the principal access boundary policy that you want to update—for example, example-policy.
  • ORG_ID: The ID of the organization that owns the principal access boundary policy. Organization IDs are numeric, like 123456789012.

  • FIELD_TO_UPDATE=UPDATED_VALUE: The fields that you want to update and the corresponding updated value.

    The following are examples of flags that you can use to update the fields in the policy:

    • --display-name=DISPLAY_NAME: Replace the display name of the policy with DISPLAY_NAME.
    • --details-enforcement-version=ENFORCEMENT_VERSION: Update the policy's enforcement version to ENFORCEMENT_VERSION.

    • --details-rules=RULES_FILE.json: Replace the principal access boundary policy's rules with the rules in RULES_FILE.json. To learn how to format the rules file, see Create a principal access boundary policy.

      If you use this flag, you can't use the --add-details-rules flag.

    • --add-details-rules=RULES_FILE: Append the rules in RULES_FILE.json to the policy's existing rules. To learn how to format the rules file, see Create a principal access boundary policy.

      If you use this flag, you can't use --details-rules flag.

    • --remove-details-rules=RULES_FILE: Remove the rules in RULES_FILE.json from the policy's existing rules. To learn how to format the rules file, see Create a principal access boundary policy. Only rules that exactly match one of the rules in RULES_FILE.json are removed.

      If you use this flag, you can't use --clear-rule-details flag.

    • --clear-details-rules: Clear all rules from the principal access boundary policy.

      If you use this flag, you can't use --remove-rule-details flag.

    For a full list of flags that you can use to update a principal access boundary policy, see the gcloud beta iam principal-access-boundary-policies update command reference.

  • FORMAT: The format for the response. Use json or yaml.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta iam principal-access-boundary-policies update PAB_POLICY_ID \
    --organization=ORG_ID --location=global \
    --FIELD_TO_UPDATE=UPDATED_VALUE \
    --format=FORMAT

Windows (PowerShell)

gcloud beta iam principal-access-boundary-policies update PAB_POLICY_ID `
    --organization=ORG_ID --location=global `
    --FIELD_TO_UPDATE=UPDATED_VALUE `
    --format=FORMAT

Windows (cmd.exe)

gcloud beta iam principal-access-boundary-policies update PAB_POLICY_ID ^
    --organization=ORG_ID --location=global ^
    --FIELD_TO_UPDATE=UPDATED_VALUE ^
    --format=FORMAT

The response contains a long-running operation representing your request. After the operation is complete, the response prints the updated principal access boundary policy. 

Request issued for: [example-policy]
Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374208720-6181fae5e2034-2d8a712b-5c92e5b9] to complete...done.
Updated principalAccessBoundaryPolicy [example-policy].
{
  "name": "organizations/123456789012/locations/global/principalAccessBoundaryPolicies/example-policy",
  "uid": "puid_13364150419245236225",
  "etag": "W/\"Gh/PcTdJD/AWHUhPW45kdw==\"",
  "displayName": "Updated display name",
  "createTime": "2024-05-07T00:05:48.295209Z",
  "updateTime": "2024-05-10T20:50:09.200421Z",
  "details": [
    "rules": {
      [
        "description": "Make principals eligible to access example.com"
        "resources": {
          "//cloudresourcemanager.googleapis.com/organizations/123456789012"
        },
        "effect": ALLOW
      ]
    },
    "enforcementVersion": "1"
  ]
}

REST

The principalAccessBoundaryPolicies.patch method updates an existing principal access boundary policy.

Before using any of the request data, make the following replacements:

  • ORG_ID: The ID of the organization that owns the principal access boundary policy. Organization IDs are numeric, like 123456789012.
  • PAB_POLICY_ID: The ID of the principal access boundary policy that you want to update—for example, example-policy.

  • FIELDS_TO_UPDATE: A comma-separated list of fields that you want to update. If you don't specify the fields to update, IAM replaces the existing policy with the content of the request body.

    Accepted values are displayName, details, details.rules, details.rules.description, details.rules.resources, details.rules.effect and details.enforcementVersion.

  • DISPLAY_NAME: Optional. A human-readable description of the principal access boundary policy—for example, Example policy. The display name can be a maximum of 63 characters.

  • PAB_RULES: A list of principal access boundary rules, which define the resources that affected principals are eligible to access. A principal access boundary policy can have up to 500 rules. Each rule has the following format: 

    {
"description": "DESCRIPTION",
"resources": [
  RESOURCES
],
"effect": ALLOW
}

    Replace the following values:

    • DESCRIPTION: Optional. The description of the principal access boundary policy rule. The description can be a maximum of 256 characters.

    • RESOURCES: A list of Resource Manager resources (projects, folders, and organizations) that you want principals to be eligible to access. Any principal that is subject to this policy is eligible to access these resources.

      Each principal access boundary policy can reference a maximum of 500 resources across all rules in the policy.

  • ENFORCEMENT_VERSION: The version of principal access boundary policies that IAM uses when enforcing the policy. The enforcement version determines which permissions IAM enforces the principal access boundary policy for.

    Accepted values are 1 and latest.

    For more information about enforcement versions, see Principal access boundary enforcement versions.

HTTP method and URL: 

PATCH https://iam.googleapis.com/v3beta/organizations/ORG_ID/locations/global/principalAccessBoundaryPolicies/PAB_POLICY_ID?updateMask=FIELDS_TO_UPDATE

Request JSON body: 

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

To send your request, expand one of these options:

The response contains a long-running operation representing your request.

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

Change who a principal access boundary policy is enforced for

After you create a policy binding for a principal access boundary policy, you can't change the policy ID or the principal set in the binding. As a result, if you want to change who a principal access boundary policy is enforced for, you must do one of the following:

  • To refine the set of principals that a principal access boundary policy is enforced for, you can modify the conditions in the policy binding. To modify the conditions in a binding, edit the policy binding.
  • To enforce the principal access boundary policy for an additional principal set, create a new policy binding that binds the policy to that principal set.
  • To remove a principal access boundary policy from a principal set, delete the policy binding that binds the policy to the principal set.

Edit existing policy bindings for principal access boundary policies

After you create a policy binding, you can edit the binding to modify the conditions in the binding or the display name of the binding.

You can edit a policy binding using the Google Cloud console, the gcloud CLI, or the IAM REST API.

Console

  1. In the Google Cloud console, go to the Principal Access Boundary policies page.

    Go to Principal Access Boundary policies

  2. Select the organization that owns the principal access boundary policy that you want to edit.

  3. Click the policy ID of the principal access boundary policy whose bindings you want to edit.

  4. Click the Bindings tab.

  5. Find the ID of the binding that you want to edit. In that binding's row, click Actions, then click Edit binding.

  6. To update the binding's display name, edit the Display name field.

  7. To add a condition to the binding, do the following:

    1. Click Add condition.
    2. In the Title field, enter a brief summary of the purpose of the condition.
    3. Optional: In the Description field, enter a longer description of the condition.
    4. In the Expression field, enter condition expression that uses the Common Expression Language (CEL) syntax. The expression must reference the principal.type or principal.subject attributes. Other attributes are not supported.
    5. Click Save.

  8. To update an existing condition, do the following:

    1. Click Edit condition next to the name of the condition.
    2. Update the condition's title, description, or expression.
    3. Click Save.

  9. To save your changes, click Save.

gcloud

The gcloud beta iam policy-bindings update command updates an existing policy binding.

Before using any of the command data below, make the following replacements:

  • BINDING_ID: The ID of the policy binding that you want to update—for example, example-binding.

  • RESOURCE_TYPE: The type of the Resource Manager resource (project, folder, or organization) that the policy binding is a child of. Use the value project, folder, or organization

    The resource type depends on the principal set in the policy binding. To see which resource type to use, see Supported principal types.

  • RESOURCE_ID: The ID of the project, folder, or organization that the policy binding is a child of. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.

  • FIELD_TO_UPDATE=UPDATED_VALUE: The fields that you want to update and the corresponding updated value.

    The following are examples of flags that you can use to update the fields in a policy binding:

    • --display-name=DISPLAY_NAME: Replace the display name of the binding with DISPLAY_NAME.
    • --condition-description=CONDITION_DESCRIPTION: If the binding has a condition, replace the condition's description with CONDITION_DESCRIPTION. Otherwise, add a new condition to the binding with the specified description. If you use this flag to update a binding that doesn't have a condition, you must also set the --condition-expression flag.
    • --condition-expression=CONDITION_EXPRESSION: If the binding has a condition, replace the condition's expression with CONDITION_EXPRESSION. Otherwise, add a new condition to the binding with the specified expression.
    • --condition-title=CONDITION_TITLE: If the binding has a condition, replace the condition's title with CONDITION_TITLE. Otherwise, add a new condition to the binding with the specified title. If you use this flag to update a binding that doesn't have a condition, you must also set the --condition-expression flag.

    For a full list of fields you can update, see the gcloud beta iam policy-bindings update command reference.

  • FORMAT: The format for the response. Use json or yaml.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta iam policy-bindings update BINDING_ID \
    --RESOURCE_TYPE=RESOURCE_ID --location=global \
    --FIELD_TO_UPDATE=UPDATED_VALUE \
    --format=FORMAT

Windows (PowerShell)

gcloud beta iam policy-bindings update BINDING_ID `
    --RESOURCE_TYPE=RESOURCE_ID --location=global `
    --FIELD_TO_UPDATE=UPDATED_VALUE `
    --format=FORMAT

Windows (cmd.exe)

gcloud beta iam policy-bindings update BINDING_ID ^
    --RESOURCE_TYPE=RESOURCE_ID --location=global ^
    --FIELD_TO_UPDATE=UPDATED_VALUE ^
    --format=FORMAT

The response contains a long-running operation representing your request.

Update request issued for: [my-binding]
Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374545618-6181fc272c6f9-55ff07f4-97d0ac76] to complete...done.
Updated policyBinding [my-binding].
{
  "createTime": "2024-05-06T18:08:24.729843Z",
  "displayName": "Updated display name",
  "etag": "W/\"xkdnPfTxoxyVqOwhQSJbMg==\"",
  "name": "organizations/123456789012/locations/global/policyBindings/example-binding",
  "policy": "organizations/123456789012/locations/global/principalAccessBoundaryPolicies/example-pab-policy",
  "policyKind": "PRINCIPAL_ACCESS_BOUNDARY",
  "policyUid": "puid_9519202237377675265",
  "target": {
    "principalSet": "//cloudresourcemanager.googleapis.com/organizations/123456789012"
  },
  "uid": "buid_9904260005517852673", 
  "updateTime": "2024-05-06T18:11:16.798841Z"
}

REST

The policyBindings.patch method updates an existing policy binding.

Before using any of the request data, make the following replacements:

  • RESOURCE_TYPE: The type of the Resource Manager resource (project, folder, or organization) that the policy binding is a child of. Use the value projects, folders, or organizations

    The resource type depends on the principal set in the policy binding. To see which resource type to use, see Supported principal types.

  • RESOURCE_ID: The ID of the project, folder, or organization that the policy binding is a child of. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
  • BINDING_ID: The ID of the policy binding that you want to update—for example, example-binding.

  • FIELDS_TO_UPDATE: A comma-separated list of fields that you want to update. If you don't specify the fields to update, IAM replaces the existing binding with the content of the request body.

    Accepted values are displayName, condition, condition.expression, condition.title, and condition.description.

  • DISPLAY_NAME: Optional. A human-readable description of the binding—for example, Example binding. The display name can be a maximum of 63 characters.

  • CONDITION_DETAILS: Optional. A condition expression that specifies which principals in the principal set the principal access boundary policy is enforced for. Contains the following fields:

    • expression: A condition expression that uses Common Expression Language (CEL) syntax. The expression must reference the principal.type or principal.subject attributes. Other attributes are not supported.

      The expression can contain up to 10 logical operators (&&, ||, !), and can be up to 250 characters long.

    • title: Optional. A brief summary of the purpose of the condition.
    • description: Optional. A longer description of the condition.

HTTP method and URL: 

POST https://iam.googleapis.com/v3beta/RESOURCE_TYPE/RESOURCE_ID/locations/global/policyBindings/BINDING_ID?updateMask=FIELDS_TO_UPDATE

Request JSON body: 

{
  "displayName": DISPLAY_NAME,
  "condition": {
    CONDITION_DETAILS
  }
}

To send your request, expand one of these options:

The response contains a long-running operation representing your request.

{
  "name": "organizations/123456789012/locations/global/operations/operation-1715373159010-6181f6fcccfa7-dcd0055c-00c22cad",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3beta.OperationMetadata",
    "createTime": "2024-05-10T20:32:39.254910121Z",
    "target": "organizations/123456789012/locations/global/policyBindings/example-binding",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v3beta"
  },
  "done": false
}

What's next