Troubleshooting access

Beta

This product is in a pre-release state and might change or have limited support. For more information, see the product launch stages.

Policy Troubleshooter makes it easier to understand why a user has access to a resource or doesn't have permission to call an API. Given an email, resource, and permission, Policy Troubleshooter will examine all Cloud IAM policies that apply to the resource. It then reveals whether the member's roles include the permission on that resource and, if so, which policies bind the member to those roles.

You can access Policy Troubleshooter using the Cloud Console, the gcloud command-line tool, or the REST API. For simple queries, using the Cloud Console is easy and includes a visual aide. For more complex scenarios, consider the gcloud tool or the REST API.

Troubleshooting access

To troubleshoot access, you'll need the following information:

• Principal: The email address to check. The email address can refer to a user, a service account, or another type of member.
• Resource: The full name of the resource. For example, to check the project my-project, enter //cloudresourcemanager.googleapis.com/projects/my-project. For other types of resources, see the examples of full resource names.

• Permission: The permission to check. If you use the Cloud Console, it presents a list of suggestions as you type. For a complete list of permissions, see the permissions reference.

Console

First, open the Policy Troubleshooter page in the Cloud Console.

Open the Policy Troubleshooter page

Next, enter an email, resource name, and permission to check.

You can check multiple resources and permissions by selecting Add Another Pair and repeating the previous step.

Finally, select Check API Call.

At the top-center of the results page, you can quickly see whether the user is granted the permission on the resource.

By default, the results are displayed in Compact View, which only contains information directly relevant to troubleshooting the given user's access. Specifically, if access is granted, only the bindings that grant access are shown. If access is denied, only roles which contain the desired permission (or custom roles which could be changed to include it) are shown.

You can disable Compact View using the toggle switch. This will display all bindings and members.

The left pane contains a list of policies that apply to the given resource and an icon indicating whether each policy contains a binding granting the permission to the member. In the example below, the Owner binding allows access.

The right pane displays the raw text of each binding, highlighting any lines that do not grant the permission in red. Notice lines 39-46, where the user is granted access, are not highlighted.

You can drill down to a specific binding by selecting it in the left pane. If you entered multiple resource and permission pairs, use the View by dropdown to switch between them.

gcloud

First, ensure your environment is set up to use Policy Troubleshooter.

Enable the API using the Cloud Console, or run the following command:

gcloud services enable policytroubleshooter.googleapis.com --project=[PROJECT-ID]

And set your project:

gcloud config set project [PROJECT-ID]

Once you've completed set up, you can troubleshoot if a user is granted a permission on a resource with the following command:

gcloud beta policy-troubleshoot iam [RESOURCE] --principal-email [EMAIL] \
    --permission [PERMISSION]

The following example checks if [e-mail] is granted the resourcemanager.projects.getIamPolicy permission on the project my-project.

gcloud beta policy-troubleshoot iam //cloudresourcemanager.googleapis.com/projects/my-project \
    --permission resourcemanager.projects.getIamPolicy --principal-email [e-mail]

The output is YAML indicating whether the user is granted the permission, and an explanation of why. It should look something like this:

access: GRANTED
explainedPolicies:
- access: GRANTED
  bindingExplanations:
  - access: NOT_GRANTED
    memberships:
      serviceAccount:[e-mail]: MEMBERSHIP_NOT_INCLUDED
    role: roles/compute.serviceAgent
    rolePermission: ROLE_PERMISSION_NOT_INCLUDED
  - access: GRANTED
    memberships:
      serviceAccount:[e-mail]: MEMBERSHIP_NOT_INCLUDED
      user:[e-mail]: MEMBERSHIP_INCLUDED
    role: roles/owner
    rolePermission: ROLE_PERMISSION_INCLUDED
  fullResourceName: //cloudresourcemanager.googleapis.com/projects/my-project
  policy:
    bindings:
    - members:
      - serviceAccount:[e-mail]
      role: roles/compute.serviceAgent
    - members:
      - serviceAccount:[e-mail]
      - user:[e-mail]
      role: roles/owner
    etag: BwWAOWEaIEg=
    version: 1
- access: UNKNOWN_INFO_DENIED
policy: {}

REST API

You can try the REST API using the API Explorer.

Request:

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

Body:

{
  "principal": "[EMAIL]",
  "fullResourceName": "[RESOURCE]",
  "permission": "[PERMISSION]"
}

All parameters are required.

The following example body checks if [e-mail] is granted the resourcemanager.projects.getIamPolicy permission on the project my-project.

{
  "principal": "[e-mail]",
  "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/my-project",
  "permission": "resourcemanager.projects.getIamPolicy"
}

The output is JSON indicating whether the user is granted the permission, and an explanation of why. It should look something like this:

{
  "access": "GRANTED",
  "explained_policies": [
      {
          "access": "GRANTED",
          "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/my-project",
          "policy": {
              "version": 1,
              "etag": "BwWBUZjK9YQ=",
              "bindings": [
                  {
                      "role": "roles/owner",
                      "members": [
                          "user:[e-mail]"
                      ]
                  }
              ]
          },
          "binding_explanations": [
              {
                  "access": "GRANTED",
                  "relevance: HIGH",
                  "role": "roles/owner",
                  "role_permission": "ROLE_PERMISSION_INCLUDED",
                  "role_permission_relevance": "HIGH",
                  "memberships": {
                      "key":  "user:[e-mail]",
                      "value": {
                          "membership": "MEMBERSHIP_INCLUDED",
                          "relevance":  "HIGH",
                      }
                  }
              }
          ]
      },
      {
          "access": "UNKNOWN_INFO_DENIED",
          "policy": {}
      }
  ]
}

Troubleshooting group membership

You can only troubleshoot access to a resource granted by a Google group if you have permission to view its members.

If you don't have permission, the group will be highlighted in orange in Cloud Console, and you'll see a warning that you don't know if the principal is granted access. If you're using gcloud or the REST API, the response will contain UNKNOWN_INFO_DENIED or ACCESS_TO_INFO_DENIED.

G Suite Super Admins and Group Admins typically have access to view group membership. To allow a user who is not a Super or Group admin to troubleshoot access, create a custom G Suite administrator role that contains the groups.read privilege (located under Admin API Privileges) and grant it to the user. This allows them to view the membership of all groups within your domain, and more effectively troubleshoot access.

Limitations

Policy Troubleshooter can't always fully explain access to a resource. If you don't have access to a policy that applies to a resource, Policy Troubleshooter won't analyze it. For example, if you are a project owner but lack organization-level privileges, Policy Troubleshooter won't reveal organization-level policies that could be granting access to your project.

To maximize the effectiveness of Policy Troubleshooter, ensure you are granted the Security Reviewer (roles/iam.securityReviewer) role. This ensures you can read all applicable Cloud IAM policies.