Configure Extended Session Length for Workforce Identity Federation

By default, Workforce Identity Federation sessions have a maximum duration of 12 hours. Extended session length lets organizations configure long-lasting sessions of up to 90 days for Looker (Google Cloud core) customers.

With extended session length, your workforce users maintain an uninterrupted connection to Looker (Google Cloud core) without requiring daily reauthentication against your external identity provider (IdP). User interaction within Looker (Google Cloud core) remains governed by your Looker (Google Cloud core) session length configuration. To maintain security throughout extended sessions, Google Cloud periodically synchronizes user attributes and group memberships directly from your external identity provider (IdP) in the background.

This document describes how to define extended session policies using the Access Context Manager API with project-scoped controls, configure your workforce pool provider, and manage active bindings.

Overview

Workforce Identity Federation uses Access Context Manager Google Cloud access bindings to configure extended session length:

Google Cloud access binding: Administrators define a session length policy using Access Context Manager that applies organization-wide across all workforce pools in your organization. Using the restricted_project scope, the policy grants extended sessions of up to 90 days, only affecting Looker (Google Cloud core) instances owned by that project.
Background attribute synchronization:
- OIDC: Supported using either an OIDC Authorization Code flow with the offline_access scope (using refresh tokens to periodically refresh user attributes and group memberships from your external IdP in the background) or through SCIM provisioning.
- SAML: For SAML providers, user attributes and group memberships are kept up-to-date using SCIM provisioning.
Staleness protection: If user attributes cannot be refreshed from the external IdP within 24 hours (for example, if the user is deprovisioned or credentials are revoked at the IdP), Google Cloud terminates the session.

Before you begin

Before configuring extended session length, ensure you have the required Identity and Access Management permissions and APIs enabled:

Required roles and permissions

To get the permissions that you need to configure extended session length, ask your administrator to grant you the following IAM roles:

Configure workforce identity pool providers: Workforce Pool Admin (roles/iam.workforcePoolAdmin) on the workforce pool or organization.
Manage Access Context Manager cloud access bindings: Cloud Access Binding Admin (roles/accesscontextmanager.gcpAccessAdmin) at the organization level. This role provides the permissions required to create, view, update, and delete Access Context Manager access bindings.

Enable APIs

Enable the Access Context Manager and IAM APIs in your project:

gcloud services enable \
    accesscontextmanager.googleapis.com \
    iam.googleapis.com

Limitations and Requirements

Before configuring extended session length, review the following requirements and limitations:

Supported application: Extended session length applies exclusively to Looker (Google Cloud core).
Mandatory project scope (restricted_project): Session settings must be configured within scopedAccessSettings using the restricted_project client scope specifying the Google Cloud project that owns the Looker (Google Cloud core) instance (projects/{PROJECT_NUMBER}).
- Only Looker (Google Cloud core) applications owned by the designated project are affected by the ESL policy.
- All other applications (and Looker (Google Cloud core) applications owned by other projects) experience no effect from the policy.
Session duration range: Session duration must be between a minimum of 1 hour (3600s) and a maximum of 90 days (7776000s).
Session settings parameter requirements:
- session_length_enabled: Must be set to true.
- session_length: Required duration between 1 hour (3600s) and 90 days (7776000s).
- session_reauth_method: Must be unset or set to LOGIN.
- use_oidc_max_age: Must be unset or set to false.
- max_inactivity: Must be unset (or default 0s). Idle session timeouts are not supported for restricted_project bindings.
Supported identity providers:
- OIDC: Requires an OIDC provider configured with Authorization Code Flow and the offline_access scope to issue refresh tokens, or configured with SCIM provisioning.
- SAML 2.0: Requires SCIM provisioning enabled on the workforce pool provider.
Attribute staleness threshold: A fixed 24-hour staleness threshold is enforced. If Google Cloud cannot refresh user attributes from your IdP within 24 hours, the session is invalidated and the user must reauthenticate.
Access Context Manager constraints:
- Single organizational binding: Extended session length bindings for workforce pools must target the organization's "all workforce pools" principal (principalSet://cloudresourcemanager.googleapis.com/organizations/{ORG_ID}/type/WorkforcePool). Because this federated principal identifier applies organization-wide across all workforce pools in your organization, only one such binding can exist per organization. To configure extended sessions for multiple Looker (Google Cloud core) projects across workforce pools, include multiple restricted_project scope blocks within the single binding's scopedAccessSettings list.
- Access levels (access_levels, dry_run_access_levels) are not supported on workforce pool bindings.
- Top-level sessionSettings directly on the GcpUserAccessBinding are not supported for workforce pool bindings; settings must be defined within scopedAccessSettings.activeSettings.sessionSettings.

