Troubleshooting access

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 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 typically fastest. For more complex scenarios, consider the gcloud tool or the REST API.

Note: Policy Troubleshooter does not diagnose access issues related to VPC Service Controls.

Required permissions

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 fully troubleshoot a principal's access, you need a role that includes the following permissions:

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

To gain these permissions while following the principle of least privilege, ask your administrator to grant you the Security Reviewer role (roles/iam.securityReviewer) at the organization level.

Alternatively, your administrator can grant you a different role with the required permissions, such as a custom role or a more permissive predefined role.

Troubleshooting access

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

• Principal: The email address to check. The email address must refer to a user or service account. Other types of members 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 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:

1. In the Cloud Console, go to the Policy Troubleshooter page.

   Go to Policy Troubleshooter

2. Enter an email, resource name, and permission to check.

3. Optional: To check multiple resources and permissions, select Add Another Pair and repeat the previous step.

4. Click Check API Call.

Understanding Policy Troubleshooter results

Policy Troubleshooter results tell you if the principal has the specified permission on the given resource. They also list the IAM policies that apply to the resource, and the role bindings in those policies.

By default, the results are displayed in Compact view, which only shows role bindings for roles that contain the specified permission. If you are troubleshooting multiple permissions, use the View by drop-down list to switch between them.

You can disable Compact view by clicking the Compact view toggle. Disabling Compact view displays all role bindings in policies that apply to the resource.

The results page contains the following information:

• Summary of access: A brief summary of the principal's access. This information allows you to see whether the principal has the permission on the resource. In the following example, [e-mail] has the logging.logs.view permission on my-project:

  

  

• Relevant policies and role bindings: A list of the IAM policies that apply to the given resource, and the role bindings in each policy. Next to each role binding is an icon indicating whether that role binding grants the specified permission to the principal. Click the role binding to see its raw text.

  In the following example, the Logs Viewer role binding grants the permission:

  

  

• Raw text of relevant role bindings: The raw text of each role binding in the list of relevant role bindings. To learn more about the structure of role bindings, see Understanding policies.

  In each role binding, lines are highlighted as follows:

  • Green: Lines are highlighted in green if they contain a role that includes the specified permission, if they refer to the specified principal, or if they refer to a group that contains the specified principal.
  • Red: Lines are highlighted in red if they contain another role, refer to another principal, or refer to a group that does not contain the specified principal.
  • Yellow: Lines are highlighted yellow if they contain a role whose details you don't have permission to view, or a group whose membership you don't have permission to view.

  

  

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 [e-mail] 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=[e-mail]

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:[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: {}

Note: The Policy Troubleshooter API calls the private method GetEffectivePolicy internally. If Data Access logs are enabled for IAM, you will see this call in your audit logs. For more information, see IAM audit logging.

REST API

The iam.troubleshoot method tells you why a member has, or does not have, an IAM permission.

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

• email: The email address of the member whose permissions you want to troubleshoot.
• resource: The resource on which the permission is granted.
• permission: The permission that you want to troubleshoot.

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: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

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

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

PowerShell (Windows)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

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

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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:[e-mail]"
            ]
          }
        ]
      },
      "bindingExplanations": [
        {
          "access": "GRANTED",
          "role": "roles/owner",
          "rolePermission": "ROLE_PERMISSION_INCLUDED",
          "rolePermissionRelevance": "HIGH",
          "memberships": {
            "key": "user:[e-mail]",
            "value": {
              "membership": "MEMBERSHIP_INCLUDED",
              "relevance": "HIGH",
            }
          },
        "relevance: HIGH",
        }
      ]
    },
    {
      "access": "UNKNOWN_INFO_DENIED",
      "policy": {}
    }
  ]
}

Note: The Policy Troubleshooter API calls the private method GetEffectivePolicy internally. If Data Access logs are enabled for IAM, you will see this call in your audit logs. For more information, see IAM audit logging.

Troubleshooting group membership

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

If you don't have permission, the group is highlighted yellow in the Cloud Console, and a warning indicates that you don't know whether the group includes the principal. If you're using the gcloud tool or the REST API, the response contains UNKNOWN_INFO_DENIED or ACCESS_TO_INFO_DENIED.

Google Workspace 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 Google Workspace 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.

Troubleshooting conditional role bindings

Preview — troubleshooting conditional role bindings

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Platform Terms of Service. Pre-GA features may have limited support, and changes to pre-GA features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

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.

Note: Data Access audit logs are disabled by default. To learn how to enable them, see Configuring data access audit logs.

This feature is only available in the Cloud Console.

To troubleshoot conditional role bindings, do the following:

1. In the Cloud Console, go to the Logs Explorer page.

   Go to the Logs Explorer

2. If the page title is Legacy Logs Viewer, click the Upgrade drop-down list and select Upgrade to the new Logs Explorer.

3. 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.

4. 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.

5. 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 directly below the summary of access. 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.

6. 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.