Troubleshoot permission error messages

This document covers the error messages that you might encounter if you don't have the required access permissions for a resource and describes how you can resolve these errors.

Permission error messages

The Trusted Cloud console, Google Cloud CLI, and REST API all display error messages when you try to access a resource that you don't have permission to access.

These error messages can be caused by any of the following:

  • You don't have the required permissions. You must have an allow policy role binding with the required permissions. If you don't have the required permissions, then Trusted Cloud displays an error message.
  • There's a deny policy blocking access. If a deny policy prevents you from using any of the required permissions, then Trusted Cloud displays an error message.
  • The resource doesn't exist. If the resource doesn't exist, then Trusted Cloud displays an error message.

The following sections show what these error messages look like for the Trusted Cloud console, gcloud CLI, and REST API.

Trusted Cloud console error messages

In the Trusted Cloud console, error messages look similar to the following:

These error messages contain the following information:

  • The resource that you tried to access: The resource name appears in the title of the error page and indicates the resource that you were trying to access when you encountered the permission error.
  • The missing required permissions: A list of the permissions that you need to have to access the resource.

  • A list of IAM roles that contain the required permissions: This list is non-exhaustive—it contains a curated list of roles that Trusted Cloud suggests to resolve the access issue. Ordering is based on the type of actions permitted by the role, service relevance, and the number of permissions.

    If you have the permissions required to grant roles, then this section is titled Select a role to grant. If you don't have the required permissions, then this section is titled Request a specific role.

    This list is only available for permission errors that can be resolved by granting additional IAM roles.

    You can click a role to learn more about the role and request that the role be granted to you. If you have the permissions required to grant roles, then you can grant yourself the role instead of requesting it.

Google Cloud CLI and REST API error messages

The exact wording of the error message depends on the command that you run. However, it typically contains the following information:

  • The required permission
  • The resource you tried to perform an action on
  • The authenticating account

For example, if you don't have permission to list buckets in a project, you see an error message like the following:

gcloud

ERROR: (gcloud.storage.buckets.list) HTTPError 403:
EMAIL_ADDRESS does not have
storage.buckets.list access to the Google Cloud project. Permission
'storage.buckets.list' denied on resource (or it may not exist). This command
is authenticated as EMAIL ADDRESS which
is the active account specified by the [core/account] property.

REST

{
  "error": {
    "code": 403,
    "message": "EMAIL ADDRESS does not have storage.buckets.list access to the Google Cloud project. Permission 'storage.buckets.list' denied on resource (or it may not exist).",
    "errors": [
      {
        "message": "EMAIL ADDRESS does not have storage.buckets.list access to the Google Cloud project. Permission 'storage.buckets.list' denied on resource (or it may not exist).",
        "domain": "global",
        "reason": "forbidden"
      }
    ]
  }
}

Request missing permissions

If you don't have permission to modify access-related policies in your organization, then you can't resolve the permission errors on your own. However, you can send an administrator an access request using the context from the error message.

You can request access in the following ways:

If you're using the Trusted Cloud console and you have permissions required to grant roles, then you can grant yourself the role directly from the error message instead of requesting it. For more information, see Self-grant a role in the Trusted Cloud console.

Request the required permissions

To request the required permissions, do the following:

Console

  1. In the list of missing permissions, click Request permissions.

  2. In the Request Access panel, choose how you want to notify your administrator:

    • If your organization supports Essential Contacts, then you can send an auto-generated email to your organization's technical Essential Contact. To send this email, do the following:

      1. Select Send auto-generated email.
      2. Add any context about the request that you want to include.
      3. Click Send request.

    • To copy the access request and paste it into your preferred request management system, do the following:

      1. If your organization supports Essential Contacts but you want to send the notification manually, select Notify manually.
      2. Add any context about the request that you want to include.
      3. Click Copy message.
      4. Paste the request into your preferred request management system.

      Your administrator receives your access request, along with any additional context that you provided.

gcloud

