Configure Workforce Identity Federation

This guide describes how to configure Workforce Identity Federation with an identity provider (IdP) that supports OIDC or SAML 2.0.

For IdP-specific instructions, see the following:

Before you begin

  1. Make sure that you have a Google Cloud organization set up.

  2. 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.

  3. Enable the Identity and Access Management (IAM) and Resource Manager APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  4. For sign-in, your IdP must provide signed authentication information: OIDC IdPs must provide a JWT, and SAML IdP responses must be signed.
  5. To receive important information about changes to your organization or Google Cloud products, you must provide Essential Contacts. For more information, see the Workforce Identity Federation overview.

Costs

Workforce Identity Federation is available as a no-cost feature. However, Workforce Identity Federation detailed audit logging uses Cloud Logging. To learn about Logging pricing, see Google Cloud Observability pricing.

Required roles

To get the permissions that you need to configure Workforce Identity Federation, ask your administrator to grant you the Workforce Identity Pool Admin (roles/iam.workforcePoolAdmin) IAM role on the organization. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Alternatively, the Owner basic role (roles/owner) also includes permissions to configure Workforce Identity Federation. You should not grant basic roles in a production environment, but you can grant them in a development or test environment.

Configure Workforce Identity Federation

To configure Workforce Identity Federation, you create a workforce identity pool and a workforce identity pool provider.

Create a workforce identity pool

To create the pool, execute the following command:

gcloud

To create the workforce identity pool, run the following command:

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

Replace the following:

  • WORKFORCE_POOL_ID: an ID that you choose to represent your Google Cloud workforce pool. The pool ID must be globally unique across all workforce identity pools in Google Cloud. For information on formatting the ID, see the Query parameters section in the API documentation.
  • ORGANIZATION_ID: the numeric organization ID of your Google Cloud organization for the workforce identity pool. Workforce identity pools are available across all projects and folders in the organization.
  • DISPLAY_NAME: Optional. A display name for your workforce identity pool.
  • DESCRIPTION: Optional. A workforce identity pool description.
  • SESSION_DURATION: Optional. The session duration, expressed as a number appended with s—for example, 3600s. Session duration determines how long the Google Cloud access tokens, console (federated) sign-in sessions, and gcloud CLI sign-in sessions from this workforce pool are valid. Session duration defaults to one hour (3600s). The session duration value must be between 15 minutes (900s) and 12 hours (43200s).

Console

To create the workforce identity pool, do the following:

  1. In the Google Cloud console, go to the Workforce Identity Pools page:

    Go to Workforce Identity Pools

  2. Select the organization for your workforce identity pool. Workforce identity pools are available across all projects and folders in an organization.

  3. Click Create pool and do the following:

    1. In the Name field, enter the display name of the pool. The pool ID is automatically derived from the name as you type, and it is displayed under the Name field. You can update the pool ID by clicking Edit next to the pool ID.

    2. Optional: In Description, enter a description of the pool.

    3. To create the workforce identity pool, click Next.

The workforce identity pool's session duration defaults to one hour (3600s). The session duration determines how long the Google Cloud access tokens, console (federated), and gcloud CLI sign-in sessions from this workforce pool are valid. After you create the pool, you can update the pool to set a custom session duration. The session duration must be from 15 minutes (900s) to 12 hours (43200s).

Create a workforce identity pool provider

This section describes how to create a workforce identity pool provider to enable your IdP users to access Google Cloud. You can configure the provider to use either the OIDC or SAML protocol.

Create an OIDC workforce pool provider

