How to replace JSON key with X.509 WiF

This short guide provides step by step instructions how to replace a JSON key with a Workload Identity Federation (WiF) X.509 certificate.

Prerequisites

openssl 3.x
Node.js with npm
gcloud authenticated as an administrator of the target project

The examples use the project ID my-project and the project number 123456789012. Replace them with your own values.

1. Create the certificates

The script creates a root CA, an issuing CA and a client certificate. The client certificate subject CN (test-client) becomes the WiF subject.

# Root CA certificate
echo "Generating Root CA certificate..."
openssl req \
    -x509 \
    -newkey rsa:4096 \
    -keyout ca_key.pem \
    -out ca_cert.pem \
    -days 3650 \
    -noenc \
    -subj "/CN=Test CA $(date +"%Y-%m-%d")" \
    -addext "basicConstraints=critical,CA:TRUE,pathlen:1" \
    -addext "keyUsage=critical,keyCertSign,cRLSign"

# Issuing CA certificate
echo "Generating Issuing CA certificate..."
openssl req \
    -newkey rsa:4096 \
    -keyout issuing_ca_key.pem \
    -noenc \
    -subj "/CN=Issuing Test CA $(date +"%Y-%m-%d")" \
    -addext "basicConstraints=critical,CA:TRUE,pathlen:0" \
    -addext "keyUsage=critical,keyCertSign,cRLSign" |
    openssl x509 \
        -req \
        -CA ca_cert.pem \
        -CAkey ca_key.pem \
        -copy_extensions copyall \
        -days 3650 \
        -out issuing_ca_cert.pem

# Client certificate
echo "Generating Client certificate..."
openssl req \
    -newkey rsa:4096 \
    -keyout client_key.pem \
    -noenc \
    -subj "/CN=test-client" \
    -addext "basicConstraints=critical,CA:FALSE" \
    -addext "keyUsage=critical,digitalSignature,keyEncipherment" \
    -addext "extendedKeyUsage=clientAuth" |
    openssl x509 \
        -req \
        -CA issuing_ca_cert.pem \
        -CAkey issuing_ca_key.pem \
        -copy_extensions copyall \
        -days 365 \
        -out client_cert.pem

2. Create the trust store

The trust store is a YAML file that holds the root CA as the trust anchor and the issuing CA as an intermediate CA. The generator uses the yaml npm package.

package.json:

{
  "dependencies": {
    "yaml": ">=2.9.1"
  }
}

make_trust_store.mjs:

#!/usr/bin/env node
import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { parseArgs } from "node:util";
import YAML from "yaml";

const { values } = parseArgs({
  options: {
    "ca-cert": { type: "string", default: "ca_cert.pem" },
    "issuing-ca-cert": { type: "string", default: "issuing_ca_cert.pem" },
    output: { type: "string", default: "trust_store.yaml" },
  },
});

// IMPORTANT: Strip the trailing newline from the PEM files,
// otherwise gcloud will reject the trust store with a cryptic error message.
const trustStore = {
  trustAnchors: [{ pemCertificate: readFileSync(values["ca-cert"], "utf8").trimEnd() }],
};

// The issuing CA is optional; it is included only when its file exists.
if (existsSync(values["issuing-ca-cert"])) {
  trustStore.intermediateCas = [
    { pemCertificate: readFileSync(values["issuing-ca-cert"], "utf8").trimEnd() },
  ];
}

writeFileSync(values.output, YAML.stringify({ trustStore }, { indentSeq: false }));

Install the dependency and generate trust_store.yaml:

npm install
node make_trust_store.mjs

The PEM files must contain only the certificate block. A trailing newline after -----END CERTIFICATE----- makes gcloud fail with Certificate is not in PEM format, which is why the script trims it.

3. Create the pool, provider and credentials

The script creates the workload identity pool, the X.509 provider and a service account. It allows the client certificate subject to impersonate the service account, grants the service account read access to the project, creates a storage bucket with read and write access to its objects for the service account, enables Data Access audit logs for Cloud Storage, and writes cred.json. It then logs in with cred.json in a separate gcloud configuration, checks the access, uploads and downloads a file, and lists the audit log of the service account operations.

Data Access audit logs are enabled for the whole project, not per bucket, by editing the project IAM policy. add_audit_config.mjs adds the auditConfigs section to the policy file fetched by gcloud. The policy must be fetched as YAML, because a different default gcloud output format makes set-iam-policy reject the file.