Copy the list of missing permissions from the error message, then use your preferred request management system to ask an administrator to give you these permissions.

REST

Copy the list of missing permissions from the error message, then use your preferred request management system to ask an administrator to give you these permissions.

Request a role

If the permission error is due to an allow policy, then you can request that an administrator grant you a role with the required permissions to resolve the error.

If the error is due to a different policy type or if you aren't sure which policy type is causing the error, then request the required permissions instead.

Console

  1. In the Request a specific role section, review the list of recommended roles and choose the one that you want to request. You can click the roles to view more details about them. This section is only visible if the permission error is due to an allow policy.

  2. Click the role that you've chosen, then click Request role.

  3. In the Request Access panel, choose one of the options for notifying your administrator:

    • If your organization supports Essential contacts, then you can send an auto-generated email to your organization's technical Essential Contact. To send this email, do the following:

      1. Select Send auto-generated email.
      2. Add any context about the request that you want to include.
      3. Click Send request.

    • To copy the access request and paste it into your preferred request management system, do the following:

      1. If your organization supports Essential Contacts but you want to send the notification manually, select Notify manually.
      2. Add any context about the request that you want to include.
      3. Click Copy message.
      4. Paste the request into your preferred request management system.

    Your administrator receives your access request, along with any additional context that you provided.

gcloud

  1. Identify an IAM role that contains the missing permissions.

    To see all of the roles that a given permission is included in, search for the permission in the IAM roles and permissions index, then click the permission name.

    If no predefined roles match your use case, then you can create a custom role instead.

  2. Use your preferred request management system to request that an administrator grant you the role.

REST

  1. Identify an IAM role that contains the missing permissions.

    To see all of the roles that a given permission is included in, search for the permission in the IAM roles and permissions index, then click the permission name.

    If no predefined roles match your use case, then you can create a custom role instead.

  2. Use your preferred request management system to request that an administrator grant you the role.

Self-grant a role in the Trusted Cloud console

If you encounter a permission error in the Trusted Cloud console and you have the permissions required to grant roles, then you can grant yourself a role directly from the permission error message:

  1. In the Select a role to grant section, review the list of recommended roles and choose the one that you want to request. You can click the roles to view more details about them.

  2. To grant the role that you've chosen, click the role, then click Grant access.

Resolve permission errors from access requests

If you're an administrator, then you might receive access requests from users who have encountered permission errors in the Trusted Cloud console. These requests are typically sent to the following people:

  • Your organization's technical Essential Contact. If your organization has enabled essential contacts, then users who encounter permission errors in the Trusted Cloud console have the option to send an access request to their organization's technical Essential Contact.

  • Contacts configured through your preferred request management system. Users who encounter permission errors in the Trusted Cloud console have the option to copy an access request message and then send it using their preferred request management system.

These messages typically have the following format:

user@example.com is requesting a role on the resource example.com:example-project.

Requestor's message:

"I need access to example-project to complete my work."

You may be able to resolve this request by granting access directly at:

ACCESS_REQUEST_PANEL_URL

Or use the Policy Troubleshooter to determine what's preventing access for user@example.com:

POLICY_TROUBLESHOOTER_URL

You can address these requests in the following ways:

  • Resolve access directly: Access requests contain a link to an access request panel in the Trusted Cloud console. If the permission error is due to an allow policy, then you can resolve access directly from that panel.

    In the access request panel, you can review the request details and choose how you want to respond to the request. You can respond in the following ways:

    • Grant the requested role
    • Add the user to an existing group that already has the required access
    • Deny the request

  • View additional details in Policy Troubleshooter: Access requests also contain a link to Policy Troubleshooter, which lets you see which policies are blocking the user's access. You can use this information to decide how to resolve the user's access issue. For more information, see Identify policies causing permission errors on this page.

Manually resolve permission errors

If you are an administrator with permission to modify the access-related policies in your organization, then you can use these strategies to resolve permission errors, regardless of the policy type causing the error.

To resolve permission errors, you first need to determine which policies (allow or deny) are causing the error. Then, you can resolve the error.

