Revoke Workforce Identity Federation user sessions

This guide shows you how to revoke active sessions and short-lived credentials for workforce users (also known as workforce principals).

Revoking sessions immediately invalidates active sessions and credentials. However, it doesn't delete user metadata or resources, or prevent subsequent sign-ins if the user remains active in your identity provider (IdP).

Revoking sessions is useful in scenarios such as the following:

  • Suspected credential compromise: You suspect that a user's active session or credentials are compromised and must immediately cut off access.
  • Offboarding or role transitions: You must immediately terminate access for a user who is leaving the organization or changing roles, while identity deletion or group updates are in progress. Because deleting a user initiates an asynchronous 30-day soft-deletion process, revoke sessions to immediately terminate a user's active access.
  • Immediate policy enforcement: You modified user permissions or group memberships in your IdP and want the user to re-authenticate immediately so that updated session attributes and group memberships take effect.

Before you begin

Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

gcloud init

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Required roles

To get the permission that you need to revoke workforce user sessions, ask your administrator to grant you the Workforce Pool Admin (roles/iam.workforcePoolAdmin) IAM role on the organization or workforce pool. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the iam.googleapis.com/workforcePoolSubjects.revokeSessions permission, which is required to revoke workforce user sessions.

You might also be able to get this permission with custom roles or other predefined roles.

Revoke user sessions

Revoking a workforce user's sessions immediately invalidates all active Google Cloud console sessions, session cookies, short-lived OAuth 2.0 access tokens, and credentials issued for that user subject, requiring the user to re-authenticate with your identity provider (IdP).

To revoke sessions for a workforce user, do the following:

gcloud

The gcloud iam workforce-pools subjects revoke-sessions command revokes active sessions and short-lived credentials for a workforce pool subject.

Before using any of the command data below, make the following replacements:

  • SUBJECT_ID: The user subject ID whose sessions you want to revoke. If you are retrieving the user's identity from Cloud Audit Logs or IAM allow policies, the subject ID is the final segment of the user's principal identifier, which has the following format: principal://iam.googleapis.com/locations/LOCATION/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID.
  • WORKFORCE_POOL_ID: The workforce pool ID.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud iam workforce-pools subjects revoke-sessions \
    SUBJECT_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --location=global

Windows (PowerShell)

gcloud iam workforce-pools subjects revoke-sessions `
    SUBJECT_ID `
    --workforce-pool=WORKFORCE_POOL_ID `
    --location=global

Windows (cmd.exe)

gcloud iam workforce-pools subjects revoke-sessions ^
    SUBJECT_ID ^
    --workforce-pool=WORKFORCE_POOL_ID ^
    --location=global

REST

The locations.workforcePools.subjects.revokeSessions method revokes active sessions and short-lived credentials for a workforce pool subject.

Before using any of the request data, make the following replacements:

  • SUBJECT_ID: The user subject ID whose sessions you want to revoke. If you are retrieving the user's identity from Cloud Audit Logs or IAM allow policies, the subject ID is the final segment of the user's principal identifier, which has the following format: principal://iam.googleapis.com/locations/LOCATION/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID.
  • WORKFORCE_POOL_ID: The workforce pool ID.

HTTP method and URL: 

POST https://iam.googleapis.com/v1/locations/global/workforcePools/WORKFORCE_POOL_ID/subjects/SUBJECT_ID:revokeSessions

To send your request, expand one of these options:

If the request is successful, the response body is empty. 

{}

What's next