add_audit_config.mjs:

#!/usr/bin/env node
import { readFileSync, writeFileSync } from "node:fs";
import YAML from "yaml";

const policy = YAML.parse(readFileSync("iam_policy.yaml", "utf8"));

// Replace the Cloud Storage entry, if any, and keep the other audit configs.
policy.auditConfigs = (policy.auditConfigs ?? []).filter(
  (c) => c.service !== "storage.googleapis.com",
);
policy.auditConfigs.push({
  service: "storage.googleapis.com",
  auditLogConfigs: [{ logType: "DATA_READ" }, { logType: "DATA_WRITE" }],
});

writeFileSync("iam_policy.yaml", YAML.stringify(policy, { indentSeq: false }));

make_wif.sh:

# Create a workload identity pool and a X.509 provider
gcloud iam workload-identity-pools create my-pool \
  --project=my-project \
  --location=global \
  --display-name="My Pool"

# Create X.509 provider
gcloud iam workload-identity-pools providers create-x509 my-x509 \
  --project=my-project \
  --location=global \
  --workload-identity-pool=my-pool \
  --trust-store-config-path=trust_store.yaml \
  --attribute-mapping="google.subject=assertion.subject.dn.cn"

# Create the service account
gcloud iam service-accounts create sa-test \
  --project=my-project \
  --display-name="SA Test"

# Allow impersonation of the service account
gcloud iam service-accounts add-iam-policy-binding \
    sa-test@my-project.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/my-pool/subject/test-client"

# Grant the service account read access to the project
gcloud projects add-iam-policy-binding my-project \
    --member="serviceAccount:sa-test@my-project.iam.gserviceaccount.com" \
    --role=roles/browser

# Create credentials configuration files
gcloud iam workload-identity-pools create-cred-config \
    projects/123456789012/locations/global/workloadIdentityPools/my-pool/providers/my-x509 \
    --service-account=sa-test@my-project.iam.gserviceaccount.com \
    --credential-cert-path=client_cert.pem \
    --credential-cert-private-key-path=client_key.pem \
    --output-file=cred.json

# Create a storage bucket
gcloud storage buckets create gs://my-project-wif-test \
    --project=my-project \
    --location=europe-central2 \
    --uniform-bucket-level-access

# Allow the service account to read and write objects in the bucket
gcloud storage buckets add-iam-policy-binding gs://my-project-wif-test \
    --member="serviceAccount:sa-test@my-project.iam.gserviceaccount.com" \
    --role=roles/storage.objectUser

# Enable Data Access audit logs for Cloud Storage (project-wide, not per bucket)
gcloud projects get-iam-policy my-project --format=yaml > iam_policy.yaml
node add_audit_config.mjs
gcloud projects set-iam-policy my-project iam_policy.yaml

# Create a new gcloud configuration for the workload identity federation test
gcloud config configurations create wif-test

# Authenticate gcloud with the credentials configuration file
gcloud auth login --cred-file=cred.json

# Set the project to my-project
gcloud config set project my-project

# Test the authentication by listing the project details
gcloud auth list
gcloud projects describe my-project
gcloud projects get-iam-policy my-project \
    --flatten="bindings[].members" \
    --format="table(bindings.role, bindings.members)"

# Test the bucket access by uploading and downloading a file
gcloud storage ls gs://my-project-wif-test
gcloud storage cp README.md gs://my-project-wif-test/README.md
gcloud storage ls gs://my-project-wif-test
gcloud storage cp gs://my-project-wif-test/README.md README.downloaded.md
cmp README.md README.downloaded.md

# Then, switch back to your original account
gcloud config configurations activate default

# List the audit log of the operations made by the service account
gcloud logging read \
    'protoPayload.authenticationInfo.principalEmail="sa-test@my-project.iam.gserviceaccount.com"' \
    --project=my-project \
    --freshness=1h \
    --order=asc \
    --format="table(timestamp, protoPayload.serviceName, protoPayload.methodName)"

# and again switch back to the service account
gcloud config configurations activate wif-test

The audit log lists only Cloud Storage operations of the service account. Resource Manager calls such as projects describe are not covered by the Data Access configuration.

Result

cred.json is a credentials configuration file that references the client certificate and private key. It contains no secret itself, but client_key.pem does and must be protected like a JSON key.

8.9 KiB Raw Blame History