Configure session controls for reauthentication

Session controls let you configure how often users must reauthenticate after being granted access and whether a full login, password only, or hardware security key is required.

You can apply session controls to do the following:

  • Enforce frequent reauthentication for privileged users: Require users with elevated privileges, such as project owners and billing administrators, to reauthenticate more frequently.
  • Configure longer sessions for certain applications: Allow certain applications, such as context-based AI applications like Gemini, to have longer session durations to preserve the large context window required for optimal performance.

Define session length and reauthentication methods

You can define session controls when creating an Access Context Manager binding. For more information about the session controls, see Apply policies to user groups using access bindings.

gcloud

  • Set default session controls for all applications

    Use the --session-length flag to set the session duration. The value must be 0s, or between 1 hour and 24 hours. Specify the duration in hours. For example, use "12h" to set a session that is 12 hours long. Use the --session-reauth-method flag to specify the reauthentication method. For example, you can set a session duration time of 3 hours (3h) and a LOGIN, PASSWORD, or SECURITY_KEY reauthentication method.

    This will be applied to all applications unless overridden by application-specific settings.

  • Set application-specific session controls

    Define scopedAccessSettings in a YAML file to specify session controls for specific applications using clientId. This lets you override the default session controls for those applications. You can then pass the YAML file using the --binding-file flag.

REST API

Define the sessionLength and sessionReauthMethod fields within the sessionSettings object in the JSON body of your POST request to create or update a GcpUserAccessBinding binding.

  • sessionLength is the session duration in seconds. The value must be 0s, or between 1 hour and 24 hours, formatted as a number of seconds followed by s (for example, 3600s, which corresponds to a 1 hour session length).
  • sessionReauthMethod can be LOGIN, PASSWORD, or SECURITY_KEY.
  • Use scopedAccessSettings to define application-specific session controls. See Define configurations for specific applications for details.

Terraform

Within the Terraform Google Cloud User Access Binding resource, populate the session_settings argument to configure general session length controls that apply to all user traffic:

  • session_length: The duration of the session in seconds. For example, 3600s sets the session length to 1 hour. The s at the end is required.
  • session_length_enabled: Set to false to disable the specified session settings.
  • session_reauth_method: The type of authentication challenge that's used to refresh credentials. The options are LOGIN, PASSWORD, or SECURITY_KEY.
  • use_oidc_max_age: An advanced field that's used to configure whether the session honors an optional OIDC maximum age parameter, which is specified if the authenticating credential is an OAuth token.

When defining session controls only the most recently created access binding that matches the request is used when resolving session control settings.

Example policy configuration

The following example shows how to create a session control that requires reauthentication every 18 hours with LOGIN and every two hours for a specific application (SENSITIVE_APP_ID) with SECURITY_KEY.

Default settings

The --level, --session-length, and --session-reauth-method flags in the Google Cloud CLI command (or the corresponding fields in the JSON body for the API call) set the default behavior for all applications not explicitly defined in scopedAccessSettings.

Application-specific settings

The scopedAccessSettings section in the YAML file (or JSON body) lets you override the default settings for specific applications. In the example, we set a two hour reauthentication requirement with SECURITY_KEY for the application with the client ID SENSITIVE_APP_ID.

To exempt certain applications from session control, set the sessionLength field to 0s or sessionLengthEnabled to false. The sessionReauthMethod method will then be ignored.

gcloud

The following example shows the session settings configuration:

scopedAccessSettings:
  scope:
    clientScope:
      restrictedClientApplication:
        clientId: SENSITIVE_APP_ID
  activeSettings:
    sessionSettings:
      sessionLength: 7200s
      sessionReauthMethod: SECURITY_KEY
      sessionLengthEnabled: true

Create the access binding:

gcloud access-context-manager cloud-bindings create \
    --organization=ORG_ID \
    --group-key=GROUP_ID \
    --binding-file=BINDING_FILE_PATH \
    --level=DEFAULT_ACCESS_LEVEL \
    --session-length=SESSION_LENGTH \
    --session-reauth-method LOGIN

Replace the following:

  • ORG_ID: the ID of the organization
  • GROUP_ID: the group key
  • BINDING_FILE_PATH: the path of the binding file
  • DEFAULT_ACCESS_LEVEL: the default access level
  • SESSION_LENGTH: the session length, for example,18h

REST API

An example JSON body of the API request:

