Configure managed workload identity authentication

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

For information about access to this release, see the access request page.

This page explains how to configure managed workload identities using the gcloud CLI.

This page also describes how to set up automatic provisioning and lifecycle management of managed workload identities for Compute Engine. You configure certificate authority (CA) pools to issue certificates using Certificate Authority Service. CA Service is a highly-available, scalable Google Cloud service that simplifies and automates the deployment, management, and security of CA services. You can create virtual machine instances (VMs) that are provisioned with X.509 credentials from the configured CA pool. These credentials can then be used to establish mTLS connections between workloads.

Before you begin

1. Create or select a Google Cloud project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

2. Request access to the managed workload identities Preview.

   Important: You must wait until you receive a confirmation that your project has been added to the allowlist before moving on to the next steps.

3. Understand managed workload identities.

4. Learn about certificate issuance using Certificate Authority Service.

5. Learn how to authenticate Compute Engine workloads using managed workload identities.

6. Enable the IAM and Certificate Authority Service APIs:

   gcloud services enable iam.googleapis.com privateca.googleapis.com

7. Configure Google Cloud CLI to use the project that was added to the allowlist for billing and quota.

   gcloud config set billing/quota_project PROJECT_ID
   

   Replace PROJECT_ID with the ID of the project that was added to the allowlist for the managed workload identity preview.

Required roles

To get the permissions that you need to create managed workload identities and provision managed workload identity certificates, ask your administrator to grant you the following IAM roles on the project:

• To create and configure managed workload identities:
  • IAM Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin)
  • Service Account Admin (roles/iam.serviceAccountAdmin)
• To create and configure CA pools: CA Service Admin (roles/privateca.admin)

For more information about granting roles, see Manage access.

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 managed workload identities. You should not grant basic roles in a production environment, but you can grant them in a development or test environment.

Overview

To use managed workload identities for your applications, you must perform the following tasks:

1. Security Administrator:

   • Create managed workload identities in a workload identity pool.
   • Define the workload attestation policy and create a service account.
   • Configure Certificate Authority Service to issue certificates for managed workload identities.
   • Authorize managed workload identities to request certificates from the CA pool.
   • Define the trust and certificate issuance config.
   • Create a configuration file to upload the partner metadata for a VM.

2. Compute Administrator:

   Enable managed workload identities for workloads running in Compute Engine:

   • For individuals VMs.
   • For managed-instance groups (MIGs).

Create managed workload identities

Managed workload identities enables Google Cloud to automatically provision credentials for workload identity pool identities onto your workloads. Workload identities are defined within a workload identity pool, and are organized into administrative boundaries called namespaces.

Create a workload identity pool

You must create a pool in TRUST_DOMAIN mode to create managed workload identities. To create a workload identity pool for managed workload identities, use the workload-identity-pools create command.

gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --mode="TRUST_DOMAIN"

Replace the following:

• POOL_ID: the unique ID for the pool. The ID must be between 4 and 32 characters, and can contain only lowercase alphanumeric characters and dashes, and start and end with an alphanumeric character. After you create a workload identity pool, you can't change its ID.

To verify that your workload identity pool was created in TRUST_DOMAIN mode, use the workload-identity-pools describe command.

gcloud iam workload-identity-pools describe POOL_ID \
    --location="global"

The command output should look similar to the following:

mode: TRUST_DOMAIN
name: projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID
state: ACTIVE

If mode: TRUST_DOMAIN is not present in the command output, verify that your project has been added to the allowlist for the managed workload identity Preview and that you've correctly configured your gcloud CLI to use the correct project for billing and quota. You might need to update to a newer version of the gcloud CLI.

Create a namespace

The workload-identity-pools namespaces create command lets you create a namespace in a workload identity pool.

gcloud iam workload-identity-pools namespaces create NAMESPACE_ID \
    --workload-identity-pool="POOL_ID" \
    --location="global"

Replace the following:

• NAMESPACE_ID: the unique ID for the namespace. The ID must be between 2 and 63 characters, contain only lowercase alphanumeric characters and dashes, and start and end with an alphanumeric character. After you create a namespace, you cannot change its ID.
• POOL_ID: the workload identity pool ID that you created earlier.

Create a managed workload identity

The workload-identity-pools managed-identities create command lets you create a managed workload identity in a workload identity pool.

gcloud iam workload-identity-pools managed-identities create MANAGED_IDENTITY_ID \
    --namespace="NAMESPACE_ID" \
    --workload-identity-pool="POOL_ID" \
    --location="global"

