Troubleshoot IAM permissions

Policy Troubleshooter helps you understand whether a principal can access a resource. Given a principal, a resource, and a permission, Policy Troubleshooter examines the allow policies, deny policies, and principal access boundary (PAB) policies that impact the principal's access. Then, it tells you whether, based on those policies, the principal can use the specified permission to access the resource. It also lists the relevant policies and explains how they affect the principal's access.

You can access Policy Troubleshooter using the Google Cloud console, the Google Cloud CLI, or the REST API. For basic queries, using the Google Cloud console is typically fastest. For more complex scenarios, consider the gcloud CLI or the REST API.

Before you begin

Enable the Policy Troubleshooter API.
Roles required to enable APIs
To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Enable the API

Required permissions

To fully troubleshoot your principals' access, you need the following permissions.

Permissions to troubleshoot access for individual principals

Policy Troubleshooter analyzes a principal's access to a resource based on the allow policies, deny policies, principal access boundary policies, and roles that you have permission to view. If you don't have permission to view a policy that applies to a resource, or if you don't have permission to view a custom role, then you might not be able to tell whether a principal has access.

Permissions to troubleshoot allow and deny policies

To troubleshoot allow and deny policies, you need permissions on the organization that contains the resource that you want to troubleshoot. These permissions let you view the allow and deny policies that control access to the resource.

To get the permissions that you need to troubleshoot a principal's access, ask your administrator to grant you the following IAM roles on the organization that contains the resource that you want to troubleshoot access for:

Security Reviewer (roles/iam.securityReviewer)
Troubleshoot deny policies: Deny Reviewer (roles/iam.denyReviewer)
Troubleshoot policies that include bindings for service account principal sets: Browser (roles/browser)
Use the Google Cloud CLI to troubleshoot: Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

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

You might also be able to get the required permissions through custom roles or other predefined roles.

If you don't have permission to view the allow and deny policies for a resource, the access results for those allow and deny policies are Unknown.

Permissions to troubleshoot principal access boundary policies

To troubleshoot principal access boundary policies, you need permissions on the organization whose principal set includes the principal. The way you identify this organization depends on the principal type:

Google Accounts and Google groups: The organization associated with the Google Workspace domain that includes the principal
Federated identities (identities in workforce identity pools or workload identity pools): The organization that contains the identity pool that includes the principal
Service accounts: The organization that contains the project where the service account was created

These permissions let you view the principal access boundary policies that control what the principal can access.

To get the permissions that you need to troubleshoot a principal's access, ask your administrator to grant you the following IAM roles on the appropriate organization:

Principal Access Boundary Policy Viewer (roles/iam.principalAccessBoundaryViewer)
Troubleshoot principal access boundary policies bound to a project's, folder's, or organization's principal set: Organization Administrator (roles/resourcemanager.organizationAdmin)
Troubleshoot principal access boundary policies bound to Google Workspace domains: Workspace Pool IAM Admin (roles/iam.workspacePoolAdmin)
Troubleshoot principal access boundary policies bound to workforce identity pools: IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin)
Troubleshoot principal access boundary policies bound to workload identity pools: IAM Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin)

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

You might also be able to get the required permissions through custom roles or other predefined roles.

If you don't have permission to view the principal access boundary policies that apply to a principal, the access results for principal access boundary policies are Unknown.

Permissions to troubleshoot access for group members

If your allow and deny policies include groups, you need the Google Workspace Admin API permission groups.read to troubleshoot access for individual group members. Super Admins and Group Admins automatically have this permission. To give a user who is not a Super or Group admin this permission, create a custom Google Workspace administrator role that contains the groups.read privilege (located under Admin API Privileges) and grant it to the user.

If you don't have these permissions, role bindings and deny rules that contain groups or domains have an access result of Unknown, unless the role binding or deny rule also explicitly includes the principal.

Permissions to troubleshoot access for domain members

If your allow and deny policies include a Google Workspace account or Cloud Identity domain, you must be a domain administrator to troubleshoot access for individual domain members.

Troubleshoot access

To troubleshoot access, you need the principal, resource, and permission you want to check. This information can be provided by an error ID:

Error ID: A unique identifier for a permission error message. The error ID provides context for the error, including the principal, resource, permission, and supported IAM conditions.

Supported IAM conditions include principal.type and principal.subject.

If you don't have an error ID, you can troubleshoot access with the following information:

Principal: The email address to check. The email address must refer to a user, a single service account, or a service account principal set.

Other types of principals, including groups, domains, workforce identities, and workload identities, are not supported.
Resource: The full name of the resource that you want to troubleshoot access to. For example, to troubleshoot access to the project my-project, enter //cloudresourcemanager.googleapis.com/projects/my-project. For other types of resources, see the examples of full resource names.

Note: Policy Troubleshooter doesn't support evaluating allow policies set on Pub/Sub resources. If you want to check whether a principal has access to a Pub/Sub resource, first troubleshoot access for the resource's parent project, and then manually review the allow policy set on the Pub/Sub resource, if any.
Permission: The permission to check. If you use the Google Cloud console, it presents a list of suggestions as you type.

To troubleshoot a permission, the permission must be applicable for the resource in the request. In other words, it must be possible to use that permission to access the resource in some way. If the permission isn't applicable for the resource, then the request fails. For example, if you try to troubleshoot the compute.instances.get permission for a Google Kubernetes Engine cluster, then the request fails because the compute.instance.get permission can't be used to access Google Kubernetes Engine clusters.

For a complete list of permissions, see the permissions reference.

Console

To troubleshoot access, do the following:

In the Google Cloud console, go to the Policy Troubleshooter page.

Go to Policy Troubleshooter
If you have an error ID, select Error ID and enter it.
If you don't have an error ID, select Manual.
1. Enter the email of the principal whose access you want to check.
2. Enter the full resource name of the resource to check.
  
  If you don't know the full resource name, do one of the following:
  - If you're troubleshooting access for a project, folder, or organization, start typing to see autocomplete options.
  - If you're troubleshooting access for another resource type, click Browse to open the resource search dialog, then search for the resource:
    1. In the Select scope box, select a project, folder, or organization to search within.
    2. In the Resource type box, select the resource types you want to search for.
    3. In the Search for resources box, enter a portion of the resource name.
    4. In the results section, select the resource you want to check.
    5. Click Select to choose the resource and close the dialog.
