IAP reauthentication

IAP reauthentication allows services and applications owners or Google Cloud administrators to require authenticated end users to reauthenticate after a specified amount of time when accessing a service or application protected by IAP. It limits the time span for which a user can access the IAP-protected service or application before they are asked to authenticate again.

IAP reauthentication is designed to enforce reauthentication policies for IAP-protected services and applications. You might do this for critical services and applications that handle confidential information. For example, you can specify that users accessing a critical HR application reauthenticate hourly using a second factor.

Supported reauthentication methods

You can use the following methods to manage the reauthentication settings:

  • Login: IAP forces reauthentication of the protected application and users must log in again.
  • Secure key: End users must reauthenticate using their configured security-key-based, two-factor authentication.
  • Enrolled second factors: End users must reauthenticate using one of the enrolled second factor authentication methods.

For more information, see IapSettings.

Set up a reauthentication policy

reauthSettings are a part of IapSettings, and as such can be set on any resource type in the resource hierarchy. You can set reauthSettings on a service or application at the organization, folder, project, or service level to apply restrictions. For example, you can limit the session length to a maximum of one hour for all applications in an organization, or to a specific application.

There are two policy types that you can use to set reauthentication:

  • Minimum: If the policy type is set to MINIMUM on a resource, such as an organization, then when evaluating the reauth settings on the lower level resource, such as a folder, the two settings are merged. If the lower level resource has no reauth settings, the merge result is the non-empty settings of the higher-level resource. Otherwise, the merge takes the shorter session duration and the higher precedence reauth method between the two resources. The policy type will always be MINIMUM. The merged reauth settings will be used to merge with the reauth settings of the next lower-level resource, such as a project.

    The order of precedence of the three supported methods from highest to lowest is Secure key, Enrolled second factors, and Login.

  • Default: If the policy type is set as DEFAULT on a resource, such as organization, then when evaluating the reauth setting on the lower-level resource, such as a folder, the lower-level resource setting is used if configured; otherwise, the higher level resource reauth setting is applied.

For both policy types, the evaluation process is repeated to determine the reauthSettings for the target service or application. The following examples show the settings before and after evaluation. During evaluation, the folder and organization reauthSettings are merged, resulting in changing the policy type of the folder to MINIMUM. The merged settings are then used to merge with the service or application reauthSettings.

Organization IapSettings:

accessSettings:
  reauthSettings:
    method: "ENROLLED_SECOND_FACTORS"
    maxAge: "3600s"
    policyType: "MINIMUM"

Folder IapSettings:

accessSettings:
  reauthSettings:
    method: "LOGIN"
    maxAge: "1200s"
    policyType: "DEFAULT"

Service or Application IapSettings:

accessSettings:
  reauthSettings:
    method: "SECURE_KEY"
    maxAge: "7200s"
    policyType: "DEFAULT"

Settings after merge:

Organization IapSettings:

accessSettings:
  reauthSettings:
    method: "ENROLLED_SECOND_FACTORS"
    maxAge: "3600s"
    policyType: "MINIMUM"

Folder IapSettings:

accessSettings:
  reauthSettings:
    method: "ENROLLED_SECOND_FACTORS"
    maxAge: "1200s"
    policyType: "MINIMUM"

Service or Application IapSettings:

accessSettings:
  reauthSettings:
    method: "SECURE_KEY"
    maxAge: "1200s"
    policyType: "MINIMUM"

In the example, if the policy type of every resource is set to DEFAULT, the reauthSettings of the service or application is used.

MaxAge

Use the MaxAge parameter to specify how often an end user must reauthenticate, denoted in seconds. For example, to set a one hour reauthentication policy, set seconds to 3600, as shown in the following example:

accessSettings:
  reauthSettings:
    method: "LOGIN"
    maxAge: "3600s"
    policyType: "MINIMUM"

The minimum value for maxAge is five minutes.

To set a reauthentication policy, complete the following steps.

Console

  1. Go to the Identity-Aware Proxy page.
    Go to the Identity-Aware Proxy page

  2. Select a project, and then select the resource on which you want to set a reauthentication policy.

  3. Open the Settings for the resource and under Reauthentication policy, select Configure reauthentication.

  4. Specify the reauthentication settings, and then click Save.

gcloud

You can set a reauthentication policy on resources and services at the organization, project, and folder level. Following are some example commands for setting a reauthentication policy.

For more information, see gcloud iap settings set.

Run the following command:

gcloud iap settings set SETTING_FILE [--organization=ORGANIZATION --folder=FOLDER --project=/PROJECT --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION

To set a reauthentication policy on the resources within an organization, run the following command: 

gcloud iap settings set SETTING_FILE --organization=ORGANIZATION

To set a reauthentication policy on the resources within a folder, run the following command: 

gcloud iap settings set SETTING_FILE --folder=FOLDER

To set a reauthentication policy on all web type resources within a project, run the following command: 

gcloud iap settings set SETTING_FILE --project=PROJECT --resource-type=iap_web

To set a reauthentication policy on an App Engine service within a project, run the following command:

gcloud iap settings set SETTING_FILE --project=PROJECT --resource-type=app-engine --service=SERVICE

Where SETTING_FILE is:

accessSettings:
  reauthSettings:
    method: "LOGIN"
    maxAge: "3600s"
    policyType: "MINIMUM"

Replace the following:

  • FOLDER: The folder ID.
  • ORGANIZATION: The organization ID.
  • PROJECT: The project ID.
  • RESOURCE_TYPE: The IAP resource type. Must be app-engine, iap_web, compute, organization, or folder.
  • SERVICE: The service name. This is optional when resource-type is compute or app-engine.
  • VERSION: The version name. This is not applicable for compute, and is optional when resource-type is app-engine.

API

Run the following command to prepare an iap_settings.json file. Update the values as needed.

cat << EOF > iap_settings.json
{
  "access_settings": {
      "reauth_settings": {
            "method": "LOGIN",
            "maxAge": "300s",
            "policy_type": "DEFAULT"
        }
    }
}
EOF

Get the resource name by running the gcloud iap settings get command. Copy the name field from the output. You will need the name in the following step.

gcloud iap settings get [--organization=ORGANIZATION --folder=FOLDER --project=/PROJECT --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION]

Replace RESOURCE_NAME in the following command with the name from the previous step. The IapSettings will be updated.

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d @iap_settings.json \
"https://iap.googleapis.com/v1/RESOURCE_NAME:iapSettings?updateMask=iapSettings.accessSettings.reauthSettings"

Understanding reauthentication credentials

After a successful reauthentication, IAP creates a cookie on the end user`s browser. To prevent users from having to reauthenticate too often when using similar apps, the cookie is set on the top level private domain and is valid for that entire private level domain.

For example, foo.example.com is an IAP protected resource and has an IAP reauthentication policy. After a successful reauthentication, IAP sets a cookie on example.com as that is the top level private domain. Apps from the same top level private domain, such as bar.example.com use the same reauthentication credentials and do not prompt the user to reauthenticate, as long as the credentials are valid.

Note that for URLs such as myapp.appspot.com, appspot.com is a public domain, therefore the top level private domain is myapp.appspot.com.

Known limitations

  • Reauthentication is only supported for browser flows. Programmatic user account access is not supported. For example, mobile and desktop apps have no way of reauthenticating users, because resources that require reauthentication are inaccessible.
  • Service accounts and IAP-TCP are exempt from reauthentication requirements.
  • Reauthentication does not work with the IAM member type allUsers.
  • External identities via Identity Platform are not supported with reauthentication, because resources that require reauthentication are not accessible.