Configure Workload Identity Federation with X.509 certificates

Stay organized with collections Save and categorize content based on your preferences.

To request access to this feature now, fill out access request form.

This guide describes how to use Workload Identity Federation with X.509 certificates that are issued by your certificate authority (CA) to authenticate to Google Cloud and access Google Cloud resources.

If your workloads possess an mTLS client certificate, you can authenticate to Google Cloud by registering one or more CAs with Workload Identity Federation as trust anchors. You can also register intermediate CAs.

By using Workload Identity Federation, you can let these workloads obtain short-lived Google Cloud credentials through a mutual TLS (mTLS) connection. Workloads can use these short-lived credentials to access Google Cloud APIs.

Concepts

The X.509 certificate-based federation concepts include the following:

• A trust anchor is a CA certificate that is considered as the root of trust. Any client certificate chains should be chained up to one of the trust anchors.

• An intermediate CA is an optional certificate authority certificate that helps build the client certificate chain.

• A trust store contains the trust anchor certificates and intermediate CA certificates that are used to validate the client certificate chain. A CA issues trusted certificates for the client.

  You can upload the following types of client certificates to the trust store:

  • Certificates issued by third-party CAs of your choice
  • Certificates issued by your private CAs
  • Signed certificates, as described in Create self-signed certificates

Before you begin

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.

   Go to project selector

We recommend that you use a dedicated project to manage workload identity pools and providers.

2. Make sure that billing is enabled for your Google Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Enable the APIs

Required roles

To get the permissions that you need to configure Workload Identity Federation, ask your administrator to grant you the following IAM roles on the project:

• Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin)
• Service Account Admin (roles/iam.serviceAccountAdmin)

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 IAM Owner (roles/owner) basic role also includes permissions to configure identity federation. You should not grant basic roles in a production environment, but you can grant them in a development or test environment.

Create a trust store

This section shows you how to create a trust store. At a high level, the steps are as follows:

• Generate self-signed certificates
• Format the certificates
• Create the trust store

Generate self-signed certificates

This section shows you how to generate keys and create signed certificates. If you have already created certificates, you can skip this section and continue with Format the certificates.

This section uses openssl commands to create root and intermediate certificates.

To generate a root certificate and a signed intermediate certificate with valid keyUsage and extendedKeyUsage fields, do the following:

1. Create an openssl configuration file to create your signing certificates. At minimum, the file is similar to the following, but you can set additional fields as needed.

   cat > example.cnf << EOF
   [req]
   distinguished_name = empty_distinguished_name
   [empty_distinguished_name]
   # Kept empty to allow setting via -subj command-line argument.
   [ca_exts]
   basicConstraints=critical,CA:TRUE
   keyUsage=keyCertSign
   extendedKeyUsage=clientAuth
   [leaf_exts]
   keyUsage=critical,Digital Signature, Key Encipherment
   basicConstraints=critical, CA:FALSE
   EOF
   

2. Create the root certificate.

   openssl req -x509 \
       -new -sha256 -newkey rsa:2048 -nodes \
       -days 3650 -subj '/CN=root' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout root.key -out root.cert
   

3. Create the signing request for the intermediate certificate.

   openssl req \
       -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=int' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout int.key -out int.req
   

4. Create the intermediate certificate.

   openssl x509 -req \
       -CAkey root.key -CA root.cert \
       -set_serial 1 \
       -days 3650 \
       -extfile example.cnf \
       -extensions ca_exts \
       -in int.req -out int.cert
   

5. Create the signing request for leaf certificate.

   openssl req -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=example' \
       -config example.cnf \
       -extensions leaf_exts \
       -keyout leaf.key -out leaf.req
   

6. Create the leaf certificate issued by the intermediate.

   openssl x509 -req \
       -CAkey int.key -CA int.cert \
       -set_serial 1 -days 3650 \
       -extfile example.cnf \
       -extensions leaf_exts \
       -in leaf.req -out leaf.cert
   

Format the certificates

To include new or existing certificates in a trust store, format the certificates into a one-line string, and store them in environment variables. The certificates must be PEM formatted. To format the certificates and store them in environment variables, do the following:

1. Save the root certificate as a one-line string.

   export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

2. Save an intermediate certificate as a one-line string.

   export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

Create the trust store

In this section, you create a trust store using a YAML-formatted file that contains your trust anchors and intermediate CAs.

This file contains the certificate content from the environment variables that you created in Format the certificates. To add additional trust anchors, add additional trustAnchors entries under trustStore. To add additional intermediate CA certificates, add additional intermediateCas entries under trustStore.

To create the trust store file, run the following command:

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

Define an attribute mapping and condition

The client X.509 certificate can contain multiple attributes. You must select which attribute you want to use as the subject identifier by mapping google.subject in Google Cloud to the attribute from your certificate. For example, if the attribute in the certificate is the subject common name, then the mapping would be as follows: google.subject=assertion.subject.dn.cn

Optionally, you can map additional attributes. You can then refer to these attributes when granting access to resources.

Your attribute mappings can use the attributes within the client certificate, including the following:

• serialNumberHex: the serial number
• subject.dn.cn: the subject common name
• subject.dn.o: the subject organization name
• subject.dn.ou: the subject organization unit
• issuer.dn.cn: the issuer common name
• issuer.dn.o: the issuer organization name
• issuer.dn.ou: the issuer organization unit
• san.dns: the subject alternative name's first DNS name
• san.uri: the subject alternative name's first URI

You must map one of these attributes to google.subject to uniquely identify the subject. To protect against spoofing threats, choose an attribute with a unique value that can't be changed. By default, the google.subject identifier is set to the client certificate subject common name, assertion.subject.dn.cn.

Optionally, you can define an attribute condition. Attribute conditions are CEL expressions that can check assertion attributes and target attributes. If the attribute condition evaluates to true for a given credential, the credential is accepted. Otherwise, the credential is rejected.

You can use an attribute condition to restrict which subjects can use Workload Identity Federation to obtain short-lived Google Cloud tokens.

For example, the following condition restricts access to client certificates containing SPIFFE ID spiffe://example/path:

assertion.san.uri=="spiffe://example/path"

Configure Workload Identity Federation

This section shows you how to configure a workload identity pool and a workload identity pool provider. You need only perform these steps once for each trust store. You can then use the same workload identity pool and provider for multiple workloads and across multiple Google Cloud projects.

Create the workload identity pool

1. To create a new workload identity pool, execute the following command:

   gcloud iam workload-identity-pools create POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   Replace the following:

   • POOL_ID: the unique ID for the pool.
   • DISPLAY_NAME: the name of the pool.
   • DESCRIPTION: a description of the pool that you choose. This description appears when you grant access to pool identities.

Create the workload identity pool provider

1. To add an X.509 workload identity pool provider, run the following command:

   gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
       --location=global \
       --workload-identity-pool="POOL_ID" \
       --trust-store-config-path="TRUST_STORE_CONFIG" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
       --billing-project="ALLOWLISTED_PROJECT"
   

   Replace the following:

   • PROVIDER_ID: A unique workload identity pool provider ID of your choice.
   • POOL_ID: The workload identity pool ID that you created earlier.
   • TRUST_STORE_CONFIG: The trust store YAML file.
   • MAPPINGS: A comma-separated list of attribute mappings that you created earlier in this guide. For example, google.subject=assertion.subject.dn.cn.
   • CONDITIONS: Optional. An attribute condition that you created earlier in this guide. Remove the parameter if you don't have an attribute condition.
   • ALLOWLISTED_PROJECT: The project ID.

Authenticate a workload

You must perform these steps once for each workload.

Allow your external workload to access Google Cloud resources

To provide your workload with access to Google Cloud resources, we recommend that you grant direct resource access to the principal. In this case, the principal is the federated user. Some Google Cloud products have Google Cloud API limitations. If your workload calls an API endpoint that has a limitation, you can instead use service account impersonation. In this case, the principal is the Google Cloud service account, which acts as the identity. You grant access to the service account on the resource.

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

Obtain an access token using plain request to access Google Cloud

Create the trust bundle

This step shows you how to create the trust bundle. You pass the trust bundle in the subject_token field when calling Security Token Service in plain request.

Format the certificates that need to be included in the chain as a JSON-formatted list as specified in RFC 7515. The leaf certificate used for the mTLS handshake must be specified as the first item. Each certificate in the bundle should be a base64-encoded string.

1. Save the leaf certificate and the intermediate certificate to base64-encoded strings.

   export LEAF_CERT=$(openssl x509 -in leaf.cert -out leaf.der -outform DER && cat leaf.der | openssl enc -base64 -A)
   

   export INTERMEDIATE_CERT=$(openssl x509 -in int.cert -out int.der -outform DER && cat int.der | openssl enc -base64 -A)
   

2. Create a JSON-formatted list of strings that can be passed as subject_token in the call to Security Token Service, later in this document

   export TRUST_BUNDLE="[\\\"${LEAF_CERT}\\\", \\\"${INTERMEDIATE_CERT}\\\"]"
   

Obtain access token

To obtain the access token, do the following:

1. Perform token exchange with mTLS and the client certificate:

   curl --key CLIENT_CERT_KEY \
   --cert CLIENT_CERT \
   --request POST 'https://sts.mtls.googleapis.com/v1/token' \
   --header "Content-Type: application/json" \
   --data-raw '{
       "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "audience": "WORKLOAD_IDENTITY_POOL_URI",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "scope": "https://www.googleapis.com/auth/cloud-platform",
       "subject_token": "TRUST_BUNDLE"
   }'
   

   Replace the following:

   • CLIENT_CERT_KEY: the client certificate private key
   • CLIENT_CERT: the client certificate

   • WORKLOAD_IDENTITY_POOL_URI: the URL of the workload identity pool provider in the following format:

     //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

   • TRUST_BUNDLE: The trust bundle needed to verify the leaf certificate, must at least include CLIENT_CERT as the first item. If you followed instructions in Formatting the certificates section, replace TRUST_BUNDLE with '"${TRUST_BUNDLE}"'

2. Use the bearer access token generated in previous step to access Google Cloud resources—for example:

   curl -X GET 'https://storage.googleapis.com/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"
   

Quotas and limits

The following table lists quotas and limits.

What's next

• Read more about Workload Identity Federation.
• Learn about best practices for using Workload Identity Federation.
• See how you can manage workload identity pools and providers.