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 will examine all Cloud IAM policies that apply to the resource. It then reveals whether the member is granted the permission on that resource and, if so, by what policies.

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

Troubleshoot access

CONSOLE

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

Open the Policy Troubleshooter page

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

  • Principal is the member email to check. This could be a user or service account.
  • Resource is the full name of the resource. For example, to check the project my-project, enter //cloudresourcemanager.googleapis.com/projects/my-project. As you type, the GCP Console should present a list of suggestions.
  • Permission is the permission to check. As you type, the GCP Console should present a list of suggestions. See the Permissions Reference for a full list of permissions.

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.

Troubleshooter results

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.

Troubleshooter binding list

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.

Troubleshooter binding list

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 COMMAND

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

Enable the API using the GCP 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]

Resource is the full name of the resource. For example, to check the project my-project, enter //cloudresourcemanager.googleapis.com/projects/my-project. Email is the member email to check. This could be a user or service account. Permission is the permission to check. See the Permissions Reference for a full list of permissions. All parameters are required.

The following example checks if foo@example.com 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 foo@example.com

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: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

Request:

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

Body:

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

Where:

  • Resource is the full name of the resource. For example, to check the project my-project, enter //cloudresourcemanager.googleapis.com/projects/my-project.
  • Email is the member email to check. This could be a user or service account.
  • Permission is the permission to check. See the Permissions Reference for a full list of permissions.

All parameters are required.

The following example body checks if foo@example.com is granted the resourcemanager.projects.getIamPolicy permission on the project my-project.

{
  "principal": "foo@example.com",
  "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:foo@example.com"
                      ]
                  }
              ]
          },
          "binding_explanations": [
              {
                  "access": "GRANTED",
                  "relevance: HIGH",
                  "role": "roles/owner",
                  "role_permission": "ROLE_PERMISSION_INCLUDED",
                  "role_permission_relevance": "HIGH",
                  "memberships": {
                      "key":  "user:foo@example.com",
                      "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 GCP 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.

Troubleshooting group membership

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.

هل كانت هذه الصفحة مفيدة؟ يرجى تقييم أدائنا:

إرسال تعليقات حول...

Cloud IAM Documentation