To create a workforce identity pool provider using the OIDC protocol, do the following:

  1. In your OIDC IdP, register a new application for Google Cloud Workforce Identity Federation. Note the client ID and issuer URI provided by the IdP. You use them in this document.

  2. If you plan to set up user access to the console, add the following redirect URL to your OIDC IdP:

    https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

    Replace the following:

    • WORKFORCE_POOL_ID: the workforce identity pool ID

    • WORKFORCE_PROVIDER_ID: the ID of the workforce identity pool provider that you create later in this document.

    To learn how to configure console (federated) sign-in, see Set up user access to the console (federated).

  3. In Google Cloud, to create the provider, do the following:

    gcloud

    Code flow

    To create an OIDC provider that uses authorization code flow for web sign-in, run the following command:

    gcloud iam workforce-pools providers create-oidc WORKFORCE_PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --issuer-uri="ISSUER_URI" \
    --client-id="OIDC_CLIENT_ID" \
        --client-secret-value="OIDC_CLIENT_SECRET" \
    --web-sso-response-type="code" \
    --web-sso-assertion-claims-behavior="merge-user-info-over-id-token-claims" \
    --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \
    --attribute-mapping="ATTRIBUTE_MAPPING" \
    --attribute-condition="ATTRIBUTE_CONDITION" \
    --jwk-json-path="JWK_JSON_PATH" \
    --detailed-audit-logging \
    --location=global

    Replace the following:

    • WORKFORCE_PROVIDER_ID: A unique workforce identity pool provider ID. The prefix gcp- is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.
    • WORKFORCE_POOL_ID: The workforce identity pool ID to connect your IdP to.
    • DISPLAY_NAME: An optional user-friendly display name for the provider; for example, idp-eu-employees.
    • DESCRIPTION: An optional workforce provider description; for example, IdP for Partner Example Organization employees.
    • ISSUER_URI: The OIDC issuer URI, in a valid URI format, that starts with https; for example, https://example.com/oidc. Note: For security reasons, ISSUER_URI must use the HTTPS scheme.
    • OIDC_CLIENT_ID: The OIDC client ID that is registered with your OIDC IdP; the ID must match the aud claim of the JWT that is issued by your IdP.
    • OIDC_CLIENT_SECRET: The OIDC client secret.
    • WEB_SSO_ADDITIONAL_SCOPES: Optional additional scopes to send to the OIDC IdP for console (federated) or gcloud CLI browser-based sign-in.
    • ATTRIBUTE_MAPPING: An attribute mapping. The following is an example of an attribute mapping: 
      google.subject=assertion.oid
google.groups=assertion.groups,
attribute.costcenter=assertion.costcenter
       This example maps the IdP attributes assertion.oid, assertion.groups, and assertion.costcenter in the OIDC assertion to the Google Cloud attributes google.subject, google.groups, and attribute.costcenter, respectively.
    • ATTRIBUTE_CONDITION: An attribute condition; for example, assertion.role == 'gcp-users'. This example condition ensures that only users with the role gcp-users can sign in using this provider.
    • JWK_JSON_PATH: An optional path to a locally uploaded OIDC JWKs. If this parameter isn't supplied, Google Cloud instead uses your IdP's /.well-known/openid-configuration path to source the JWKs containing the public keys. For more information about locally uploaded OIDC JWKs, see manage OIDC JWKs.

    • Workforce Identity Federation detailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, see General attribute mapping errors. To learn about Logging pricing, see Google Cloud Observability pricing.

      To disable detailed audit logging for a workforce identity pool provider, omit the --detailed-audit-logging flag when you run gcloud iam workforce-pools providers create. To disable detailed audit logging, you can also update the provider.

    In the command response, POOL_RESOURCE_NAME is the name of the pool; for example, locations/global/workforcePools/enterprise-example-organization-employees.

    Implicit flow

    To create an OIDC provider that uses the implicit flow for web sign-in, run the following command:

    gcloud iam workforce-pools providers create-oidc WORKFORCE_PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --issuer-uri="ISSUER_URI" \
    --client-id="OIDC_CLIENT_ID" \
    --web-sso-response-type="id-token" \
    --web-sso-assertion-claims-behavior="only-id-token-claims" \
    --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \
    --attribute-mapping="ATTRIBUTE_MAPPING" \
    --attribute-condition="ATTRIBUTE_CONDITION" \
    --jwk-json-path="JWK_JSON_PATH" \
    --detailed-audit-logging \
    --location=global

    Replace the following:

    • WORKFORCE_PROVIDER_ID: A unique workforce identity pool provider ID. The prefix gcp- is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.
    • WORKFORCE_POOL_ID: The workforce identity pool ID to connect your IdP to.
    • DISPLAY_NAME: An optional user-friendly display name for the provider; for example, idp-eu-employees.