Identify policies causing permission errors

To determine which policies are causing a permission error, use Policy Troubleshooter.

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.

To learn how to troubleshoot access and interpret Policy Troubleshooter results, see Troubleshoot IAM permissions.

Error messages in the Trusted Cloud console contain a link to a Policy Troubleshooter results page for the principal, permissions, and resource involved in the request. To view this link, click View troubleshooting details, then find the value in the Troubleshooting URL field.

Update access to resolve permission errors

After you know which policies are causing a permission error, you can take steps to resolve the error.

Often, resolving an error involves creating or updating allow or deny policies.

However, there are other options for resolving errors that don't involve updating policies. For example, you can add the user to a group that has the required permissions or add tags to exempt a resource from a policy.

To learn the different ways that you can resolve permission errors due to each of the different policy types, see the following:

Resolve allow policy permission errors

To resolve permission errors due to allow policies, do one of the following.

Grant a role with the required permissions

To find and grant a role with the required permissions, do the following:

  1. Identify an IAM role that contains the missing permissions.

    To see all of the roles that a given permission is included in, search for the permission in the IAM roles and permissions index, then click the permission name.

    If no predefined roles match your use case, then you can create a custom role instead.

  2. Identify a principal to grant the role to:

    • If the user is the only individual who needs the permission, then grant the role directly to the user.
    • If the user is part of a Google group containing users that all need similar permissions, then consider granting the role to the group instead. If you grant the role to the group, then all members of that group can use that permission, unless they have been explicitly denied from using it.

  3. Grant the role to the principal.

Add the user to a Google group

If a Google group is granted a role on a resource, then all members of that group can use the permissions in that role to access the resource.

If an existing group has already been granted a role with the required permissions, then you can give a user the required permissions by adding them to that group:

  1. Identify a group that has a role with the required permissions. If you already used Policy Troubleshooter to troubleshoot the request, then you can review the Policy Troubleshooter results to identify a group with the required permissions.

    Alternatively, you can use Policy Analyzer to identify a group with the required permissions.

  2. Add the user to the group.

Resolve deny policy permission errors

To resolve permission errors related to deny policies, do one of the following.

Exempt yourself from a deny policy

If a deny rule is blocking a user's access to a resource, you can do one of the following to exempt the user from the rule:

  • Add the user as an exception principal in the deny rule. Exception principals are principals who are not affected by the deny rule, even if they're part of a group that's included in the deny rule.

    To add an exception principal to a deny rule, follow the steps to update the deny policy. When updating the deny policy, find the deny rule that blocks access, then add the user's principal identifier as an exception principal.

  • Add the user to a group that's exempt from the rule. If a group is listed as an exception principal, then all members of that group are exempt from the deny rule.

    To add the user to an exempt group, do the following:

    1. Use Policy Troubleshooter to identify the deny policies that are blocking access to the resource.
    2. View the deny policy.
    3. Check the list of exception principals for groups.
    4. If you identify an exempt group, add the user to the group.

Remove the permission from the deny policy

Deny rules prevent the listed principals from using specific permissions. If a deny rule is blocking a user's access to a resource, then you can remove the permissions that they need from the deny rule.

To remove permissions from a deny rule, follow the steps to update the deny policy. When updating the deny policy, find the deny rule that blocks access, then do one of the following:

  • If the deny policy lists the required permissions individually, then find the required permissions and remove them from the deny rule.
  • If the deny rule uses permission groups, then add the required permissions as exception permissions. Exception permissions are permissions that aren't blocked by the deny rule, even if they're part of a permission group that's included in the rule.

Exclude the resource from the deny policy

You can use conditions in deny policies to apply a deny rule based on a resource's tags. If the resource's tags don't meet the condition in the deny rule, then the deny rule doesn't apply.

If a deny rule is blocking access to a resource, then you can edit the conditions in the deny rule or the tags on the resource to ensure that the deny rule doesn't apply to the resource.

What's next