Setting up context-aware access with Cloud Identity-Aware Proxy

This guide describes how to extend Cloud Identity-Aware Proxy (Cloud IAP) access policies using access levels and the Cloud Identity and Access Management (Cloud IAM) Conditions Framework. Access levels allow access restrictions to resources based on IP address and end-user device attributes. Cloud IAM conditions allow access restrictions based on URL hosts, paths, date, and time.

If you're signed up for the Cloud IAM Conditions Framework private beta, you can also use access levels for Cloud IAP-secured projects.

For example, depending on the policy configuration, your sensitive app can:

  • Grant access to all employees if they're using a trusted corporate device from your corporate network.
  • Grant access to employees in the Remote Access group if they're using a trusted corporate device with a secure password and up-to-date patch level, from any network.
  • Only grant access to employees in the Privileged Access group if the URL path starts with /admin.

Before you begin

Before you begin, you'll need the following:

  • A Cloud IAP-secured app to which you want to add individual or group access.
  • User or group names that you want to grant access to.
  • Whitelist access to the Cloud IAM Conditions Framework private beta if you want to set project-level conditions.

Setting up an access level

To limit access based on IP address or end-user device attributes, you need to create an access level. To learn how to create an access level, see the Access Context Manager guide. Cloud IAP uses the access level name to associate it with a Cloud IAP-secured app.

Creating a service account

To use access levels and update your Cloud IAM policy using the API, you need an authenticated service account for your project.

  1. In the project where your app is deployed create a new service account.
  2. Authenticate your new service account by using gcloud auth activate-service-account.

Downloading the credentials file

You need to download your new service account's JSON credential file to update your Cloud IAM policy using the API. To download the JSON credentials file:

  1. Go to the Service accounts page.
    Go to the service accounts page

  2. Click the email address of your service account.

  3. Click Edit.

  4. Click Create key.

  5. Select JSON as your key type.

  6. Create you new key by clicking Create and closing the confirmation window that appears.

Your JSON credentials file has now been downloaded.

Editing the Cloud IAM policy

A Cloud IAP-secured app has a Cloud IAM policy that binds the Cloud IAP role to the app.

By adding a Cloud IAM conditional binding to the Cloud IAM policy, access to your resources are further restricted based on request attributes. These request attributes include:

  • Access levels
  • URL Host/Path
  • Date/Time

Note that request values being compared to request.host and request.path specified in a Cloud IAM conditional binding must be exact. For example, if you restrict access to paths starting with /internal admin, one can bypass the restriction by going to /internal%20admin. For more information about hostname and path conditions, see Using hostname and path conditions.

Add and edit conditional bindings on your Cloud IAM policy by following the process below.

Console

To add a conditional binding using the GCP Console:

  1. Go to the Cloud IAP admin page.

    Go to the Cloud IAP admin page

  2. Select the checkbox next to the resources that you want to update Cloud IAM permissions for.

  3. On the right side Info panel, click Add member.

  4. In the New member box, enter the members that you want to assign a role to.

  5. In the Select a role drop-down list, select the IAP-secured Web App User role and specify access level conditions that the members will need to meet to access the resource.

    • To specify existing access levels, select them from the Access levels drop-down list. You need to select the IAP-secured Web App User role and have organization level permissions to view existing access levels. You must be granted one of the following roles:
      • Access Context Manager Admin
      • Access Context Manager Editor
      • Access Context Manager Reader
    • To create and manage access levels, use the Access Context Manager.
  6. If you want to add more roles to the members, click Add another role.

  7. When you're finished adding roles, click Save.

    You have now added a conditional binding to your resource.

To remove a conditional binding:

  1. Go to the Cloud IAP admin page.

    Go to the Cloud IAP admin page

  2. Select the checkbox next to the resource that you want to remove a member's Cloud IAM role from.

  3. On the right side Info panel, under Role / Member, click the role that you want to remove from the member.

  4. Click Remove next to the member.

  5. On the Remove role from member dialog that appears, click Remove. To remove all non-inherited roles from the member on the selected resource, select the checkbox before clicking Remove.

gcloud

To set conditional bindings using the gcloud tool, you must sign up for the Cloud IAM Conditions Framework private beta. At this time, you can only use the gcloud tool to set project-level conditional bindings.

To set conditional bindings, edit your project's policy.yaml file by following the process below:

  1. Open the Cloud IAM policy for the app using the following gcloud command:

    gcloud projects get-iam-policy PROJECT_ID > policy.yaml

  2. Edit the policy.yaml file to specify the following:

    • The users and groups you want to apply the Cloud IAM condition to.
    • The iap.httpsResourceAccessor role to grant them access to the resources.
    • The Cloud IAM condition.

      The following snippet shows a Cloud IAM condition with only one attribute specified. This condition grants access to the user and group if the ACCESS_LEVEL_NAME access level requirements are met and the resource URL path starts with /.

      ...
      - members:
      - group:EXAMPLE_GROUP@GOOGLE.COM
      - user:EXAMPLE_USER@GOOGLE.COM
      role: roles/iap.httpsResourceAccessor
      condition:
          expression: "accessPolicies/ORGANIZATION_NUMBER/accessLevels/ACCESS_LEVEL_NAME" in
                       request.auth.access_levels && request.path.startsWith("/")
          title: CONDITION_TITLE
      ...

  3. Bind the policy to the application using the set-iam-policy command.

    gcloud projects set-iam-policy PROJECT_ID policy.yaml

