Troubleshoot IAM permissions

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 examines all Identity and Access Management (IAM) policies that apply to the resource. It then reveals whether the principal's roles include the permission on that resource and, if so, which policies bind the principal to those roles.

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

The Google Cloud console also alerts you if there are any deny policies that could impact the principal's access. The gcloud CLI and the REST API don't provide information about deny policies.

Before you begin

Enable the Policy Troubleshooter API.
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 IAM 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.

To get the permissions that you need to troubleshoot a principal's access, ask your administrator to grant you the Security Reviewer (roles/iam.securityReviewer) IAM role on the organization. For more information about granting roles, see Manage access.

This predefined role contains the permissions required to troubleshoot a principal's access. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to troubleshoot a principal's access:

iam.roles.get
iam.roles.list
resourcemanager.folders.getIamPolicy
resourcemanager.organizations.getIamPolicy
resourcemanager.projects.getIamPolicy

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

Permissions to troubleshoot access for group members

If your IAM policy contains 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 that contain groups or domains have an access result of Unknown, unless the role binding also explicitly contains the principal.

Permissions to troubleshoot access for domain members

If your IAM policy contains domains, you must be a domain administrator to troubleshoot access for individual domain members.

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

Troubleshooting access

To troubleshoot access, you need the following information:

Principal: The email address to check. The email address must refer to a user or service account. Other types of principals are not supported.
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 Google Cloud console, it presents a list of suggestions as you type. For a complete list of permissions, see the permissions reference.

Console

Troubleshooting access

To troubleshoot access, do the following:

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

Go to Policy Troubleshooter
Enter the email of the principal whose access you want to check.
Enter the resource name and permission to check. If you don't know the full resource name or permission name, start typing to see autocomplete options.
Optional: To check multiple resources and permissions, select Add Another Pair and repeat the previous step.
Click Check access.

Understanding Policy Troubleshooter results

For each resource and permission pair, Policy Troubleshooter provides a results page that explains the principal's access.

The results page contains the following information:

Evaluation details: 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 switch between them using the Access Evaluation list.
Deny policy notice: If a deny policy could impact the access that you're troubleshooting, Policy Troubleshooter displays a notice.

This notice appears in the following cases:
- You're troubleshooting a permission that is supported in deny policies, and there is a deny policy that applies to the resource you're troubleshooting.
- You're troubleshooting a permission that is supported in deny policies, and you don't have permission to view deny policies.
If you don't see this notice, then there are no deny policies affecting the principal's access.
IAM allow policy details: A brief summary of the principal's access based on the relevant IAM allow policies. These policies policies include the allow policy of the specified resource and the allow policies of all of the resource's ancestors. Because of policy inheritance, if the principal has the permission on any of these resources, they have the permission on the resource that you specified in the troubleshooting query.

This information lets you see whether the principal has the permission on the resource.
Resources: A list of the specified resource and its ancestors. Next to each resource is an evaluation of whether that resource's allow policy gives the principal the specified permission. This evaluation pertains to that resource's allow policy only—it doesn't reflect any access from inherited policies.

If you don't have permission to view an ancestor's allow policy, the resource list does not include that ancestor.

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 bindings appear in the Role bindings pane.
Role bindings: A list of role bindings in the selected resource's allow policy. By default, the list only shows role bindings that include a role with the specified permission. If the principal doesn't have access, the list 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. This column can have any of the following values:
- Granted: The role binding includes both the principal and a role with the permission.
- Not granted: The role binding doesn't include the principal, or the role in the binding does not include the permission.
- Conditional: The role binding includes both the principal and a role with the permission. However, it also contains a condition, and the principal will only have access if the condition is met.
- Unknown: The role binding contains either a role that you don't have permission to view or a group that you don't have permission to check the members of.
To see more details about the role binding, click See binding details. This action opens the Binding details pane. The Details tab of this pane displays information about the role, principals, and conditions in the role binding. If the role binding doesn't give the principal access, this pane also describes what you can do to give the principal access.

The JSON tab displays the raw text of the role binding. To learn more about the structure of role bindings, see Understanding policies.

gcloud

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

Enable the Policy Troubleshooter API:

gcloud services enable policytroubleshooter.googleapis.com --project=project-id

Then, set your project:

gcloud config set project project-id

After you complete the setup, you can use Policy Troubleshooter to check whether a user has a permission on a resource. Run the following command:

gcloud policy-troubleshoot iam resource --principal-email=email \
    --permission=permission

For example, the following command checks if foo@example.com has the resourcemanager.projects.getIamPolicy permission on the project my- project.

gcloud policy-troubleshoot iam //cloudresourcemanager.googleapis.com/projects/my-project \
    --permission=resourcemanager.projects.getIamPolicy --principal-email=foo@example.com

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

access: GRANTED
explainedPolicies:
- access: GRANTED
  bindingExplanations:
  - access: NOT_GRANTED
    memberships:
      serviceAccount:service-123@compute-system.iam.gserviceaccount.com: MEMBERSHIP_NOT_INCLUDED
    role: roles/compute.serviceAgent
    rolePermission: ROLE_PERMISSION_NOT_INCLUDED
  - access: GRANTED
    memberships:
      serviceAccount:service@my-project.iam.gserviceaccount.com: MEMBERSHIP_NOT_INCLUDED
      user:foo@example.com: MEMBERSHIP_INCLUDED
    role: roles/owner
    rolePermission: ROLE_PERMISSION_INCLUDED
  fullResourceName: //cloudresourcemanager.googleapis.com/projects/my-project
  policy:
    bindings:
    - members:
      - serviceAccount:service-123@compute-system.iam.gserviceaccount.com
      role: roles/compute.serviceAgent
    - members:
      - serviceAccount:foo@my-project.iam.gserviceaccount.com
      - user:foo@example.com
      role: roles/owner
    etag: BwWAOWEaIEg=
    version: 1
- access: UNKNOWN_INFO_DENIED
policy: {}

REST API

To find out why a principal has, or does not have, an IAM permission, 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.
PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.

HTTP method and URL:

POST https://policytroubleshooter.googleapis.com/v1/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/v1/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/v1/iam:troubleshoot" | Select-Object -Expand Content

API Explorer (browser)

Copy the request body and open the method reference page. The API 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:

{
  "access": "GRANTED",
  "explainedPolicies": [
    {
      "access": "GRANTED",
      "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/my-project",
      "policy": {
        "version": 1,
        "etag": "BwWBUZjK9YQ=",
        "bindings": [
          {
            "role": "roles/owner",
            "members": [
              "user:foo@example.com"
            ]
          }
        ]
      },
      "bindingExplanations": [
        {
          "access": "GRANTED",
          "role": "roles/owner",
          "rolePermission": "ROLE_PERMISSION_INCLUDED",
          "rolePermissionRelevance": "HIGH",
          "memberships": {
            "key": "user:foo@example.com",
            "value": {
              "membership": "MEMBERSHIP_INCLUDED",
              "relevance": "HIGH",
            }
          },
        "relevance: HIGH",
        }
      ]
    },
    {
      "access": "UNKNOWN_INFO_DENIED",
      "policy": {}
    }
  ]
}

Troubleshooting conditional role bindings

To troubleshoot conditional role bindings, 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.

To provide this additional context, you can troubleshoot 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.

This feature is only available in the Google Cloud console.

To troubleshoot conditional role bindings, 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 Troubleshooting access 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, return to the Logs Explorer page and repeat the previous steps.

What's next

Use the permissions reference or the predefined roles reference to determine which role to grant to a user who is missing permissions.
Read about the other Policy Intelligence tools, which help you understand and manage your policies to proactively improve your security configuration.