Customizing IAP

This article describes the customization options available to Identity-Aware Proxy (IAP). Using various settings, you can control:

  • Compatibility with Anthos and Istio on Google Kubernetes Engine.
  • The handling of CORS preflight requests.
  • How users are authenticated.
  • The error page shown to users when access is denied.

Understanding settings

IAP provides the following customization settings:

Field Description
access_settings.cors_settings.allow_http_options Control HTTP OPTIONS (CORS preflight)
access_settings.oauth_settings.login_hint Simplify login for users of a G Suite domain
application_settings.access_denied_page_settings.access_denied_page_uri Show a custom error page when access is denied
application_settings.csm_settings.rctoken_aud Issue Anthos and Istio RCTokens
access_settings.gcip_settings Authenticate with Identity Platform

You can apply settings at the project level, or at any lower IAP resource level.

Settings are only available for web-based IAP resources, not IAP for TCP forwarding.

The sections below provide more information on each setting.

Allowing HTTP OPTIONS (CORS preflight)

Field Default value
access_settings.cors_settings.allow_http_options false

The web's same-origin policy blocks browsers from sending AJAX requests between websites. By default, JavaScript on a page served from one origin can't use AJAX to send a request to an app secured with IAP hosted on a different origin.

In some cases, browsers will automatically try a request, but discard the content of the response if it doesn't include an Access-Control-Allow-Origin header. To allow these types of requests, include this header in your app's responses.

In other cases, the browser will send a CORS preflight request, a type of HTTP OPTIONS request, before sending the cross-origin request. If your app doesn't response with an appropriate preflight response (containing the required Access-Control-* response headers), the browser will block the request with an error. Additionally, since preflight requests aren't sent with any authentication credentials (such as a IAP session cookie), IAP will also respond with an error.

To allow these requests:

  1. Add code to your app that responds to the OPTIONS requests.

  2. Change the setting access_settings.cors_settings.allow_http_options to true so that IAP passes OPTIONS requests through to your application.

Authenticating using a G Suite domain

Field Default value
access_settings.oauth_settings.login_hint ""

If only members of a specific G Suite domain will use your app, you can configure IAP to optimize the authentication flow. This has several benefits:

  • If a user is signed in with multiple accounts (such as work account and a personal account), the system will automatically select their work account instead of displaying the account selection UI.

  • If a user isn't signed into their Google account, the sign-in UI will automatically fill the domain portion of their email address (meaning the user only needs to type alice instead of alice@example.com, for example).

  • If your G Suite domain is configured to use a third-party single sign-on provider, the system will show that custom sign-in page instead of Google's.

To enable this behavior, set the value of access_settings.oauth_settings.login_hint to your G Suite domain name (such as example.com).

In general, enabling this setting will prevent users who aren't in the specified G Suite domain from connecting to your application. You can use programmatic authentication if you need to authenticate users outside the domain.

For more information, see the OpenID Connect documentation.

Redirecting to a custom "access denied" error page

Field Default value
application_settings.access_denied_page_settings.access_denied_page_uri ""

You can set a URL in this field that redirects users to a custom page instead of the default IAP error page whenever access is denied by a policy.

Issuing Anthos and Istio RCToken mesh IDs

Field Default value
application_settings.csm_settings.rctoken_aud ""

If you're using Istio on GKE, you can configure IAP to produce an Istio-compatible RCToken. If this field is set to a non-empty string, IAP will add an Ingress-Authorization HTTP header containing an RCToken. The aud claim will be set to the value of the field.

Authenticating with Identity Platform

Field Default value
access_settings.gcip_settings null

By default, IAP uses Google's native identity system. If this field is set, IAP will use Identity Platform instead to authenticate users.

Settings inheritance in the resource hierarchy

IAP always evaluates requests for a specific web service version. This type of resource is at the lowest level of the resource hierarchy, which looks like this:

- Organization
  - Folder
    - Project
      - All web services
        - Web service type
          - Web service
            - Web service version

To determine the settings to apply for a web service version, IAP starts with a default set of values, and then walks the hierarchy from top to bottom. Settings are applied as they are found, so values set at a lower level overrides values set at a higher level. For example, if access_settings.cors_settings.allow_http_options is set to true at the project level, but false at the service level, then effective value will be false.

See Resources and permissions to learn more about the IAP resource hierarchy.

Access control for settings

Specific permissions are required to view and modify IAP settings. The table below lists the permissions required to read and modify settings for each resource type. See Resources and permissions for a description of the different resource types.

Resource Permission for viewing settings Permission for modifying settings
Organization iap.organizations.getSettings iap.organizations.updateSettings
Folder iap.folders.getSettings iap.folders.updateSettings
Project iap.projects.getSettings iap.projects.updateSettings
All web services iap.web.getSettings iap.web.updateSettings
Web service type iap.webTypes.getSettings iap.webTypes.updateSettings
Web service iap.webServices.getSettings iap.webServices.updateSettings
Web Service version iap.webServiceVersions.getSettings iap.webServiceVersions.updateSettings

The IAP Settings Admin (roles/iap.settingsAdmin) role grants all of these permissions, as does Project Editor (roles/editor). Project Viewer (roles/viewer) grants all getSettings permissions.

To learn more about granting Cloud IAM roles, see Granting, changing, and revoking access.

Managing settings

You can view and update settings using the Cloud Console, the IAP API, or the gcloud command-line tool.

To manage settings in IAP:

Console

To view and modify settings using the Cloud Console:

  1. Go to the Identity-Aware Proxy page.
    Go to the Identity-Aware Proxy page
  2. Find your resource on the HTTPS Resources tab.
  3. Open the more actions menu and click Settings.
  4. Once you've made your changes, click Save.

gcloud

To get and modify settings using the gcloud command-line tool, use the gcloud iap settings get and gcloud iap settings set commands as shown below:

  • To get settings for a project, folder, or organization, use the following commands. See the gcloud iap settings get topic for more information::
gcloud iap settings get --project=PROJECT-ID
gcloud iap settings get --folder=FOLDER-ID
gcloud iap settings get --organization=ORGANIZATION-ID
  • To get settings for a specific IAP resource type under a project:
gcloud iap settings get --project=PROJECT-ID \
  --resource-type=RESOURCE-TYPE-NAME
  • To set settings for a project, folder, or organization, or an IAP resource type under a project, create a JSON or YAML file that contains the desired new settings and specify the path to the file. See the gcloud iap settings set topic for more information:
gcloud iap settings set SETTING_FILE --project=PROJECT-ID \
  --resource-type=RESOURCE-TYPE-NAME

API

To get and modify settings using the IAP API, make requests using either the GET or PATCH HTTP verbs to the desired resource endpoint in Google Cloud. Combine the :iapSettings path suffix, a resource path (as detailed in Resources and permissions), and an appropriate HTTP method to get or modify a setting. See getIapSettings() and updateIapSettings() for more information:

  • To get or set settings for a specific IAP resource type under a project:
https://iap.googleapis.com/v1/projects/PROJECT-ID/iap_web/appengine-APP-ID/services/SERVICE-ID/versions/VERSION-ID:iapSettings
  • To get or set settings for a project:
https://iap.googleapis.com/v1/projects/PROJECT-ID:iapSettings
  • To get or set settings for a folder:
https://iap.googleapis.com/v1/folders/FOLDER-ID:iapSettings
  • To get or set settings for an organization:
https://iap.googleapis.com/v1/organizations/ORGANIZATION-ID:iapSettings