Your Cloud IAM policy now includes a conditional binding.

API

To edit your app's policy.json file, follow the process below for your app type. See Managing access to Cloud IAP-secured resources for more information about using the Cloud IAM API to manage access policies.

Before doing the application-specific API steps below:

  1. Download the credentials file for your service account.
  2. Export the following variables.

    export PROJECT_NUM=PROJECT_NUMBER
    export IAP_BASE_URL=https://iap.googleapis.com/v1beta1/projects/${PROJECT_NUMBER}/iap_web
    # Replace with the path to your local service account's downloaded JSON file
    export JSON_CREDS=EXAMPLE.IAM.GSERVICEACCOUNT.COM.JSON
    # Replace POLICY_FILE.JSON with the name of JSON file to use for setIamPolicy
    export JSON_NEW_POLICY=POLICY_FILE.JSON
    

  3. Convert your service account credentials JSON file into an OAuth access token using Oauth2l by running the following command.

    oauth2l header --json ${JSON_CREDS} cloud-platform

  4. If this is your first time running the above command, when prompted:

    1. Get the verification code by clicking the displayed link and copying the code.
    2. Paste the verification code into your app prompt.
    3. Copy the returned bearer token.
    4. Export a new variable that's assigned your returned bearer token.
      export CLOUD_OAUTH_TOKEN=AUTHORIZATION_BEARER_TOKEN
  5. If you've run this command before, export the following variable.

    export CLOUD_OAUTH_TOKEN ="$(oauth2l header --json ${JSON_CREDS} cloud-platform)"

App Engine

  1. Export the following App Engine variables:

    # The APP_ID is usually the project ID
    export GAE_APP_ID=APP_ID
    export GAE_BASE_URL=${IAP_BASE_URL}/appengine-${GAE_APP_ID}

  2. Get the Cloud IAM policy for the App Engine app using the getIamPolicy method. The empty data bit at the end turns the curl request into POST instead of GET.

    curl -i -H "${CLOUD_OAUTH_TOKEN}" ${GAE_BASE_URL}/:getIamPolicy \
         -d ''
    

  3. Add your Cloud IAM conditional binding to the Cloud IAM policy JSON file. The following is an example of an edited policy.json file that binds the iap.httpsResourceAccessor role to two users, granting them access to the Cloud IAP-secured resources. A Cloud IAM condition has been added to grant them access to the resources only if the ACCESS_LEVEL_NAME access level requirement is met and the resource URL path starts with /. There can be only one condition per binding.

    Example policy.json file

    {
    "policy": {
    "bindings": [
    {
      "role": "roles/iap.httpsResourceAccessor",
      "members": [
          "group:EXAMPLE_GROUP@GOOGLE.COM",
          "user:EXAMPLE_USER@GOOGLE.COM"
      ],
      "condition": {
        "expression": ""accessPolicies/ORGANIZATION_NUMBER/accessLevels/ACCESS_LEVEL_NAME" in request.auth.access_levels && request.path.startsWith("/")",
        "title": "CONDITION_NAME"
      }
    }
    ]
    }
    }

  4. Set your new policy.json file using the setIamPolicy method.

    curl -i -H "${CLOUD_OAUTH_TOKEN}" ${GAE_BASE_URL}:setIamPolicy \
         -d @${JSON_NEW_POLICY}

App Engine services and versions

You can also update the Cloud IAM policy of a App Engine service, all versions, or a specific version of a service. To do this for specific version of a service:

  1. Export the following additional variables.
    export GAE_SERVICE=SERVICE_NAME
    export GAE_VERSION=VERSION_NAME
    
  2. Update the exported GAE_BASE_URL variable.
    export GAE_BASE_URL=${IAP_BASE_URL}/appengine-${GAE_APP_ID}/services/${GAE_SERVICE}/versions/${GAE_VERSION}
  3. Get and set the Cloud IAM policy for the version using the getIamPolicy and setIamPolicy commands shown above.

