Configure Workload Identity Federation with other identity providers

This guide describes how to use Workload Identity Federation with other identity providers (IdPs).

To authenticate to Google Cloud, you can let the workload exchange its environment-specific credentials for short-lived Google Cloud credentials by using Workload Identity Federation.

Workloads that run outside of Google Cloud might have access to existing, environment-specific credentials, for example:

  • A workload might be able to obtain an OpenID Connect (OIDC) assertion token from an identity provider (IdP).

  • A workload might be able to obtain a SAML assertion token from an identity provider (IdP).

Using Workload Identity Federation can help you reduce the number of credentials that require rotation.

The following sections describe how you can use Workload Identity Federation with IdPs that support either OpenID Connect (OIDC) or SAML authentication protocols.

Prepare your external IdP

You need to perform these steps once for each IdP.

Before you begin, verify that your external IdP meets the following requirements:

OIDC

  • The IdP supports OpenID Connect 1.0.

  • The IdP has an issuer URI.

  • Google Cloud can access a JSON web key set (JWKS) that contains JSON web keys (JWKs). The JWKs are used to validate OIDC assertion tokens. You can provide access to the JWKS through one of the following methods:

    • Google Cloud downloads OIDC metadata from the IdP, through a publicly available, well-known, internet-accessible discovery URL. Within the metadata, the JWKS URL must be secured with SSL and TLS. The JWKS URL must start with https://. Google Cloud doesn't support JWKS URLs that are secured with self-signed certificates.

      Google Cloud uses these endpoint URLs to download your IdP's JSON web keys (JWKs) and uses these keys to validate tokens. Google Cloud doesn't limit the number of keys that it can download.

    • You can upload an OIDC JWKS file directly to Google Cloud when you create or update the OIDC workload identity pool provider. To do this, you use the --jwk-json-path to provide a path to your JWKS file. You can use this method when the IdP's OIDC metadata endpoint URL isn't publicly accessible. A maximum of 8 keys can be uploaded to Google Cloud. As a best practice, we recommend that you rotate your JWKS keys regularly by updating the JWKS file.

  • If you're federating workloads from AWS using AWS Outbound Identity Federation, AWS acts as your OIDC IdP. To prepare your AWS environment, follow these steps:

    1. Enable outbound identity federation in your AWS account settings to generate your unique OIDC issuer URL.

    2. Ensure your AWS workloads (such as EC2 instance profiles or ECS task roles) have the required AWS IAM policy granting permission to get JSON Web Tokens (JWTs).

SAML

  • The IdP supports SAML 2.0.

  • The IdP provides a SAML SP metadata document that describes the SAML service provider configuration and contains the IdP's signing certificate.

    Google Cloud uses this certificate to validate SAML assertions and responses.

  • The IdP signing certificate must contain either an ECDSA or RSA key that is within an X.509 v3 certificate.

  • Recommended signing algorithms include the following:

  • The signing certificate must meet the following validity requirements:

    • notBefore: a timestamp that is no more than 7 days in the future
    • notAfter: a timestamp that is no more than 25 years in the future

You can configure a SAML workload identity pool provider with at most three SAML signing certificates at a given time. This limitation doesn't apply to other workload identity pool provider types, like OIDC and X.509. When multiple certificates exist, Google Cloud iterates through them and attempts to use each non-expired certificate to fulfill a token exchange request.

As a security best practice, we strongly recommend that you don't reuse the same key pair with other services.

If your IdP meets these criteria, do the following:

OIDC

Configure your IdP so that your workload can obtain ID tokens that meet the following criteria:

  • Tokens are signed using the RS256 or ES256 algorithm.

  • Tokens contain an aud claim with the following value:

    https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID

    Replace the following:

    • PROJECT_NUMBER: the project number of the Google Cloud project that you use to create a workload identity pool.
    • POOL_ID: an ID of your choice that identifies the workload identity pool. You must use the same ID when creating the workload identity pool later.
    • WORKLOAD_PROVIDER_ID: an ID of your choice that identifies the workload identity pool provider. You must use the same ID when creating the workload identity pool provider later.

    Alternatively, you can configure the workload identity pool provider to expect a custom audience.

  • Tokens contain an exp claim that is in the future and an iat claim that is in the past.

    The value of exp must be greater than the value of iat by at most 24 hours.

Typically, it's best to use ID tokens when performing a token exchange, because ID tokens reflect the user's identity. If you decide to use access tokens instead, make sure that access tokens meet the following additional requirements:

  • Access tokens are JSON Web Token-formatted.

  • Access tokens contain an ISSUER claim so that the URL ISSUER/.well-known/openid-configuration points to the IdP's OIDC metadata endpoint.

  • To upload local JWK keys, see Manage OIDC JWKs.

SAML

Configure your IdP so that SAML assertions contain elements that meet the following criteria:

  • an Issuer element that is set to the Entity ID configured in the workload identity pool provider. The issuer format must be omitted or set to urn:oasis:names:tc:SAML:2.0:nameid-format:entity.
  • a Subject element with:
    • a NameID element.
    • exactly one SubjectConfirmation element with Method set to urn:oasis:names:tc:SAML:2.0:cm:bearer.
    • a SubjectConfirmationData element with NotOnOrAfter set to a timestamp that occurs in the future and no NotBefore value.

  • a Conditions element with:

    • NotBefore omitted or in the past.
    • NotOnOrAfter omitted or in the future.

    • An Audience that is formatted as follows:

      https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID

      Replace the following:

      • PROJECT_NUMBER: the project number of the Google Cloud project that you use to create workload identity pool.
      • POOL_ID: an ID of your choice that identifies the workload identity pool. You must use the same ID when creating the workload identity pool later.
      • WORKLOAD_PROVIDER_ID: an ID of your choice that identifies the workload identity pool provider. You must use the same ID when creating the workload identity pool provider later.

  • at least one AuthnStatement element.

  • a SessionNotOnOrAfter element with a timestamp that occurs in the future. Alternatively, omit the element.

For SAML assertions that are enclosed in a SAML response, the SAML response must contain:

  • exactly one assertion that meets the SAML assertion criteria that is described earlier in this section.
  • an IssueInstant attribute with a value less than 1 hour in the past.
  • the StatusCode urn:oasis:names:tc:SAML:2.0:status:Success.

Either the SAML assertion, the response, or both must be signed.

Configure Workload Identity Federation

You only need to perform these steps once for each IdP. You can then use the same workload identity pool and provider for multiple workloads and across multiple Google Cloud projects.

To start configuring Workload Identity Federation, do the following:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.