Google Cloud Workload Identity Federation OIDC Integration

1. Overview

MonoSign acts as the OIDC identity provider that Google Cloud trusts via Workload Identity Federation. A workload authenticates with its own MonoSign client credentials and gets a short-lived Google Cloud token — no service account key file involved. The rest of this page is the exact setup to get that working.

2. Architecture

The diagram below shows two different teams (Team A, Team B) sharing the same MonoSign issuer and the same Google Cloud Workload Identity Pool/Provider, while remaining fully isolated from each other via different service accounts:

Flow summary:

1. The workload calls MonoSign with its own client_id + client_secret using the client_credentials grant type.

2. MonoSign returns a signed OIDC JWT (access_token) representing the workload's identity. The token's sub claim is that client's client_id, and its aud claim is the Google Cloud provider's canonical resource name.

3. The workload sends this JWT to Google STS (sts.googleapis.com/v1/token) and receives a Google "federated token" in exchange.

4. The federated token is used to impersonate the target service account (iamcredentials.googleapis.com ... :generateAccessToken).

5. The resulting service account access token is used to make real Google Cloud API calls.

3. Prerequisites

• Access to IAM & Admin → Workload Identity Federation in the Google Cloud project

• Permission to create new Applications/Clients in MonoSign

• gcloud CLI installed locally (install with brew install --cask google-cloud-sdk) — needed for testing and verification steps

4. Google Cloud Setup

4.1 Create a Workload Identity Pool

IAM & Admin → Workload Identity Federation → Get started → enter a Pool ID/Name (e.g. monofor).

4.2 Add an OIDC Provider

Select OpenID Connect (OIDC) as the provider type.

Click for next step, “Continue” button.

4.3 Attribute Mapping

On the "Configure provider attributes" screen, the required mapping is:

google.subject = assertion.sub

This maps the sub claim from the MonoSign token (in the client_credentials flow, this value equals the client_id) to the google.subject field that Google IAM recognizes.

5. MonoSign Setup

5.1 Create a New Application (OIDC/OpenID)

In the MonoSign admin panel, create a separate Application for each workload/team (Type: OIDC/OpenID).

5.2 Enable the Client Credentials (M2M) Flow

By default, MonoSign applications use the Authorization Code grant type — this requires an interactive human login via browser and is not suitable for an automated, unattended workload scenario.

Under Edit → OIDC/OpenID Settings → Configuration:

5.3 Set the Audience Claim

In the same Configuration tab, set the Audience field to the Google Cloud provider's canonical resource name:

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

6. Grant Access

Authenticating the workload isn't enough — Google Cloud also needs to know what it's allowed to do (authorization). This is done in two steps:

6.1 Create a Service Account

IAM & Admin → Service Accounts → Create Service Account. A dedicated service account per workload/team is recommended (avoid shared/general-purpose SAs).

6.2 Grant a Role to the Service Account

Grant the SA the narrowest possible role(s) it actually needs (least privilege). Example: if it only needs to read project metadata, roles/browser; for a narrower need, create a custom role:

gcloud iam roles create saListOnly \
  --project=PROJECT_ID \
  --title="SA List Only" \
  --permissions="iam.serviceAccounts.list" \
  --stage=GA

6.3 Bind the Federated Identity to the Service Account

From the service account's own Permissions → Grant Access screen (not the project's IAM — the SA's own resource-level IAM policy), map the MonoSign client's sub value to permission to impersonate this SA:

Principal: principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/monofor/subject/CLIENT_ID
Role: Workload Identity User (roles/iam.workloadIdentityUser)

7. Testing

End-to-end verification consists of 4 steps:

7.1 Get a Token from MonoSign

curl -s -X POST https://id.yourdomain.com/openid/token \
  -d grant_type=client_credentials \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET

Note: do not send a scope=openid parameter together with client_credentials — the openid scope requires a "subject" (a user), whereas in client_credentials the subject is the client itself; this can cause an invalid_scope error. Send the request with no scope parameter at all.

7.2 Exchange It for a Federated Token via Google STS

curl -X POST https://sts.googleapis.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "audience": "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/monofor/providers/monofor",
    "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
    "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "https://www.googleapis.com/auth/cloud-platform",
    "subjectTokenType": "urn:ietf:params:oauth:token-type:jwt",
    "subjectToken": "MONOSIGN_ACCESS_TOKEN"
  }'

7.3 Impersonate the Service Account

curl -X POST "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_EMAIL:generateAccessToken" \
  -H "Authorization: Bearer FEDERATED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope": ["https://www.googleapis.com/auth/cloud-platform"]}'

7.4 Make a Real API Call

curl -H "Authorization: Bearer SA_ACCESS_TOKEN" \
  "https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID"

If this returns 200, the chain is working end to end.

8. Multi-Team / Multi-Client Pattern

Don't create a new Google Cloud provider per team. Instead:

• Google Cloud side: keep a single Pool + single Provider.

• MonoSign side: a separate Application/Client per team/workload (its own client_id + client_secret, its own sub value).

• IAM binding: each client's sub value is bound to its own dedicated service account, with its own minimal role.

9. Troubleshooting