Resolve permission errors

This document describes the different methods administrators can use to identify and resolve permission errors for users in their organization.

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 Google Cloud console. These requests are typically sent to the following people:

  • Your organization's technical Essential Contact. If your organization has enabled Essential Contacts and allows auto-generated access request emails, then users who encounter permission errors in the Google Cloud console have the option to send an auto-generated access request to their organization's technical Essential Contact.

  • Contacts configured through your preferred request management system. Users who encounter permission errors in the Google 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 Google Cloud console. If the permission error is caused by 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 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.

  • Remediate access issues with Policy Troubleshooter (Preview): Access requests also contain a link to a policy remediation summary, which describes the request details, including the requesting principal, resource, and permission. From the policy remediation summary, you can directly resolve access requests involving allow policies, and get more information about the policies that are blocking user access.

    For more information about resolving access requests using the policy remediation summary, see Remediate access issues.

Manually resolve permission errors

If you're 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, deny, or principal access boundary) 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 Google Cloud console contain a link to a Policy Troubleshooter remediation page (Preview) for the principal, permissions, and resource involved in the request. To view this link, click View troubleshooting details, and then click Policy Troubleshooter. For more information, see Remediate access requests.

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, deny, or principal access boundary 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 caused by each of the different policy types, see the following:

Resolve allow policy permission errors

To resolve permission errors caused by 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.

Approve a grant against a Privileged Access Manager entitlement

Privileged Access Manager entitlements let users request to be granted specific IAM roles. If you approve a user's request for a grant, then they're granted the requested roles temporarily.

If the user already has a Privileged Access Manager entitlement with a role that contains the required permissions, then they can request a grant against that entitlement. After they request the grant, you can approve the grant to resolve their permission error.

If a user doesn't have an entitlement, then you can create a new entitlement for them to request grants against.

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.

Resolve principal access boundary policy permission errors

By default, principals are eligible to access any Google Cloud resource. However, if they're subject to any principal access boundary policy, then they're only eligible to access the resources listed in the principal access boundary policies that they're subject to. In these cases, a principal access boundary policy might prevent a principal from accessing a resource.

To resolve errors related to principal access boundary policies, do one of the following.

Add the resource to a principal access boundary policy

If a resource is included in a principal access boundary policy that a user is subject to, then they're eligible to access that resource.

To add a resource to a principal access boundary policy, do one of the following:

Add a condition to exempt specific principals

You can use conditions in principal access boundary policy bindings to refine which principals the principal access boundary policy is enforced for.

If you don't want a user to be subject to principal access boundary policies, then use conditions in principal access boundary policy bindings to exempt the user from principal access boundary policies.

For this approach to resolve errors, you must exempt the user from every principal access boundary policy that they're subject to. Doing so will make the user eligible to access any Google Cloud resource.

We don't recommend this approach. Instead, consider adding the resource to a principal access boundary policy.

To view the principal access boundary policies that a user is subject to, list the policy bindings for the principal sets that they're included in. Each binding represents a principal access boundary policy that's bound to the principal set.

To learn how to add conditions to principal access boundary policy bindings, see Edit existing policy bindings for principal access boundary policies.

What's next