Configure the workforce pool provider

To allow extended session length, your workforce pool provider must be configured to support background attribute refresh. You can configure the provider to use either the OIDC or SAML protocol.

Configure an OIDC provider

Background attribute refresh for OIDC providers can be handled using either refresh tokens (offline_access scope) or SCIM provisioning. If using token-based attribute refresh:

In your external IdP, configure an OIDC application with Authorization Code Flow and enable Offline Access so that a refresh token is returned.
In Google Cloud, add offline_access to the additional scopes on your OIDC workforce pool provider.

Offline access must be configured on all workforce identity pools in your Google Cloud organization for the extended session length policy to have the intended effect.

gcloud

If your provider already has existing additional scopes, include them alongside offline_access so they are not overwritten:

gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_NAME \
    --location=global \
    --web-sso-additional-scopes="offline_access[,EXISTING_ADDITIONAL_SCOPES]"

Replace the following:

PROVIDER_ID: The name of your workforce identity pool provider.
WORKFORCE_POOL_NAME: The name of your workforce identity pool.
EXISTING_ADDITIONAL_SCOPES: Any comma-separated additional scopes previously configured on the provider. If you have no existing additional scopes, omit this parameter.

REST API

Send a PATCH request to update the provider. Include any existing additional scopes alongside offline_access:

PATCH https://iam.googleapis.com/v1/locations/global/workforcePools/WORKFORCE_POOL_NAME/providers/PROVIDER_ID?updateMask=oidc.webSsoConfig.additionalScopes

Request body:

{
  "oidc": {
    "webSsoConfig": {
      "additionalScopes": [
        "offline_access"
      ]
    }
  }
}

Replace the following:

WORKFORCE_POOL_NAME: The name of your workforce identity pool.
PROVIDER_ID: The ID of your workforce identity pool provider.

Configure a SAML provider

For SAML providers, background attribute refresh requires SCIM provisioning:

Set up a SCIM tenant for your workforce pool provider.
Configure user and group provisioning from your SAML identity provider to the SCIM endpoint.

For step-by-step instructions, see SCIM provisioning for Workforce Identity Federation.

Example policy configuration for Looker (Google Cloud core)

Create a GcpUserAccessBinding resource that assigns the extended session length policy to your organization's workforce pool, scoping the policy to the project hosting your Looker (Google Cloud core) instance.

gcloud

Define the policy in a YAML file named esl-binding.yaml:

scopedAccessSettings:
- scope:
    clientScope:
      restrictedProject:
        name: projects/PROJECT_NUMBER
  activeSettings:
    sessionSettings:
      sessionLength: 7776000s
      sessionLengthEnabled: true
      sessionReauthMethod: LOGIN

Create the access binding:

gcloud access-context-manager cloud-bindings create \
    --organization=ORG_ID \
    --federated-principal="principalSet://cloudresourcemanager.googleapis.com/organizations/ORG_ID/type/WorkforcePool" \
    --binding-file="esl-binding.yaml"

Replace the following:

ORG_ID: Your Google Cloud organization ID (for example, 123456789012).
PROJECT_NUMBER: The project number that owns the target Looker (Google Cloud core) instance (for example, 987654321098). Only Looker (Google Cloud core) applications owned by this project receive the extended session length.
sessionLength: The session duration in seconds followed by s. For example, 7776000s specifies a 90-day session.
sessionLengthEnabled: Set to true.
sessionReauthMethod: Set to LOGIN (or leave unset).

REST API

Send a POST request to the Access Context Manager API:

POST https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings

JSON request body:

{
  "principal": {
    "federatedPrincipal": "principalSet://cloudresourcemanager.googleapis.com/organizations/ORG_ID/type/WorkforcePool"
  },
  "scopedAccessSettings": [
    {
      "scope": {
        "clientScope": {
          "restrictedProject": {
            "name": "projects/PROJECT_NUMBER"
          }
        }
      },
      "activeSettings": {
        "sessionSettings": {
          "sessionLength": "7776000s",
          "sessionLengthEnabled": true,
          "sessionReauthMethod": "LOGIN"
        }
      }
    }
  ]
}

Replace the following:

ORG_ID: Your Google Cloud organization ID (for example, 123456789012).
PROJECT_NUMBER: The project number that owns the target Looker (Google Cloud core) instance (for example, 987654321098). Only Looker (Google Cloud core) applications owned by this project receive the extended session length.
sessionLength: The session duration in seconds followed by s. For example, 7776000s specifies a 90-day session.
sessionLengthEnabled: Set to true.
sessionReauthMethod: Set to LOGIN (or leave unset).