Replace the following:

• MANAGED_IDENTITY_ID: the unique ID for the managed identity. The ID must be between 2 and 63 characters, contain only lowercase alphanumeric characters and dashes, and start and end with an alphanumeric character. After you create a managed workload identity, you cannot change its ID.
• NAMESPACE_ID: the namespace ID that you created earlier.
• POOL_ID: the workload identity pool ID that you created earlier.

The SPIFFE identity for your managed workload identity is equal to the following:

spiffe://POOL_ID.global.PROJECT_NUMBER.workload.id.goog/ns/NAMESPACE_ID/sa/MANAGED_IDENTITY_ID

Define the workload attestation policy

A workload attestation policy ensures that only trusted workloads can use the managed identity. You must allow your workload to use the managed workload identity before it can be issued credentials.

To do this, you create a user-managed service account and attach it to your workload. Your workload will use the managed workload identity as its identity when it authenticates to other workloads using mutual TLS (mTLS), and your workload will use the service account as its identity when it accesses other Google Cloud services and resources.

The service-accounts create command lets you create a managed workload identity in a workload identity pool.

To create the attached service account, run the following command:

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

Replace the following:

• SERVICE_ACCOUNT_NAME: the name of the service account

To create a workload attestation policy that allows your workloads with the service account attached to be issued credentials for the managed workload identity, use the workload-identity-pools managed-identities workload-sources create command:

gcloud iam workload-identity-pools managed-identities workload-sources create \
    project-WORKLOAD_PROJECT_NUMBER \
    --single-attribute-selectors "compute.googleapis.com/Instance.attached_service_account.email=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --managed-identity MANAGED_IDENTITY_ID \
    --namespace NAMESPACE_ID \
    --workload-identity-pool POOL_ID \
    --location "global"

Replace the following:

• SERVICE_ACCOUNT_NAME: the name of the service account.
• WORKLOAD_PROJECT_NUMBER: the project number for the project that contains your workload. The policy allows workloads within this project to use the managed workload identity.
• PROJECT_ID: the ID of the project containing the service account.
• MANAGED_IDENTITY_ID: the unique ID for the managed identity.
• NAMESPACE_ID: the namespace ID that you created. earlier.
• POOL_ID: the workload identity pool ID that you created earlier.

For a given workload identity pool, you can define a maximum of 50 single attribute selectors for your workload project.

To learn about how to update or delete an attestation policy, run the following command:

gcloud iam workload-identity-pools managed-identities workload-sources --help

Configure Certificate Authority Service to issue certificates for managed workload identities

Create the recommended set up for root and subordinate certificate authorities (CAs) using Certificate Authority Service pools. The subordinate CA pool issues the X.509 workload identity certificates to VMs.

Note: The CA pools configured to issue certificates for Compute Engine VMs using managed workload identities must reside in the same region as the VM. If you want to design a multi-region architecture for resilience to regional outages, we recommend that you configure a subordinate Certificate Authority Service CA pool for each of your workload's regions, so that each of your Compute Engine VMs can reference an in-region subordinate Certificate Authority Service CA pool.

After configuring the CA pools, you then authorize the managed workload identities to request and receive the signed certificates from the CA pools.

Configure the root CA pool

Use the Google Cloud CLI interface to Certificate Authority Service to configure a root CA pool.

Note: You cannot move or export a CA pool after it has been created.

gcloud

Create the root CA pool.

1. Create the root CA pool in the Enterprise tier, which is meant for long-lived, low-volume certificate issuance using the gcloud privateca pools create command.

   gcloud privateca pools create ROOT_CA_POOL_ID \
      --location=REGION \
      --tier=enterprise
   

   Replace the following:

   • ROOT_CA_POOL_ID: a unique ID for the root CA pool. The ID can be up to 64 characters in length and must contain only lower and uppercase alphanumeric characters, underscores, or hyphens. The pool ID must be unique within the region.
   • REGION: the region where the root CA pool is located.

   For more information, see Creating CA pools.

2. Create a root CA in the root CA pool using the gcloud privateca roots create command. You might be prompted to enable the root CA if this is the only CA in the root CA Pool.

   For example, you might use a command similar to the following to create a root CA.

   gcloud privateca roots create ROOT_CA_ID \
      --pool=ROOT_CA_POOL_ID \
      --subject "CN=ROOT_CA_CN, O=ROOT_CA_ORGANIZATION" \
      --key-algorithm="ec-p256-sha256" \
      --max-chain-length=1 \
      --location=REGION
   

   Replace the following:

   • ROOT_CA_ID: a unique name for the root CA. The CA name can be up to 64 characters in length and must contain only lower and uppercase alphanumeric characters, underscores, or hyphens. The CA name must be unique within the region.
   • ROOT_CA_POOL_ID: the ID of the root CA pool.
   • ROOT_CA_CN: the common name of the root CA.
   • ROOT_CA_ORGANIZATION: the organization of the root CA.
   • REGION: the region where the root CA pool is located.

   For more information, see Create a root certificate authority. For more information about the subject fields for the CA, see Subject.