3. Enter the permission to check.
  
  If you don't know the full permission name, start typing to see autocomplete options.
4. Optional: To check multiple resources and permissions, select Add Another Pair and repeat the previous step.
Click Check access.

gcloud

To find out why a principal has, or doesn't have, an IAM permission, use the gcloud beta policy-troubleshoot iam command.

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

VERSION: Optional. The version of the command to use. To troubleshoot access based on allow and deny policies only, don't specify a version. To troubleshoot access based on allow, deny, and principal access boundary policies, use the version beta.
EMAIL: The email address of the principal whose permissions you want to troubleshoot.
RESOURCE: The resource on which the permission is granted.
PERMISSION: The permission that you want to troubleshoot.

Execute the gcloud beta policy-troubleshoot iam command:

Linux, macOS, or Cloud Shell

gcloud VERSION policy-intelligence troubleshoot-policy iam RESOURCE --principal-email=EMAIL \
    --permission=PERMISSION

Windows (PowerShell)

gcloud VERSION policy-intelligence troubleshoot-policy iam RESOURCE --principal-email=EMAIL `
    --permission=PERMISSION

Windows (cmd.exe)

gcloud VERSION policy-intelligence troubleshoot-policy iam RESOURCE --principal-email=EMAIL ^
    --permission=PERMISSION

You should receive a response similar to the following:

Response

{
  "accessTuple": {
    "conditionContext": {
      "destination": {},
      "effectiveTags": [
        {
          "namespacedTagKey": "project-1/tag-key-1",
          "namespacedTagValue": "project-1/tag-key-1/tag-value-1",
          "tagKey": "tagKeys/123456789012",
          "tagKeyParentName": "projects/123456789012",
          "tagValue": "tagValues/123456789012"
        },
      ],
      "request": {},
      "resource": {}
    },
    "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/project-1",
    "permission": "bigtable.instances.create",
    "permissionFqdn": "bigtable.googleapis.com/instances.create",
    "principal": "service-account-3@project-1.iam.gserviceaccount.com"
  },
  "allowPolicyExplanation": {
    "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
    "explainedPolicies": [
      {
        "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
        "bindingExplanations": [
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "condition": {
              "expression": "resource.type == \"cloudresourcemanager.googleapis.com/Project\"",
              "title": "Resource-based condition"
            },
            "conditionExplanation": {
              "evaluationStates": [
                {
                  "end": 62,
                  "value": false
                }
              ],
              "value": false
            },
            "memberships": {
              "serviceAccount:service-account-1@project-1.iam.gserviceaccount.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL",
            "role": "roles/bigquery.admin",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL"
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "condition": {
              "expression": "resource.matchTag(\"project-1/tag-key-1\", \"tag-value-1\")",
              "title": "Tag-based condition"
            },
            "conditionExplanation": {
              "evaluationStates": [
                {
                  "end": 73,
                  "value": true
                }
              ],
              "value": true
            },
            "memberships": {
              "serviceAccount:service-account-2@project-1.iam.gserviceaccount.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL",
            "role": "roles/bigquery.admin",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL"
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "user:user-2@example.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL",
            "role": "roles/compute.admin",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL"
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "user:user-1@example.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              },
              "user:user-3@example.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL",
            "role": "roles/iam.serviceAccountTokenCreator",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL"
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "user:user-2@example.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              },
              "user:user-1@example.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_HIGH",
            "role": "roles/owner",
            "rolePermission": "ROLE_PERMISSION_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_HIGH"
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "combinedMembership": {
              "membership": "MEMBERSHIP_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "serviceAccount:service-account-3@project-1.iam.gserviceaccount.com": {
                "membership": "MEMBERSHIP_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              },
              "serviceAccount:service-account-4@project-1.iam.gserviceaccount.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL",
            "role": "roles/resourcemanager.projectIamAdmin",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL"
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "serviceAccount:service-account-4@project-1.iam.gserviceaccount.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL",
            "role": "roles/resourcemanager.tagViewer",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL"
          }
        ],
        "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/project-1",
        "policy": {
          "bindings": [
            {
              "condition": {
                "expression": "resource.type == \"cloudresourcemanager.googleapis.com/Project\"",
                "title": "Resource-based condition"
              },
              "members": [
                "serviceAccount:service-account-1@project-1.iam.gserviceaccount.com"
              ],
              "role": "roles/bigquery.admin"
            },
            {
              "condition": {
                "expression": "resource.matchTag(\"project-1/tag-key-1\", \"tag-value-1\")",
                "title": "Tag-based condition"
              },
              "members": [
                "serviceAccount:service-account-2@project-1.iam.gserviceaccount.com"
              ],
              "role": "roles/bigquery.admin"
            },
            {
              "members": [
                "user:user-2@example.com"
              ],
              "role": "roles/compute.admin"
            },
            {
              "members": [
                "user:user-1@example.com",
                "user:user-3@example.com"
              ],
              "role": "roles/iam.serviceAccountTokenCreator"
            },
            {
              "members": [
                "user:user-2@example.com",
                "user:user-1@example.com"
              ],
              "role": "roles/owner"
            },
            {
              "members": [
                "serviceAccount:service-account-3@project-1.iam.gserviceaccount.com",
                "serviceAccount:service-account-4@project-1.iam.gserviceaccount.com"
              ],
              "role": "roles/resourcemanager.projectIamAdmin"
            },
            {
              "members": [
                "serviceAccount:service-account-4@project-1.iam.gserviceaccount.com"
              ],
              "role": "roles/resourcemanager.tagViewer"
            }
          ],
          "etag": "BwYY6ttEMEY=",
          "version": 3
        },
        "relevance": "HEURISTIC_RELEVANCE_HIGH"
      },
    ],
    "relevance": "HEURISTIC_RELEVANCE_HIGH"
  },
  "denyPolicyExplanation": {
    "denyAccessState": "DENY_ACCESS_STATE_NOT_DENIED",
    "explainedResources": [
      {
        "denyAccessState": "DENY_ACCESS_STATE_NOT_DENIED",
        "explainedPolicies": [
          {
            "denyAccessState": "DENY_ACCESS_STATE_NOT_DENIED",
            "policy": {
              "createTime": "2024-04-09T23:28:24.103203Z",
              "displayName": "Troubleshooter v3 prober non-tag deny policy",
              "etag": "MTgyMzk3MDY4OTY4MDE0ODg4OTY=",
              "kind": "DenyPolicy",
              "name": "policies/cloudresourcemanager.googleapis.com%2Fprojects%2F546942305807/denypolicies/deny-policy-1",
              "rules": [
                {
                  "denyRule": {
                    "deniedPermissions": [
                      "bigquery.googleapis.com/datasets.create"
                    ],
                    "deniedPrincipals": [
                      "principal://iam.googleapis.com/projects/-/serviceAccounts/service-account-1@project-1.iam.gserviceaccount.com"
                    ]
                  }
                }
              ],
              "uid": "fab63b4d-ecfb-5f06-8a6d-602bf1be5062",
              "updateTime": "2024-05-20T23:29:38.428095Z"
            },
            "relevance": "HEURISTIC_RELEVANCE_HIGH",
            "ruleExplanations": [
              {
                "combinedDeniedPermission": {
                  "permissionMatchingState": "PERMISSION_PATTERN_NOT_MATCHED",
                  "relevance": "HEURISTIC_RELEVANCE_HIGH"
                },
                "combinedDeniedPrincipal": {
                  "membership": "MEMBERSHIP_NOT_MATCHED",
                  "relevance": "HEURISTIC_RELEVANCE_HIGH"
                },
                "combinedExceptionPermission": {
                  "permissionMatchingState": "PERMISSION_PATTERN_NOT_MATCHED",
                  "relevance": "HEURISTIC_RELEVANCE_NORMAL"
                },
                "combinedExceptionPrincipal": {
                  "membership": "MEMBERSHIP_NOT_MATCHED",
                  "relevance": "HEURISTIC_RELEVANCE_NORMAL"
                },
                "deniedPermissions": {
                  "bigquery.googleapis.com/datasets.create": {
                    "permissionMatchingState": "PERMISSION_PATTERN_NOT_MATCHED",
                    "relevance": "HEURISTIC_RELEVANCE_HIGH"
                  }
                },
                "deniedPrincipals": {
                  "principal://iam.googleapis.com/projects/-/serviceAccounts/service-account-1@project-1.iam.gserviceaccount.com": {
                    "membership": "MEMBERSHIP_NOT_MATCHED",
                    "relevance": "HEURISTIC_RELEVANCE_HIGH"
                  }
                },
                "denyAccessState": "DENY_ACCESS_STATE_NOT_DENIED",
                "relevance": "HEURISTIC_RELEVANCE_HIGH"
              }
            ]
          },
        ],
        "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/123456789012",
        "relevance": "HEURISTIC_RELEVANCE_HIGH"
      }
    ],
    "permissionDeniable": true,
    "relevance": "HEURISTIC_RELEVANCE_NORMAL"
  },
  "overallAccessState": "CANNOT_ACCESS",
  "pabPolicyExplanation": {
    "explainedBindingsAndPolicies": [
      {
        "bindingAndPolicyAccessState": "PAB_ACCESS_STATE_NOT_ENFORCED",
        "explainedPolicy": {
          "explainedRules": [
            {
              "combinedResourceInclusionState": "RESOURCE_INCLUSION_STATE_NOT_INCLUDED",
              "effect": "ALLOW",
              "explainedResources": [
                {
                  "relevance": "HEURISTIC_RELEVANCE_NORMAL",
                  "resource": "//cloudresourcemanager.googleapis.com/projects/project-2",
                  "resourceInclusionState": "RESOURCE_INCLUSION_STATE_NOT_INCLUDED"
                }
              ],
              "relevance": "HEURISTIC_RELEVANCE_NORMAL",
              "ruleAccessState": "PAB_ACCESS_STATE_NOT_ALLOWED"
            }
          ],
          "policy": {
            "createTime": "2024-04-09T17:40:51.627668Z",
            "details": {
              "enforcementVersion": "1",
              "rules": [
                {
                  "effect": "ALLOW",
                  "resources": [
                    "//cloudresourcemanager.googleapis.com/projects/project-2"
                  ]
                }
              ]
            },
            "displayName": "Troubleshooter v3 PAB Policy",
            "etag": "m64s4IgR80eDJDywuVA2DA==",
            "name": "organizations/123456789012/locations/global/principalAccessBoundaryPolicies/example-pab-policy",
            "uid": "puid_11875429267422576641",
            "updateTime": "2024-04-09T17:40:51.627668Z"
          },
          "policyAccessState": "PAB_ACCESS_STATE_NOT_ENFORCED",
          "policyVersion": {
            "enforcementState": "PAB_POLICY_ENFORCEMENT_STATE_NOT_ENFORCED",
            "version": 1
          },
          "relevance": "HEURISTIC_RELEVANCE_NORMAL"
        },
        "explainedPolicyBinding": {
          "conditionExplanation": {
            "evaluationStates": [
              {
                "end": 53,
                "value": true
              },
              {
                "end": 153,
                "start": 58,
                "value": false
              },
              {
                "end": 248,
                "start": 157,
                "value": false
              }
            ],
            "value": false
          },
          "policyBinding": {
            "condition": {
              "expression": "principal.type == 'iam.googleapis.com/ServiceAccount' && (principal.subject=='service-account-1@project-1.iam.gserviceaccount.com' || principal.subject=='service-account-2@project-1.iam.gserviceaccount.com')"
            },
            "createTime": "2024-04-09T17:51:13.504418Z",
            "displayName": "PAB Policy Binding on project-1 project",
            "etag": "W/\"hz9IKzHsIqvopqDRcVYDxQ==\"",
            "name": "projects/123456789012/locations/global/policyBindings/example-policy-binding",
            "policy": "organizations/123456789012/locations/global/principalAccessBoundaryPolicies/example-pab-policy",
            "policyKind": "PRINCIPAL_ACCESS_BOUNDARY",
            "policyUid": "puid_11875429267422576641",
            "target": {
              "principalSet": "//cloudresourcemanager.googleapis.com/projects/project-1"
            },
            "uid": "buid_1012746966204940289", 
            "updateTime": "2024-05-09T23:08:56.846355Z"
          },
          "policyBindingState": "POLICY_BINDING_STATE_NOT_ENFORCED",
          "relevance": "HEURISTIC_RELEVANCE_NORMAL"
        },
        "relevance": "HEURISTIC_RELEVANCE_NORMAL"
      }
    ],
    "principalAccessBoundaryAccessState": "PAB_ACCESS_STATE_NOT_ENFORCED",
    "relevance": "HEURISTIC_RELEVANCE_NORMAL"
  }
}

REST

To find out why a principal has, or doesn't have, an IAM permission, use the Policy Troubleshooter API's iam.troubleshoot method.

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

VERSION: The API version to use for this request. To troubleshoot access based on allow and deny policies only, use v3. To troubleshoot access based on allow, deny, and principal access boundary policies, use v3beta.
EMAIL: The email address of the principal whose permissions you want to troubleshoot.
RESOURCE: The resource on which the permission is granted.
PERMISSION: The permission that you want to troubleshoot.
PROJECT_ID: The ID of the project that you want to use to make the request. Project IDs are alphanumeric strings, like my-project.

HTTP method and URL:

POST https://policytroubleshooter.googleapis.com/VERSION/iam:troubleshoot

Request JSON body:

{
  "accessTuple": {
    "principal": "EMAIL",
    "fullResourceName": "RESOURCE",
    "permission": "PERMISSION"
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://policytroubleshooter.googleapis.com/VERSION/iam:troubleshoot"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://policytroubleshooter.googleapis.com/VERSION/iam:troubleshoot" | Select-Object -Expand Content

APIs Explorer (browser)

Copy the request body and open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and click Execute.

You should receive a JSON response similar to the following:

Response

{
  "overallAccessState": "CANNOT_ACCESS",
  "accessTuple": {
    "principal": "service-account-3@project-1.iam.gserviceaccount.com",
    "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/project-1",
    "permission": "bigtable.instances.create",
    "permissionFqdn": "bigtable.googleapis.com/instances.create",
    "conditionContext": {
      "effectiveTags": [
        {
          "tagValue": "tagValues/123456789012",
          "namespacedTagValue": "project-1/example-tag-key/example-tag-value",
          "tagKey": "tagKeys/123456789012",
          "namespacedTagKey": "project-1/example-tag-key",
          "tagKeyParentName": "projects/546942305807"
        },
      ]
    }
  },
  "allowPolicyExplanation": {
    "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
    "explainedPolicies": [
      {
        "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
        "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/project-1",
        "bindingExplanations": [
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "role": "roles/bigquery.admin",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "serviceAccount:service-account-1@project-1.iam.gserviceaccount.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL",
            "condition": {
              "expression": "resource.type == \"cloudresourcemanager.googleapis.com/Project\"",
              "title": "Resource-based condition"
            },
            "conditionExplanation": {
              "value": null
            }
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "role": "roles/bigquery.admin",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "serviceAccount:service-account-2@project-1.iam.gserviceaccount.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL",
            "condition": {
              "expression": "resource.matchTag(\"project-1/example-tag-key\", \"example-tag-value\")",
              "title": "Tag-based condition"
            },
            "conditionExplanation": {
              "value": true,
              "evaluationStates": [
                {
                  "end": 73,
                  "value": true
                }
              ]
            }
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "role": "roles/compute.admin",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "user:user-1@example.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL"
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "role": "roles/iam.serviceAccountTokenCreator",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "user:user-2@example.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              },
              "user:user-3@example.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL"
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "role": "roles/owner",
            "rolePermission": "ROLE_PERMISSION_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_HIGH",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "user:user-1@example.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              },
              "user:user-3@example.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_HIGH"
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "role": "roles/resourcemanager.projectIamAdmin",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL",
            "combinedMembership": {
              "membership": "MEMBERSHIP_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "serviceAccount:service-account-4@project-1.iam.gserviceaccount.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              },
              "serviceAccount:service-account-3@project-1.iam.gserviceaccount.com": {
                "membership": "MEMBERSHIP_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              }
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL"
          },
          {
            "allowAccessState": "ALLOW_ACCESS_STATE_NOT_GRANTED",
            "role": "roles/resourcemanager.tagViewer",
            "rolePermission": "ROLE_PERMISSION_NOT_INCLUDED",
            "rolePermissionRelevance": "HEURISTIC_RELEVANCE_NORMAL",
            "combinedMembership": {
              "membership": "MEMBERSHIP_NOT_MATCHED",
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            },
            "memberships": {
              "serviceAccount:service-account-4@project-1.iam.gserviceaccount.com": {
                "membership": "MEMBERSHIP_NOT_MATCHED",
                "relevance": "HEURISTIC_RELEVANCE_NORMAL"
              },
            },
            "relevance": "HEURISTIC_RELEVANCE_NORMAL"
          }
        ],
        "relevance": "HEURISTIC_RELEVANCE_HIGH",
        "policy": {
          "version": 3,
          "etag": "BwYY6ttEMEY=",
          "bindings": [
            {
              "role": "roles/bigquery.admin",
              "members": [
                "serviceAccount:service-account-1@project-1.iam.gserviceaccount.com"
              ],
              "condition": {
                "expression": "resource.type == \"cloudresourcemanager.googleapis.com/Project\"",
                "title": "Resource-based condition"
              }
            },
            {
              "role": "roles/bigquery.admin",
              "members": [
                "serviceAccount:service-account-2@project-1.iam.gserviceaccount.com"
              ],
              "condition": {
                "expression": "resource.matchTag(\"project-1/example-tag-key\", \"example-tag-value\")",
                "title": "Tag-based condition"
              }
            },
            {
              "role": "roles/compute.admin",
              "members": [
                "user:user-1@example.com"
              ]
            },
            {
              "role": "roles/iam.serviceAccountTokenCreator",
              "members": [
                "user:user-3@example.com",
                "user:user-2@example.com"
              ]
            },
            {
              "role": "roles/owner",
              "members": [
                "user:user-1@example.com",
                "user:user-3@example.com"
              ]
            },
            {
              "role": "roles/resourcemanager.projectIamAdmin",
              "members": [
                "serviceAccount:service-account-3@project-1.iam.gserviceaccount.com",
                "serviceAccount:service-account-4@project-1.iam.gserviceaccount.com"
              ]
            },
            {
              "role": "roles/resourcemanager.tagViewer",
              "members": [
                "serviceAccount:service-account-4@project-1.iam.gserviceaccount.com"
              ]
            }
          ]
        }
      },
    ],
    "relevance": "HEURISTIC_RELEVANCE_HIGH"
  },
  "denyPolicyExplanation": {
    "denyAccessState": "DENY_ACCESS_STATE_NOT_DENIED",
    "explainedResources": [
      {
        "denyAccessState": "DENY_ACCESS_STATE_NOT_DENIED",
        "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/546942305807",
        "explainedPolicies": [
          {
            "denyAccessState": "DENY_ACCESS_STATE_NOT_DENIED",
            "policy": {
              "name": "policies/cloudresourcemanager.googleapis.com%2Fprojects%2F546942305807/denypolicies/ts-v3-non-tag-deny-policy",
              "uid": "fab63b4d-ecfb-5f06-8a6d-602bf1be5062",
              "kind": "DenyPolicy",
              "displayName": "Troubleshooter v3 prober non-tag deny policy",
              "etag": "MTgyMzk3MDY4OTY4MDE0ODg4OTY=",
              "createTime": "2024-04-09T23:28:24.103203Z",
              "updateTime": "2024-05-20T23:29:38.428095Z",
              "rules": [
                {
                  "denyRule": {
                    "deniedPrincipals": [
                      "principal://iam.googleapis.com/projects/-/serviceAccounts/service-account-1@project-1.iam.gserviceaccount.com"
                    ],
                    "deniedPermissions": [
                      "bigquery.googleapis.com/datasets.create"
                    ]
                  }
                }
              ]
            },
            "ruleExplanations": [
              {
                "denyAccessState": "DENY_ACCESS_STATE_NOT_DENIED",
                "combinedDeniedPermission": {
                  "permissionMatchingState": "PERMISSION_PATTERN_NOT_MATCHED",
                  "relevance": "HEURISTIC_RELEVANCE_HIGH"
                },
                "deniedPermissions": {
                  "bigquery.googleapis.com/datasets.create": {
                    "permissionMatchingState": "PERMISSION_PATTERN_NOT_MATCHED",
                    "relevance": "HEURISTIC_RELEVANCE_HIGH"
                  }
                },
                "combinedExceptionPermission": {
                  "permissionMatchingState": "PERMISSION_PATTERN_NOT_MATCHED",
                  "relevance": "HEURISTIC_RELEVANCE_NORMAL"
                },
                "combinedDeniedPrincipal": {
                  "membership": "MEMBERSHIP_NOT_MATCHED",
                  "relevance": "HEURISTIC_RELEVANCE_HIGH"
                },
                "deniedPrincipals": {
                  "principal://iam.googleapis.com/projects/-/serviceAccounts/service-account-1@project-1.iam.gserviceaccount.com": {
                    "membership": "MEMBERSHIP_NOT_MATCHED",
                    "relevance": "HEURISTIC_RELEVANCE_HIGH"
                  }
                },
                "combinedExceptionPrincipal": {
                  "membership": "MEMBERSHIP_NOT_MATCHED",
                  "relevance": "HEURISTIC_RELEVANCE_NORMAL"
                },
                "relevance": "HEURISTIC_RELEVANCE_HIGH"
              }
            ],
            "relevance": "HEURISTIC_RELEVANCE_HIGH"
          },
        ],
        "relevance": "HEURISTIC_RELEVANCE_HIGH"
      }
    ],
    "relevance": "HEURISTIC_RELEVANCE_NORMAL",
    "permissionDeniable": true
  },
  "pabPolicyExplanation": {
    "principalAccessBoundaryAccessState": "PAB_ACCESS_STATE_NOT_ENFORCED",
    "explainedBindingsAndPolicies": [
      {
        "bindingAndPolicyAccessState": "PAB_ACCESS_STATE_NOT_ENFORCED",
        "explainedPolicyBinding": {
          "policyBindingState": "POLICY_BINDING_STATE_NOT_ENFORCED",
          "policyBinding": {
            "name": "projects/546942305807/locations/global/policyBindings/example-policy-binding",
            "uid": "buid_1012746966204940289", 
            "etag": "W/\"hz9IKzHsIqvopqDRcVYDxQ==\"",
            "displayName": "PAB Policy Binding on project-1 project",
            "target": {
              "principalSet": "//cloudresourcemanager.googleapis.com/projects/project-1"
            },
            "policy": "organizations/123456789012/locations/global/principalAccessBoundaryPolicies/example-pab-policy",
            "condition": {
              "expression": "principal.type == 'iam.googleapis.com/ServiceAccount' && (principal.subject=='service-account-1@project-1.iam.gserviceaccount.com' || principal.subject=='service-account-2@project-1.iam.gserviceaccount.com')"
            },
            "createTime": "2024-04-09T17:51:13.504418Z",
            "updateTime": "2024-05-09T23:08:56.846355Z",
            "policyKind": "PRINCIPAL_ACCESS_BOUNDARY",
            "policyUid": "puid_11875429267422576641"
          },
          "conditionExplanation": {
            "value": false,
            "evaluationStates": [
              {
                "end": 53,
                "value": true
              },
              {
                "start": 58,
                "end": 153,
                "value": false
              },
              {
                "start": 157,
                "end": 248,
                "value": false
              }
            ]
          },
          "relevance": "HEURISTIC_RELEVANCE_NORMAL"
        },
        "explainedPolicy": {
          "policyAccessState": "PAB_ACCESS_STATE_NOT_ENFORCED",
          "policy": {
            "name": "organizations/123456789012/locations/global/principalAccessBoundaryPolicies/example-pab-policy",
            "uid": "puid_11875429267422576641",
            "etag": "m64s4IgR80eDJDywuVA2DA==",
            "displayName": "Troubleshooter v3 PAB Policy",
            "createTime": "2024-04-09T17:40:51.627668Z",
            "updateTime": "2024-04-09T17:40:51.627668Z",
            "details": {
              "rules": [
                {
                  "resources": [
                    "//cloudresourcemanager.googleapis.com/projects/project-2"
                  ],
                  "effect": "ALLOW"
                }
              ],
              "enforcementVersion": "1"
            }
          },
          "policyVersion": {
            "version": 1,
            "enforcementState": "PAB_POLICY_ENFORCEMENT_STATE_NOT_ENFORCED"
          },
          "explainedRules": [
            {
              "ruleAccessState": "PAB_ACCESS_STATE_NOT_ALLOWED",
              "effect": "ALLOW",
              "combinedResourceInclusionState": "RESOURCE_INCLUSION_STATE_NOT_INCLUDED",
              "explainedResources": [
                {
                  "resourceInclusionState": "RESOURCE_INCLUSION_STATE_NOT_INCLUDED",
                  "resource": "//cloudresourcemanager.googleapis.com/projects/project-2",
                  "relevance": "HEURISTIC_RELEVANCE_NORMAL"
                }
              ],
              "relevance": "HEURISTIC_RELEVANCE_NORMAL"
            }
          ],
          "relevance": "HEURISTIC_RELEVANCE_NORMAL"
        },
        "relevance": "HEURISTIC_RELEVANCE_NORMAL"
      }
    ],
    "relevance": "HEURISTIC_RELEVANCE_NORMAL"
  }
}

Understand Troubleshooter results

Console

The results page contains the following information:

Evaluation details
Policy details, which contains the following:

Evaluation details

The Evaluation details section contains a summary of the access you're troubleshooting, including the specified principal, resource, and permission. If you're troubleshooting multiple resource permission pairs, you can use the Access Evaluation list to switch between them.

Policy details

The Policy details section contains details about how the relevant allow, deny, and principal access boundary policies affect the principal's access.

Relevant principal access boundary policies include all principal access boundary policies that are bound to a principal set that includes the principal.

Relevant allow and deny policies include the following:

The resource's allow policy
The resource's deny policies, if any
The allow policies of the resource's parent project, folder, and organization, if any
The deny policies of the resource's parent project, folder, and organization, if any

The allow and deny policies of parent projects, folders, and organizations are relevant because of policy inheritance. When you attach an allow or deny policy to a project, folder, or organization, that policy also applies for all resources inside that project, folder, or organization.

For example, if a deny policy for an organization says that a principal can't use a specific permission, then the principal can't use that permission for any resource within the organization. This rule applies even if the folders and projects within that organization have more permissive deny policies, or allow policies that give the principal the permission.

Similarly, if an allow policy for a project gives a principal a specific permission, then the principal has that permission for any resource within the project, provided that they aren't denied that permission.

The Policy details section contains the following sections:

Access state
Principal access boundary policy
Deny policy
Allow policy

Access state

The Access state section summarizes the results for each policy type (principal access boundary policies, deny policies, and allow policies), and states the overall outcome. The outcome indicates whether the principal is able to use the permission to access the resource, according to the relevant policies.

For a user to be able to use the permission to access the resource, all policy types must permit access. For more information, see Policy evaluation.

Principal access boundary policy

In the Principal access boundary policy section, you can view all principal access boundary policies that the principal is subject to, and the policy bindings that bind these policies to the principal.

The Policies pane lists all policies that are bound to a principal set that includes the principal. Next to each policy is an icon indicating how that policy affects the principal's access.

Principal access boundary policies can affect a principal's access in the following ways:

Principal is eligible to access the resource: The principal access boundary policy applies to the principal, and one of its rules contains the queried resource.
Principal is ineligible to access the resource: The principal access boundary policy applies to the principal, but the queried resource isn't in that policy's rules.
Not enforced: Principal access boundary policies aren't enforced in the following situations:
- IAM doesn't enforce the specified permission at the principal access boundary policy's enforcement version. As a result, the principal access boundary policy can't block access.
- Due to a condition in the policy binding, the principal access boundary policy or binding doesn't apply to the principal.
- A principal access boundary policy has no rules.
If a principal access boundary policy isn't enforced, then it can't affect whether the principal can access the resource.

To view the rules and bindings associated with a principal access boundary policy, click the policy name. The pane adjacent to the Policies pane displays the policy's details.

To view the rules in the policy, click the Boundary rules tab. This tab displays a table of the relevant principal access boundary policy rules.

A principal access boundary rule is relevant if the rule impacts the overall outcome of the Policy Troubleshooter query. As a result, the relevant rules vary depending on the Policy Troubleshooter results. For example, consider the following situations:

Policy Troubleshooter indicates that the principal can access the resource. As a result, the relevant rules are those that make the principal eligible to access the resource.
Policy Troubleshooter indicates that the principal can't access the resource. However, according to the relevant principal access boundary policies, the principal is eligible to access the resource. As a result, no rules are relevant, because the principal access boundary policies aren't the reason that the principal can't access the resource.
Policy Troubleshooter indicates that the principal can't access the resource. Additionally, according to the relevant principal access boundary policies, the principal isn't eligible to access the resource. As a result, the relevant rules are those that don't make the principal eligible to access the resource.

To view all principal access boundary rules in a policy, clear the Show only relevant rules and bindings checkbox.

The Findings column in the boundary rules table indicates whether the principal access boundary rule contains the queried resource. To see more details about the rule, click See rule details.

To view the policy bindings for the policy, click the Bindings tab. This tab displays a table of the relevant policy bindings for the selected principal access boundary policy.

A policy binding is relevant if it effectively applies the principal access boundary policy to the queried principal. For a policy binding to apply a principal access boundary policy to a principal, the following must be true:

The principal set in the policy binding must include the queried principal
Any conditions in the policy binding must evaluate to true for the queried principal.

To view all policy bindings with principal sets that include the queried principal, regardless of whether the queried principal meets the condition in the binding, clear the Show only relevant rules and bindings checkbox.

The Findings column in the bindings table indicates whether the binding is enforced for the queried principal. To see more details about the policy binding, click See binding details.

Deny policy

In the Deny policy section, you can view all relevant deny policies, identify deny rules that deny access to the principal, and understand why a deny rule denies or doesn't deny the principal the permission.

The Resources with deny policies pane lists all relevant deny policies, organized by the resources they're attached to. Next to each deny policy is an access evaluation. This evaluation only applies to that deny policy—it doesn't reflect any access from inherited policies. If you don't have permission to view a resource's deny policy, the resource list does not include that resource or its deny policies.

To view the relevant deny rules in these deny policies, click a deny policy. To view all deny rules in a resource's deny policies, click a resource. The deny rules appear in the Deny rules pane. This pane contains a table of all deny rules with the queried principal or permission for the resource or deny policy you've selected.

The Access column indicates whether the deny rule denies the principal the permission. To see more details about the deny rule, click See deny rule in that rule's row.

Allow policy

In the Allow policy section, you can navigate through all relevant allow policies, identify role bindings that grant access to the principal, and understand why a role binding gives or doesn't give the principal the permission.

The Resources pane lists the specified resource and its ancestors. Next to each resource is an access evaluation. This evaluation only applies to that resource's allow policy—it doesn't reflect any access from inherited policies. If you don't have permission to view a resource's allow policy, the resource list does not include that resource.

To view the relevant role bindings in a resource's allow policy and see how they do or don't give the principal the permission, click the resource. The allow policy's role bindings appear in the Role bindings pane.

The Role bindings pane contains a table of role bindings in the selected resource's allow policy. By default, the table only contains role bindings that include a role with the specified permission. If the principal doesn't have access, the table also shows role bindings with editable custom roles. To see all role bindings, clear the Show only relevant bindings checkbox.

The Access column indicates whether the role binding gives the principal the permission. To see more details about the role binding, click See binding details in that role binding's row.

gcloud

The response contains four main sections: a description of the access tuple in the request, the results of the allow policy evaluation, the results of the deny policy evaluation, and the overall access state.

Many objects in the response also have a relevance field. The value in this field indicates how much that object contributes to the overall access state. The relevance field can have the following values:

REST

The response contains four main sections: the overall access state, a description of the access tuple in the request, the results of the allow policy evaluation, and the results of the deny policy evaluation.

Troubleshooting conditional role bindings

Policy Troubleshooter automatically troubleshoots conditional role bindings and deny rules based on tags. It also automatically troubleshoots principal access boundary policy bindings with conditions based on principals.

To troubleshoot other kinds of conditional role bindings or conditional deny rules, Policy Troubleshooter needs additional context about the request. For example, to troubleshoot conditions based on date/time attributes, Policy Troubleshooter needs the time of the request.

In the Google Cloud console, you can provide this additional context by troubleshooting directly from any Admin Activity audit log or Data Access audit log. Each audit log entry corresponds to a request to a Google Cloud API, or an action that Google Cloud takes on your behalf. When you troubleshoot from an audit log, Policy Troubleshooter automatically gets additional information about the request, such as its date and time, which allows Policy Troubleshooter to analyze conditional role bindings and deny rules.

Console

To troubleshoot conditional role bindings and deny rules, do the following:

In the Google Cloud console, go to the Logs Explorer page.

Go to the Logs Explorer
If the page title is Legacy Logs Viewer, click the Upgrade drop-down list and select Upgrade to the new Logs Explorer.
To view only Admin Activity and Data Access audit logs, enter the following query in the query builder, then click Run query:
```
logName=("RESOURCE_TYPE/RESOURCE_ID/logs/cloudaudit.googleapis.com%2Factivity" OR "RESOURCE_TYPE/RESOURCE_ID/logs/cloudaudit.googleapis.com%2Fdata_access")
```
Replace the following values:
- RESOURCE_TYPE: The resource type that you are listing audit logs for. Use projects, folders, or organizations.
- RESOURCE_ID: The ID of your resource.
Locate the audit log entry that corresponds to the request that you want to troubleshoot. To learn how to use the Logs Explorer to find specific log entries, see Using the Logs Explorer.

Note: In some cases, a single request might produce more than one log entry. Review the entries carefully to determine which entry to troubleshoot.
In the Summary column of the log entry, click IAM, then click Troubleshoot access issue.

Policy Troubleshooter uses the information in the log entry to troubleshoot access, then shows you the results. The additional context is listed in the evaluation details under Condition context. To view the context details, click View condition context. To learn more about the Policy Troubleshooter results page, see Understand Troubleshooter results on this page.

Note: The additional context does not include group membership status. When troubleshooting group membership, Policy Troubleshooter always uses the group membership status at the time of troubleshooting.
Optional: To troubleshoot another request that involves conditional role bindings and deny rules, return to the Logs Explorer page and repeat the previous steps.

gcloud

To troubleshoot conditional role bindings and deny rules, use the gcloud policy-troubleshoot iam command.

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

EMAIL: The email address of the principal whose permissions you want to troubleshoot.
RESOURCE: The resource on which the permission is granted.
PERMISSION: The permission that you want to troubleshoot.
DESTINATION_IP: Optional. The request destination IP address to use when checking conditional role bindings. For example, 198.1.1.1.
DESTINATION_PORT: Optional. The request destination port to use when checking conditional role bindings. For example, `8080`.
REQUEST_TIME: Optional. The request timestamp to use when checking conditional role bindings. Use a timestamp in RFC 3339format—for example, 2099-02-01T00:00:00Z.
RESOURCE_NAME: Optional. The resource name value to use when checking conditional role bindings. For a list of accepted resource name formats, see Resource name format.
RESOURCE_SERVICE: Optional. The resource service value to use when checking conditional role bindings. For a list of accepted service names, see Resource service values.
RESOURCE_TYPE: Optional. For a list of accepted resource types, see Resource type values.

Execute the gcloud policy-troubleshoot iam command:

Linux, macOS, or Cloud Shell

gcloud policy-intelligence troubleshoot-policy iam RESOURCE --principal-email=EMAIL \
    --permission=PERMISSION --destination-ip=DESTINATION_IP \
    --destination-port=DESTINATION_PORT --request-time=REQUEST_TIME \
    --resource-name=RESOURCE_NAME --resource-service=RESOURCE_SERVICE \
    --resource-type=RESOURCE_TYPE

Windows (PowerShell)

gcloud policy-intelligence troubleshoot-policy iam RESOURCE --principal-email=EMAIL `
    --permission=PERMISSION --destination-ip=DESTINATION_IP `
    --destination-port=DESTINATION_PORT --request-time=REQUEST_TIME `
    --resource-name=RESOURCE_NAME --resource-service=RESOURCE_SERVICE `
    --resource-type=RESOURCE_TYPE

Windows (cmd.exe)

gcloud policy-intelligence troubleshoot-policy iam RESOURCE --principal-email=EMAIL ^
    --permission=PERMISSION --destination-ip=DESTINATION_IP ^
    --destination-port=DESTINATION_PORT --request-time=REQUEST_TIME ^
    --resource-name=RESOURCE_NAME --resource-service=RESOURCE_SERVICE ^
    --resource-type=RESOURCE_TYPE

The response contains an explanation of the principal's access. For each role binding and deny rule with a condition, the response includes a conditionExplanation field describing whether the condition evaluates to true or false based on the condition context that you provided.

For example, the following is an evaluation of a role binding with a condition specifying the resource type and resource service:

Response

...
{
  "allowAccessState": "ALLOW_ACCESS_STATE_GRANTED",
  "combinedMembership": {
    "membership": "MEMBERSHIP_MATCHED",
    "relevance": "HEURISTIC_RELEVANCE_HIGH"
  },
  "condition": {
    "expression": " resource.type \u003d\u003d \"compute.googleapis.com/Instance\" \u0026\u0026 resource.service \u003d\u003d \"compute.googleapis.com\"",
    "title": "Compute instances only",
    "description": "Condition that limits permissions to only Compute instances"
  },
  "conditionExplanation": {
    "evaluationStates": [{
      "end": 51,
      "start": 1,
      "value": true
    }, {
      "end": 99,
      "start": 55,
      "value": true
    }],
    "value": true,
  },
  "memberships": {
    "user:my-user@example.com": {
      "membership": "MEMBERSHIP_MATCHED",
      "relevance": "HEURISTIC_RELEVANCE_HIGH"
    }
  },
  "relevance": "HEURISTIC_RELEVANCE_HIGH",
  "role": "roles/compute.viewer",
  "rolePermission": "ROLE_PERMISSION_INCLUDED",
  "rolePermissionRelevance": "HEURISTIC_RELEVANCE_HIGH"
}
...

REST

To troubleshoot conditional role bindings and deny rules, use the Policy Troubleshooter API's iam.troubleshoot method.

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

EMAIL: The email address of the principal whose permissions you want to troubleshoot.
RESOURCE: The resource on which the permission is granted.
PERMISSION: The permission that you want to troubleshoot.
DESTINATION_IP: Optional. The request destination IP address to use when checking conditional role bindings. For example, 198.1.1.1.
DESTINATION_PORT: Optional. The request destination port to use when checking conditional role bindings. For example, `8080`.
REQUEST_TIME: Optional. The request timestamp to use when checking conditional role bindings. Use a timestamp in RFC 3339format—for example, 2099-02-01T00:00:00Z.
RESOURCE_NAME: Optional. The resource name value to use when checking conditional role bindings. For a list of accepted resource name formats, see Resource name format.
RESOURCE_SERVICE: Optional. The resource service value to use when checking conditional role bindings. For a list of accepted service names, see Resource service values.
RESOURCE_TYPE: Optional. For a list of accepted resource types, see Resource type values.

HTTP method and URL:

POST https://policytroubleshooter.googleapis.com/v3/iam:troubleshoot

Request JSON body:

{
  "accessTuple": {
    "principal": "EMAIL",
    "fullResourceName": "RESOURCE",
    "permission": "PERMISSION",
    "conditionContext": {
      "destination": {
        "ip": DESTINATION_IP,
        "port": DESTINATION_PORT
      },
      "request": {
        "receiveTime": REQUEST_TIME
      },
      "resource": {
        "name": RESOURCE_NAME,
        "service": RESOURCE_SERVICE,
        "type": RESOURCE_TYPE
      }
    }
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://policytroubleshooter.googleapis.com/v3/iam:troubleshoot"

PowerShell (Windows)

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://policytroubleshooter.googleapis.com/v3/iam:troubleshoot" | Select-Object -Expand Content

APIs Explorer (browser)

For example, the following is an evaluation of a role binding with a condition specifying the resource type and resource service:

...
{
  "allowAccessState": "ALLOW_ACCESS_STATE_GRANTED",
  "role": "roles/compute.viewer",
  "rolePermission": "ROLE_PERMISSION_INCLUDED",
  "rolePermissionRelevance": "HEURISTIC_RELEVANCE_HIGH",
  "combinedMembership": {
    "membership": "MEMBERSHIP_MATCHED",
    "relevance": "HEURISTIC_RELEVANCE_HIGH"
  },
  "memberships": {
    "user:my-user@example.com": {
      "membership": "MEMBERSHIP_MATCHED",
      "relevance": "HEURISTIC_RELEVANCE_HIGH"
    }
  },
  "relevance": "HEURISTIC_RELEVANCE_HIGH",
  "condition": {
    "expression": " resource.type \u003d\u003d \"compute.googleapis.com/Instance\" \u0026\u0026 resource.service \u003d\u003d \"compute.googleapis.com\"",
    "title": "Compute instances only",
    "description": "Condition that limits permissions to only Compute instances"
  },
  "conditionExplanation": {
    "value": true,
    "evaluationStates": [{
      "start": 1,
      "end": 51,
      "value": true
    }, {
      "start": 55,
      "end": 99,
      "value": true
    }]
  }
}
...

Troubleshoot IAM permissions Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required permissions

Permissions to troubleshoot access for individual principals

Permissions to troubleshoot allow and deny policies

Permissions to troubleshoot principal access boundary policies

Permissions to troubleshoot access for group members

Permissions to troubleshoot access for domain members

Troubleshoot access

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Response

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

APIs Explorer (browser)

Response

Understand Troubleshooter results

Console

gcloud

REST

Troubleshooting conditional role bindings

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Response

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

APIs Explorer (browser)

What's next