GKE and Compute Engine

  1. Export the project ID of your backend service.

    export BACKEND_SERVICE_NAME=BACKEND_SERVICE_NAME

  2. Get the Cloud IAM policy for the Compute Engine app using the getIamPolicy method. The empty data bit at the end turns the curl request into POST instead of GET.

    curl -i -H "${CLOUD_OAUTH_TOKEN}" ${IAP_BASE_URL}/compute/services/${BACKEND_SERVICE_NAME}:getIamPolicy \
         -d ''

  3. Add your Cloud IAM conditional binding to the Cloud IAM policy JSON file. The following is an example of an edited policy.json file that binds the iap.httpsResourceAccessor role to two users, granting them access to the Cloud IAP-secured resources. A Cloud IAM condition has been added to grant them access to the resources only if the ACCESS_LEVEL_NAME access level requirement is met and the resource URL path starts with /. There can be only one condition per binding.


    Example policy.json file

    {
    "policy": {
    "bindings": [
    {
    "role": "roles/iap.httpsResourceAccessor",
    "members": [
      "group":EXAMPLE_GROUP@GOOGLE.COM,
      "user:EXAMPLE_USER@GOOGLE.COM"
    ],
    "condition": {
      "expression": ""accessPolicies/ORGANIZATION_NUMBER/accessLevels/ACCESS_LEVEL_NAME" in request.auth.access_levels && request.path.startsWith("/")",
      "title": "CONDITION_NAME"
    }
    }
    ]
    }
    }

  4. Set your new policy.json file using the setIamPolicy method.

    curl -i -H "Content-Type:application/json" \
         -H "$(oauth2l header --json ${JSON_CREDS} cloud-platform)" \
         ${IAP_BASE_URL}/compute/services/${BACKEND_SERVICE_NAME}:setIamPolicy \
         -d @${JSON_NEW_POLICY}

Using hostname and path conditions

Access to your app can be secured using the hostname and path of a request URL. For example, the request.path.startsWith Cloud IAM condition can be used to only grant access to employees in the Privileged Access group if the URL path starts with /admin.

For more information about using hostname and path conditions, see request attributes.

String normalization

A URL has a hostname and path. For example, the URL https://sheets.google.com/create?query=param has a hostname of sheets.google.com and a path of /create.

Backends can interpret hostnames and paths in different ways. To remove ambiguity, Cloud IAP normalizes hostname and path strings when checking policies.

Cloud IAP performs two policy checks when a request has a non-normalized path. If the non-normalized path passes the policy check, Cloud IAP normalizes the path and a second policy check is performed. Access is granted if both the non-normalized and normalized paths pass the policy check.

For example, if a request has the path /internal;some_param/admin, Cloud IAP first performs a policy check on the non-normalized path (/internal). If that passes, Cloud IAP performs a second policy check on the normalized path (/internal/admin).

Hostnames

Hostnames are normalized by:

  • Removing trailing dots
  • Lowercasing characters
  • Converting to ASCII

Hostnames that include non-ASCII characters are further normalized with punycoding. You need to punycode your hostname string for a match to be made.

To punycode your hostname string, use a converter like Punycoder.

The following are examples of normalized hostnames:

  • FOO.com is normalized to foo.com
  • café.fr is normalized to xn--caf-dma.fr

Paths

Paths are normalized by:

  • Removing path params
  • Resolving relative paths to their absolute equivalent

A path param includes all characters from a ; to either the next / or the end of the path.

Requests that contain ..; at the beginning of a path section are considered invalid. For example, /..;bar/ and /bar/..;/ return the HTTP 400: Bad Request error.

The following are examples of normalized paths:

  • /internal;some_param/admin is normalized to /internal/admin
  • /a/../b is normalized to /b
  • /bar;param1/baz;baz;param2 is normalized to /bar/baz

Subdomain endings

A policy set with request.host.endsWith("google.com") will match to both sub_domain.google.com and testgoogle.com. If your goal is to limit your policy to all subdomains the end with google.com, set your policy to request.host.endsWith(".google.com").

Note that setting your policy to request.host.endsWith(".google.com") will match with sub_domain.google.com but won't match with google.com due to the additional ..

Cloud Audit Logs and access levels

Enabling Cloud Audit Logs for your Cloud IAP-secured project allows you to see authorized and unauthorized access requests. View requests and all the access levels a requestor has met by following the process below:

  1. Go to the GCP Console Logs page for your project.
    Go to the logs page
  2. On the resource selector drop-down list, select a resource. Cloud IAP-secured HTTPS resources are under GAE Application and GCE Backend Service. Cloud IAP-secured SSH and TCP resources are under GCE VM instance.
  3. On the logs type drop-down list, select data_access.
    • The data_access log type only appears if there was traffic to your resource after you enabled Cloud Audit Logs for Cloud IAP.
  4. Click to expand the date and time of the access you want to review.
    • Authorized access has a blue i icon.
    • Unauthorized access has an orange !! icon.
  5. View the access levels the requester has met by clicking to expand sections until you reach protoPayload > requestMetadata > requestAttributes > auth > accessLevels.

Note that all access levels that a user has met are visible when viewing a request, including access levels that weren't required to access it. Viewing an unauthorized request doesn't indicate what access levels weren't met. This is determined by comparing the conditions on the resource to the access levels visible on the request.

See the Cloud Audit Logs guide for more information about logs.

Var denne side nyttig? Giv os en anmeldelse af den:

Send feedback om...

Identity-Aware Proxy Documentation