Viewing and listing bindings

Because the binding applies across all workforce pools in the organization, there is at most one access binding per organization.

List active bindings

To list the workforce pool access binding in your organization, use the principal:federatedPrincipal filter:

gcloud

gcloud access-context-manager cloud-bindings list \
    --organization=ORG_ID \
    --filter="principal:federatedPrincipal"

REST API

GET https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings?filter=principal:federated_principal

Get binding details

To view the details of a specific workforce pool access binding:

gcloud

gcloud access-context-manager cloud-bindings describe \
    --binding=BINDING_NAME

Replace BINDING_NAME with the full resource name of the binding (for example, organizations/123456789012/gcpUserAccessBindings/b1234567890).

REST API

GET https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings/BINDING_ID

Replace the following:

ORG_ID: Your Google Cloud organization ID (for example, 123456789012).
BINDING_ID: The ID of your access binding (for example, b1234567890).

Update an access binding

You can update an existing workforce pool access binding to modify session lengths, add new project scopes, or remove existing project scopes.

gcloud

Define the updated policy in a YAML file named updated-esl-binding.yaml:

scopedAccessSettings:
- scope:
    clientScope:
      restrictedProject:
        name: projects/PROJECT_NUMBER
  activeSettings:
    sessionSettings:
      sessionLength: 2592000s
      sessionLengthEnabled: true
      sessionReauthMethod: LOGIN

Apply the updated policy:
- Replace scoped access settings: To overwrite the existing project scopes with the configuration defined in updated-esl-binding.yaml:
```
gcloud access-context-manager cloud-bindings update \
    --binding=BINDING_NAME \
    --binding-file="updated-esl-binding.yaml"
```
- Append to existing settings: To append the project scopes defined in updated-esl-binding.yaml to the binding's existing project scopes without overwriting them, pass the --append flag:
```
gcloud access-context-manager cloud-bindings update \
    --binding=BINDING_NAME \
    --binding-file="updated-esl-binding.yaml" \
    --append
```

Replace the following: * BINDING_NAME: The full resource name of the binding (for example, organizations/123456789012/gcpUserAccessBindings/b1234567890). * PROJECT_NUMBER: The project number that owns the target Looker (Google Cloud core) instance. * sessionLength: The updated session duration (for example, 2592000s for 30 days).

REST API

Send a PATCH request to update the binding.

Replace scoped access settings: To overwrite existing project scopes:

PATCH https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings/BINDING_ID?updateMask=scopedAccessSettings

Append to existing settings: To append new project scopes without overwriting existing ones, set the append=true query parameter:

PATCH https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings/BINDING_ID?updateMask=scopedAccessSettings&append=true

JSON request body:

{
"scopedAccessSettings": [
  {
    "scope": {
      "clientScope": {
        "restrictedProject": {
          "name": "projects/PROJECT_NUMBER"
        }
      }
    },
    "activeSettings": {
      "sessionSettings": {
        "sessionLength": "2592000s",
        "sessionLengthEnabled": true,
        "sessionReauthMethod": "LOGIN"
      }
    }
  }
]
}

Replace the following: * ORG_ID: Your Google Cloud organization ID (for example, 123456789012). * BINDING_ID: The ID of your access binding (for example, b1234567890). * PROJECT_NUMBER: The project number that owns the target Looker (Google Cloud core) instance. * sessionLength: The updated session duration (for example, 2592000s for 30 days).

Delete an access binding

If you delete the workforce pool access binding, extended session length is disabled for all workforce pools in your organization.

gcloud

gcloud access-context-manager cloud-bindings delete \
    --binding=BINDING_NAME

Replace BINDING_NAME with the full resource name of the binding.

REST API

Send a DELETE request to remove the binding:

DELETE https://accesscontextmanager.googleapis.com/v1/organizations/ORG_ID/gcpUserAccessBindings/BINDING_ID

Replace the following:

ORG_ID: Your Google Cloud organization ID.
BINDING_ID: The ID of the access binding to delete.

Configure Extended Session Length for Workforce Identity Federation Stay organized with collections Save and categorize content based on your preferences.

Overview

Before you begin

Required roles and permissions

Enable APIs

Limitations and Requirements

Configure the workforce pool provider

Configure an OIDC provider

gcloud

REST API

Configure a SAML provider

Example policy configuration for Looker (Google Cloud core)

gcloud

REST API

Viewing and listing bindings

List active bindings

gcloud

REST API

Get binding details

gcloud

REST API

Update an access binding

gcloud

REST API

Delete an access binding

gcloud

REST API

Configure Extended Session Length for Workforce Identity Federation