3. Optional: Repeat the previous steps to create an additional root CA in the root CA pool. This can be useful for root CA rotation.

Configure the subordinate CAs

Use the Google Cloud CLI interface to Certificate Authority Service to create a subordinate CA pool and subordinate CA.

If you have multiple certificate issuance scenarios, you can create a subordinate CA for each of those scenarios. Also, adding multiple subordinate CAs in a CA pool helps you achieve better load-balancing of certificate requests.

gcloud

Use the gcloud privateca pools create command to create a subordinate CA pool.

1. Create the subordinate CA pool in the DevOps tier, which is meant for high volume, short-lived certificate issuance .

   gcloud privateca pools create SUBORDINATE_CA_POOL_ID \
      --location=REGION \
      --tier=devops
   

   Replace the following:

   • SUBORDINATE_CA_POOL_ID: a unique ID for the subordinate CA pool. The ID can be up to 64 characters in length and must contain only lowercase and uppercase alphanumeric characters, underscores, or hyphens. The pool ID must be unique within the region.
   • REGION: the region in which to create the subordinate CA pool.

   For more information, see Creating CA pools.

2. Create a subordinate CA in the subordinate CA pool using the gcloud privateca subordinates create command. Don't change the default config-based issuance mode.

   For example, you might use a command similar to the following to create a subordinate CA.

   gcloud privateca subordinates create SUBORDINATE_CA_ID \
      --pool=SUBORDINATE_CA_POOL_ID \
      --location=REGION \
      --issuer-pool=ROOT_CA_POOL_ID \
      --issuer-location=REGION \
      --subject="CN=SUBORDINATE_CA_CN, O=SUBORDINATE_CA_ORGANIZATION" \
      --key-algorithm="ec-p256-sha256" \
      --use-preset-profile=subordinate_mtls_pathlen_0
   

   Replace the following:

   • SUBORDINATE_CA_ID: a unique name for the subordinate CA. The name can be up to 64 characters in length and must contain only lowercase and uppercase alphanumeric characters, underscores, or hyphens. The pool name must be unique within the region.
   • SUBORDINATE_CA_POOL_ID: the name of the subordinate CA pool.
   • REGION: the region where the subordinate CA pool is located.
   • ROOT_CA_POOL_ID: the ID of the root CA pool.
   • REGION: the region of the root CA pool.
   • SUBORDINATE_CA_CN: the common name of the subordinate CA.
   • SUBORDINATE_CA_ORGANIZATION: the name of the subordinate CA issuing organization.

   For more information, see Creating CA pools. For more information about the subject fields for the CA, see Subject.

Authorize managed workload identities to request certificates from the CA pool

The managed workload identities require permissions to request certificates from the CA Service and get the public certificates.

gcloud

1. Grant the CA Service Workload Certificate Requester (roles/privateca.workloadCertificateRequester) IAM role on each subordinate CA pool to the managed workload identity. The following gcloud privateca pools add-iam-policy-binding command authorizes the managed workload identity to request certificates from the CA Service certificate chains.

   gcloud privateca pools add-iam-policy-binding SUBORDINATE_CA_POOL_ID \
    --location=REGION \
    --role=roles/privateca.workloadCertificateRequester \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*"
   

   Replace the following:

   • SUBORDINATE_CA_POOL_ID: the ID for the subordinate CA pool.
   • REGION: the region of the subordinate CA pool.
   • PROJECT_NUMBER: the project number of the project that contains the workload identity pool.
   • POOL_ID: the ID of the workload identity pool.

2. Grant the CA Service Pool Reader (roles/privateca.poolReader) IAM role on the subordinate CA pools to the managed workload identity. This authorizes the managed workload identity to get the signed X.509 certificates from the CA's certificate chains.

   gcloud privateca pools add-iam-policy-binding SUBORDINATE_CA_POOL_ID \
    --location=REGION \
    --role=roles/privateca.poolReader \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*"
   

   Replace the following:

   • SUBORDINATE_CA_POOL_ID: the ID for the subordinate CA pool.
   • REGION: the region of the subordinate CA pool.
   • PROJECT_NUMBER: the project number of the project that contains the workload identity pool.
   • POOL_ID: the ID of the workload identity pool.