{
  "groupKey": "GROUP_ID",
  "accessLevels": [
    "accessPolicies/POLICY_ID/accessLevels/DEFAULT_ACCESS_LEVEL"
  ],
  "scopedAccessSettings": [
    {
      "scope": {
        "clientScope": {
          "restrictedClientApplication": {
            "clientId": "SENSITIVE_APP_ID"
          }
        }
      },
      "activeSettings": {
        "accessLevels": [
          "accessPolicies/POLICY_ID/accessLevels/ACCESS_LEVEL_NAME"
        ],
        "sessionSettings": [
          {
            "sessionLength": "2h",
            "sessionReauthMethod": "SECURITY_KEY",
            "sessionLengthEnabled": true
          }
        ]
      }
    }
  ]

Construct the POST request in the following format:

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

Replace ORG_ID with the ID of the organization.

Terraform

To specify a session length for access requests from users coming from "Group Key" across all applications:

    resource "google_access_context_manager_gcp_user_access_binding" "gcp_user_access_binding" {
      organization_id = "{Organization ID}"
      group_key = "{Group Key}"
      session_settings {
        session_length = "3600s"
        session_length_enabled = true
        session_reauth_method = "LOGIN"
        use_oidc_max_age = false
      }

To specify a session length for requests from users coming from a specific Google Group using a specific app, such as the Google Cloud console, populate the appropriate scoped_access_settings argument with a session_settings argument in active_settings. The sub-arguments within session_settings are identical to the top level argument.

    resource "google_access_context_manager_gcp_user_access_binding" "gcp_user_access_binding" {
      organization_id = "{Organization ID}"
      group_key = "{Group Key}"
      scoped_access_settings {
        scope {
          client_scope {
            restricted_client_application {
              name = "Cloud Console"
            }
          }
        }
        active_settings {
          session_settings {
            session_length = "3600s"
            session_length_enabled = true
            session_reauth_method = "LOGIN"
            use_oidc_max_age = false
          }
        }
      }
    }

Example policy configuration for Google Cloud applications

You can configure application-specific reauthentication controls for Google Cloud applications, for example requiring SECURITY_KEY for Google Cloud SDK and LOGIN for the Google Cloud console. The following example shows how to create a session control that requires reauthentication every hour for Google Cloud SDK with SECURITY_KEY, and every 4 hours for the Google Cloud console with LOGIN.

The scopedAccessSettings section in the YAML file (or JSON body) lets you override the default settings for specific applications. In this example, we set a one hour reauthentication requirement with SECURITY_KEY for Google Cloud SDK, and a four hour reauthentication requirement with LOGIN for the Google Cloud console using the name field to identify these applications.

To exempt certain applications from session control, set the sessionLength field to 0s or sessionLengthEnabled to false. The sessionReauthMethod method will then be ignored.

gcloud

The following example shows the session settings configuration:

scopedAccessSettings:
- scope:
    clientScope:
      restrictedClientApplication:
        name: Google Cloud SDK
  activeSettings:
    sessionSettings:
      sessionLength: 3600s
      sessionReauthMethod: SECURITY_KEY
      sessionLengthEnabled: true
- scope:
    clientScope:
      restrictedClientApplication:
        name: Cloud Console
  activeSettings:
    sessionSettings:
      sessionLength: 14400s
      sessionReauthMethod: LOGIN
      sessionLengthEnabled: true

Create the access binding:

gcloud access-context-manager cloud-bindings create \
    --organization=ORG_ID \
    --group-key=GROUP_ID \
    --binding-file=BINDING_FILE_PATH

Replace the following:

  • ORG_ID: the ID of the organization
  • GROUP_ID: the group key
  • BINDING_FILE_PATH: the path of the binding file

REST API

An example JSON body of the API request:

{
  "groupKey": "GROUP_ID",
  "scopedAccessSettings": [
    {
      "scope": {
        "clientScope": {
          "restrictedClientApplication": {
            "name": "Google Cloud SDK"
          }
        }
      },
      "activeSettings": {
        "sessionSettings": {
            "sessionLength": "3600s",
            "sessionReauthMethod": "SECURITY_KEY",
            "sessionLengthEnabled": true
          }
      }
    },
    {
      "scope": {
        "clientScope": {
          "restrictedClientApplication": {
            "name": "Cloud Console"
          }
        }
      },
      "activeSettings": {
        "sessionSettings": {
            "sessionLength": "14400s",
            "sessionReauthMethod": "LOGIN",
            "sessionLengthEnabled": true
          }
      }
    }
  ]
}

Construct the POST request in the following format:

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

Replace ORG_ID with the ID of the organization.

Terraform

To specify session length settings for Google Cloud SDK and the Google Cloud console, populate the appropriate scoped_access_settings argument:

    resource "google_access_context_manager_gcp_user_access_binding" "gcp_user_access_binding" {
      organization_id = "{Organization ID}"
      group_key = "{Group Key}"
      scoped_access_settings {
        scope {
          client_scope {
            restricted_client_application {
              name = "Google Cloud SDK"
            }
          }
        }
        active_settings {
          session_settings {
            session_length = "3600s"
            session_length_enabled = true
            session_reauth_method = "SECURITY_KEY"
            use_oidc_max_age = false
          }
        }
      }
      scoped_access_settings {
        scope {
          client_scope {
            restricted_client_application {
              name = "Cloud Console"
            }
          }
        }
        active_settings {
          session_settings {
            session_length = "14400s"
            session_length_enabled = true
            session_reauth_method = "LOGIN"
            use_oidc_max_age = false
          }
        }
      }
    }