Troubleshooting using the Policy Troubleshooter for BeyondCorp Enterprise

BeyondCorp Enterprise provides a troubleshooting tool that administrators can use to triage and analyze an end user's failed access.

BeyondCorp Enterprise enables enterprises to create advanced rules that provide context based application access. However, when you apply multiple access rules to resources, from location restrictions to device rules, it can make it difficult to understand why an end user cannot access a resource.

The Policy Troubleshooter enables an administrator to identify why access fails, and if required, change the policy and instruct the end user to modify their context to allow access.

The Policy Troubleshooter is a valuable tool for organizations that need to apply multiple rules to multiple resources for different groups of users.

Before you begin

The Policy Troubleshooter is a premium feature and requires a BeyondCorp Enterprise license.

To use the Policy Troubleshooter, turn on the feature for an IAP resource in the IAP settings, by clicking the three dots to the right of the IAP protected application, Settings, and then selecting Generate a troubleshooting URL. To maximize the effectiveness of the Policy Troubleshooter, ensure that you have the IAP Settings Admin role (roles/iap.settingsAdmin). This ensures that you can retrieve and update the IAP settings of all the IAP resources.

Troubleshooting URLs are only presented on the default 403 pages, when enabled.

Troubleshooter workflow overview

The Policy Troubleshooter provides a user interface where you can view the detailed evaluation results of all effective policies for the target IAP resource. When a user's access fails, the Policy Troubleshooter shows the details of the failing bindings and the analysis of the failing access levels, if they exist in the bindings.

User access denied

When a user doesn't have the permission or doesn't satisfy the condition required to access an IAP resource, the user is directed to a 403 access denied error page. The 403 page includes a troubleshooting URL that can either be copied and sent manually to the application owner or security administrator, or the user can click Send Email in the user interface.

When a user clicks Send Email, an email is sent to the support email address (supportEmail) that is configured on the OAuth consent screen. For more information about configuring the OAuth consent screen, see Programmatically creating OAuth clients for IAP.

Troubleshooting failed access

When you receive the link for a failed access request, you can click the URL, which will open in the default browser. If you are not signed in to the Google Cloud console in your default browser, you might be redirected to another sign-in page in order to access the Policy Troubleshooter analysis page.

On the Policy Troubleshooter analysis page, you will see more information about the restricted access, including the target principal email address, target IAP resource URL, and required permissions. You will also see a list view of effective evaluation results for the Identity and Access Management (IAM) bindings, granted or not, together with a high level view on where the failures occurred, such as Principal not a member and does not meet conditions.

To further analyze the failed access, you can view Binding details. Within the Binding Details, you can see the binding components, Role, Principal, and Condition. The component that has sufficient permissions will note No action required. Components where access has failed, the gaps in permissions are explicitly explained, such as Principal Category: Please add Principal to the below groups.

Note that in the user interface, the Relevant bindings section is turned on by default. The bindings listed in the Relevant bindings section are not a comprehensive list, but instead are the most relevant bindings that might be of interest to you when troubleshooting a specific access issue. The effective policies associated with a specific resource might contain a lot of bindings not relevant to your resource, such as a Cloud Storage permission granted at the project level. Irrelevant details are filtered out.

You can further investigate a failed Condition by looking into the Access Level Explanations. The Access Level details point out where the failure occurred and suggest fixes to resolve the failure. You can propagate the necessary actions back to the user or fix the policies, if necessary. For example, you can send the following action back to the user: Request failed because the device is not corp owned.

Common troubleshooting scenarios

Following are some common scenarios that you might encounter when working with the Policy Troubleshooter:

  • You provide an actionable item to the end user after troubleshooting, such as instructing the end user to switch to a corporate-owned device or update the operating system.
  • You discover that you didn't assign the right permission to the end user, so you create a new binding for the target principal in the IAP interface (roles/iap.httpsResourceAccessor).
  • You discover that you created an access level incorrectly for the following example reasons:
    • You created complicated nested attribute restrictions, such as corporate subnetworks, that no longer apply because employees are now working from home.
    • You applied incorrect access level parameters. For example, you specified that users can create a custom level with vendor restrictions but compared attributes with different types. For example, device.vendors["vendorX"].data.["should_contain_boolean_value"] == "true". Note that the left side returns a boolean value while the right side returns a string true. Because of the inequivalent attributes, it is difficult to detect the error in the policy construct. The Policy Troubleshooter helps by explaining that this is evaluated to be an error with detailed partial evaluation results on both sides.

Troubleshooting restricted access

To maximize the effectiveness of the Policy Troubleshooter, ensure that you have the Security Reviewer role (roles/iam.securityReviewer). This ensures that you can read all applicable Cloud IAM policies.

Device privilege is optional. If policies associated with the target resource contain device policies, such as an access level that requires the device to be encrypted, you might not get accurate results unless the permission to retrieve the device details of the target principal is verified. Google Workspace Super Admin, Services Admin, and Mobile Admin typically have access to view device details. To allow a user who is not a Super, Service, or Mobile Admin to troubleshoot access, complete the following steps:

  1. Create a custom Google Workspace administrator role with the MDM administrator privilege.
  2. Assign the role to users by using the Admin console.

The privilege to view group membership is optional. If the policies contain a group, you should have the permission to view the details of the group before opening it. 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, complete the following steps:

  1. Create a custom Google Workspace administrator role that contains the groups.read privilege (located under Admin API Privileges).
  2. Assign the role to the user. This lets the user view the membership of all groups within your domain, and more effectively troubleshoot access.

Custom Role permission is optional. 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 it from bindings with custom roles.

Troubleshooter intended behavior

Troubleshooting is done on the restricted accesses using the current policies and device information with the current timestamp. Therefore, if you synced your device or changed the policies after the restricted access denial, you are not troubleshooting using the old contexts and data. You are troubleshooting using the current contexts and data.

Tips for troubleshooting bindings

For any components (Role, Principal, Condition) of any bindings with authorization errors, grant the necessary permissions if you want to check the troubleshooting results of such bindings.

If role check fails in a binding, complete the following actions:

  • Check other bindings or create a new binding by using the IAP interface to grant the roles/iap.httpsResourceAccessor role to the principal with applied access levels, if necessary.
  • If it is a custom role, you can add the target permission to the custom role to grant the permission (after you fix any principal failures and any condition failures, when applicable). Note that adding permissions to an existing custom role might grant other bindings with this custom role with more permissions than needed. Don't do this unless you are aware of the scope of the custom role and the risk of your operation.
  • If it is not a custom role, check other bindings or create a new binding by using the IAP interface to grant the roles/iap.httpsResourceAccessor role to the principal with applied access levels, if necessary.

If role check succeeds but principal check fails, complete the following actions:

  • If the members contain a group, you can add the principal to the group to grant the permissions (after you fix any condition failures, when applicable). Note that adding principal to an existing group might grant the group more permission than needed. Don't do this unless you are aware of the scope of the group and the risk of your operation.
  • If the members don't contain a group, check other bindings or create a new binding by using the IAP interface to grant the roles/iap.httpsResourceAccessor to the principal with applied access levels, if necessary.

If the role and principal check succeed but the condition fails, check the troubleshooting details of each individual access level listed under the condition, if the condition only consists of access levels connected with the OR logical operator.