Define the trust and certificate issuance config

You use this information to create a JSON file that is uploaded as partner data when creating a VM.

Define the certificate issuance config

The following certificate issuance config is required to enable managed workload identities for Compute Engine.

{
  "primary_certificate_authority_config": {
    "certificate_authority_config": {
      "ca_pool": "projects/PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID"
    }
  },
  "key_algorithm": "ALGORITHM",
  "workload_certificate_lifetime_seconds": "DURATION",
  "rotation_window_percentage": "ROTATION_WINDOW_PERCENTAGE"
}

Replace the following:

• PROJECT_NAME: the name of the project that contains the CA pool
• REGION: the region where the subordinate CA pool is located
• SUBORDINATE_CA_POOL_ID: the name of the subordinate CA pool
• ALGORITHM: the encryption algorithm used to generate the private key. Valid values are rsa-2048 (default), rsa-3072, rsa-4096, ecdsa-p256 and ecdsa-p384.
• DURATION: Optional: The leaf certificate validity duration, in seconds. The value must be between 3600 and 315360000. If not specified, the default value of 86400 is used. The actually validity of the issued certificate also depends on the issuing CA, because it may restrict the lifetime of the issued certificate.
• ROTATION_WINDOW_PERCENTAGE: Optional: The percentage of the certificate's lifetime at which a renewal triggers. Value must be between 1 and 100. The default value is 66 percent. You must set the rotation window percentage in relation to the certificate lifetime so that certificate renewal occurs at least 7 days after the certificate has been issued and at least 7 days before it expires.

Define the trust config

The trust config contains the set of trust anchors for validating peer certificates. This includes the following:

• Trusted CA pool resource URIs: A set of CA pool resource URIs that are trusted to issue certificates in the same trust domain as the VMs belongs to.
• PEM formatted CA certificates: A set of PEM-formatted CA certificates trusted to issue certificates in the same trust domain as the VMs belongs to.

Note: The trust config must contain an entry for the SPIFFE trust domain POOL_ID.global.PROJECT_NUMBER.workload.id.goog, which corresponds to the SPIFFE trust domain of managed identity assigned to the VM. Not specifying this would result in provisioning failure of workload certificates.

{
  "POOL_ID.global.PROJECT_NUMBER.workload.id.goog": {
    "trust_anchors": [
      {
        "ca_pool": "projects/PROJECT_NAME/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID"
      },
      {
        "pem_certificate": "PEM-encoded certificate"
      }
    ]
  }
}

Replace the following:

• POOL_ID: the ID of the workload identity pool
• PROJECT_NUMBER: the project number of the project that that contains the workload identity pool
• PROJECT_NAME: the name of the project that contains the CA pool
• REGION: the region where the subordinate CA pool is located
• SUBORDINATE_CA_POOL_ID: the ID of the subordinate CA pool
• PEM-encoded certificate: Optional: a set of PEM-formatted CA certificates trusted to issue certificates in the same trust domain that the VMs belongs to

Create a configuration file to upload the partner metadata for a VM

Create a JSON file that contains the following:

• The configuration for the workload identity
• The information from Define the certificate issuance config
• The information from Define the trust config

Save this file as CONFIGS.json. This file is used when creating VMs to run applications that use managed workload identities.

Note: The format of the JSON and the values provided must be valid. The VM creation will fail if the file provides invalid input.

Your CONFIGS.json file should be similar to the following:

  {
  "wc.compute.googleapis.com": {
     "entries": {
        "certificate-issuance-config": {
           "primary_certificate_authority_config": {
              "certificate_authority_config": {
                 "ca_pool": "projects/PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID"
              }
           },
           "key_algorithm": "ALGORITHM"
        },
        "trust-config": {
           "POOL_ID.global.PROJECT_NUMBER.workload.id.goog": {
               "trust_anchors": [{
                  "ca_pool": "projects/PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID"
                }]
           }
     }
  }
  },
  "iam.googleapis.com": {
     "entries": {
        "workload-identity": "spiffe://POOL_ID.global.PROJECT_NUMBER.workload.id.goog/ns/NAMESPACE_ID/sa/MANAGED_IDENTITY_ID"
     }
  }
  }
  

What's next

• Configure workload to workload authentication using mTLS.
• Learn more about creating CA pools.

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Get started for free