For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Exchange the incoming token for a Google Cloud access token at the Google Security Token Service, with Workload Identity Federation.

Attaches to:

Exchange the token that a client sends to the gateway for a Google Cloud access token at the Google Security Token Service (STS), so that Google Cloud APIs authorize each request as the end user.

About

The Google Cloud Security Token Service (STS) implements the RFC 8693 token exchange grant for Workload Identity Federation. You register your identity provider (IdP) as a provider in a workload identity pool. The STS then accepts a JWT that your IdP issued as the subject_token, and returns a short-lived Google Cloud access token for the federated identity in the token’s sub claim.

In this guide, agentgateway performs that exchange for each request to a Google Cloud API. The client sends its usual IdP token, and the Google API receives a Google access token. Google Cloud authorizes the request as the end user’s federated identity, so IAM policies and Cloud Audit Logs reflect the user, not the gateway. No Google service account key is stored in the gateway or the client.

    sequenceDiagram
    participant Client
    participant AGW as agentgateway
    participant STS as Google STS
    participant API as Google Cloud Storage

    Client->>AGW: Request + IdP JWT
    AGW->>STS: POST /v1/token<br/>subject_token=IdP JWT<br/>audience=//iam.googleapis.com/.../providers/PROVIDER
    STS-->>AGW: Federated Google access token
    AGW->>API: Request + Authorization: Bearer Google token
    API-->>AGW: Response, authorized for the federated user
    AGW-->>Client: Response
  

Google Cloud trusts the token because of the workload identity pool provider, not because of the caller. The STS token endpoint does not take client authentication, so the exchange has no client ID or client secret to store.

This exchange differs from Google Cloud backend authentication, where the gateway calls Google Cloud with its own identity, such as a service account. Use token exchange when Google Cloud must authorize each request as the user who sent it.

Google STS settings

The Google STS uses the standard RFC 8693 grant, so you configure it with the generic oauthTokenExchange method. The following settings are specific to Google.

Before you begin

1. Install the agentgateway binary.
2. Install Docker to run the sample identity provider.
3. Install the gcloud CLI and log in to a Google Cloud project where you can create workload identity pools and Cloud Storage buckets, such as with the roles/iam.workloadIdentityPoolAdmin and roles/storage.admin roles.
4. Install jq.

Step 1: Run a sample identity provider

Run Keycloak as the identity provider that issues the incoming token. The realm in this example has a confidential client, agent, that adds the audience agentgateway to its tokens, and a user, testuser, with the password testpass.

Google requires the issuer to be an https:// URL. Keycloak in this example runs on plain HTTP on your machine, so the KC_HOSTNAME variable pins the issuer to https://keycloak.example.com. Google never contacts this host, because you upload the realm’s signing keys to Google instead. In production, use your own IdP and its real issuer URL.

1. Save the realm definition to a file.

   cat > agentgateway-realm.json <<'EOF'
   {
     "realm": "agentgateway",
     "enabled": true,
     "clients": [
       {
         "clientId": "agent",
         "secret": "agent-secret",
         "publicClient": false,
         "standardFlowEnabled": false,
         "directAccessGrantsEnabled": true,
         "protocolMappers": [
           {
             "name": "google-audience",
             "protocol": "openid-connect",
             "protocolMapper": "oidc-audience-mapper",
             "config": {
               "included.custom.audience": "agentgateway",
               "access.token.claim": "true"
             }
           }
         ]
       }
     ],
     "users": [
       {
         "username": "testuser",
         "enabled": true,
         "email": "[email protected]",
         "emailVerified": true,
         "firstName": "Test",
         "lastName": "User",
         "credentials": [{"type": "password", "value": "testpass", "temporary": false}]
       }
     ]
   }
   EOF

2. Run Keycloak with the realm on port 7080.

   docker run -d --name keycloak -p 7080:8080 \
     -v "$PWD/agentgateway-realm.json:/opt/keycloak/data/import/agentgateway-realm.json:ro" \
     -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
     -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
     -e KC_HOSTNAME=https://keycloak.example.com \
     quay.io/keycloak/keycloak:26.7.1 \
     start-dev --import-realm --http-port=8080

3. Wait for the realm to be served.

   until curl -sf http://localhost:7080/realms/agentgateway/.well-known/openid-configuration > /dev/null; do sleep 2; done

4. Mint a token for testuser and save it in an environment variable. Keycloak tokens expire after 5 minutes, so mint a new one if you come back to this guide later.

   export INBOUND_TOKEN=$(curl -s http://localhost:7080/realms/agentgateway/protocol/openid-connect/token \
     -u agent:agent-secret -d grant_type=password \
     -d username=testuser -d password=testpass | jq -r .access_token)

5. Decode the token’s payload and save its sub claim. Google uses this claim as the identity of the federated user.

   echo "$INBOUND_TOKEN" | cut -d. -f2 | jq -R 'gsub("-";"+") | gsub("_";"/") | . + ("=" * ((4 - (length % 4)) % 4)) | @base64d | fromjson | {iss, aud, sub}'
   export USER_SUB=$(echo "$INBOUND_TOKEN" | cut -d. -f2 | jq -rR 'gsub("-";"+") | gsub("_";"/") | . + ("=" * ((4 - (length % 4)) % 4)) | @base64d | fromjson | .sub')

   Example output:

   {
     "iss": "https://keycloak.example.com/realms/agentgateway",
     "aud": "agentgateway",
     "sub": "c4bfb640-7fa6-4dcc-a742-190df95dc030"
   }

6. Save the realm’s signing keys to a file, to upload to Google in the next step. The jq filter keeps the signing keys and drops the encryption key.

   curl -s http://localhost:7080/realms/agentgateway/protocol/openid-connect/certs \
     | jq '{keys: [.keys[] | select(.use == "sig")]}' > jwks.json

   Keycloak in this example keeps its keys in memory. If you restart the container, it generates new keys, and you must upload the new jwks.json file to the provider with gcloud iam workload-identity-pools providers update-oidc.

Step 2: Set up Workload Identity Federation

Register Keycloak as an identity provider in a Google Cloud workload identity pool, and give its user access to a Cloud Storage bucket.

1. Set environment variables for your Google Cloud project and the resources that you create. Bucket names are globally unique, so the bucket name includes your project ID.

   export PROJECT_ID=<your-project-id>
   export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
   export POOL_ID=agentgateway-pool
   export PROVIDER_ID=keycloak
   export BUCKET=agentgateway-te-$PROJECT_ID

2. Enable the APIs that Workload Identity Federation and Cloud Storage use.

   gcloud services enable iam.googleapis.com sts.googleapis.com storage.googleapis.com \
     --project $PROJECT_ID

3. Create a workload identity pool.

   gcloud iam workload-identity-pools create $POOL_ID \
     --project $PROJECT_ID \
     --location global \
     --display-name "agentgateway token exchange"

4. Create an OIDC provider in the pool for the Keycloak realm.

   gcloud iam workload-identity-pools providers create-oidc $PROVIDER_ID \
     --project $PROJECT_ID \
     --location global \
     --workload-identity-pool $POOL_ID \
     --issuer-uri "https://keycloak.example.com/realms/agentgateway" \
     --allowed-audiences agentgateway \
     --attribute-mapping "google.subject=assertion.sub" \
     --jwk-json-path jwks.json

   Setting	Description
   --issuer-uri	Must match the iss claim of the incoming token exactly. Google requires an https:// issuer.
   --allowed-audiences	The aud values that Google accepts in the incoming token. The sample realm sets aud to agentgateway. If you omit this flag, the token’s aud must be the full provider resource name, https://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID.
   --attribute-mapping	Maps the token’s sub claim to the Google subject. IAM policies refer to the federated user by this value.
   --jwk-json-path	Uploads the signing keys that you saved earlier, so Google validates tokens without contacting the issuer. For an IdP with a public https:// discovery endpoint, omit this flag and Google fetches the keys itself.

5. Create a bucket with a sample object.

   gcloud storage buckets create gs://$BUCKET --project $PROJECT_ID --location us-central1
   echo "hello from agentgateway" > hello.txt
   gcloud storage cp hello.txt gs://$BUCKET/hello.txt

6. Grant the Keycloak user read access to the bucket. The member is the federated identity of testuser: the workload identity pool plus the sub claim that you saved earlier. Use the project number, not the project ID.

   gcloud storage buckets add-iam-policy-binding gs://$BUCKET \
     --member "principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/subject/$USER_SUB" \
     --role roles/storage.objectViewer

   IAM changes can take a few minutes to take effect.

Step 3: Configure token exchange

1. Create a configuration file. The route forwards requests to the Cloud Storage API, and the oauthTokenExchange policy on the backend exchanges the incoming token at the Google STS first. The shell fills in your project number, pool ID, and provider ID.

   cat > config.yaml <<EOF
   # yaml-language-server: \$schema=https://agentgateway.dev/schema/config
   gateways:
     default:
       port: 3000
   routes:
   - name: google-storage
     backends:
     - host: storage.googleapis.com:443
       policies:
         backendTLS: {}
         backendAuth:
           oauthTokenExchange:
             host: sts.googleapis.com:443
             path: /v1/token
             policies:
               backendTLS: {}
             subjectToken:
               tokenType: urn:ietf:params:oauth:token-type:jwt
             requestedTokenType: urn:ietf:params:oauth:token-type:access_token
             audiences:
             - //iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID
             scopes:
             - https://www.googleapis.com/auth/cloud-platform
   EOF

   For a description of each setting, see Google STS settings.

2. In a second terminal, change to the directory that has the config.yaml file, and run agentgateway with the configuration. Keep the first terminal for the curl commands, so that the INBOUND_TOKEN, USER_SUB, and BUCKET variables stay available there.

   agentgateway -f config.yaml

Step 4: Verify the exchange

1. In the first terminal, mint a new token for testuser. The token from Step 1 has likely expired, because Keycloak tokens expire after 5 minutes. The sub claim of the new token is the same, so the IAM binding from Step 2 still applies.

   export INBOUND_TOKEN=$(curl -s http://localhost:7080/realms/agentgateway/protocol/openid-connect/token \
     -u agent:agent-secret -d grant_type=password \
     -d username=testuser -d password=testpass | jq -r .access_token)

2. List the objects in the bucket through the gateway, with the Keycloak token. The gateway exchanges the Keycloak token at the Google STS, and forwards the request to Cloud Storage with the Google access token.

   curl -s http://localhost:3000/storage/v1/b/$BUCKET/o \
     -H "authorization: Bearer $INBOUND_TOKEN"

   Cloud Storage authorizes the request as the federated testuser identity, and returns the objects in the bucket.

   {
     "kind": "storage#objects",
     "items": [
       {
         "kind": "storage#object",
         "name": "hello.txt",
         "bucket": "agentgateway-te-my-project",
         ...
       }
     ]
   }

3. Send a request without a token. The gateway has no subject token to exchange, so it rejects the request with a 400 response and does not call the STS.

   curl -s -w " %{http_code}\n" http://localhost:3000/storage/v1/b/$BUCKET/o

   Example output:

   invalid request 400

The exchange does not validate the incoming token itself; Google does. To reject an invalid or expired token at the gateway before it calls the STS, add a JWT authentication policy to the route. Set preserveToken: true on that policy, so that the token is still in the request when the exchange runs.

Troubleshooting

When the exchange fails, the gateway returns 400 with the body invalid request. The response from the STS is logged at debug level. To see it, run agentgateway with the RUST_LOG=info,agentgateway::http::auth::oauth=debug environment variable, and look for oauth token exchange rejected by authorization server in the output.

If the exchange succeeds but Cloud Storage returns 403, the federated identity has no access to the bucket. Check that the IAM binding uses the project number and the sub claim of the token, and allow a few minutes for IAM changes to take effect.

Cleanup

1. Stop agentgateway with Ctrl+C in its terminal, and remove the Keycloak container.

   docker rm -f keycloak

2. Delete the Google Cloud resources.

   gcloud storage rm --recursive gs://$BUCKET
   gcloud iam workload-identity-pools delete $POOL_ID --project $PROJECT_ID --location global --quiet

   A deleted pool stays in a soft-deleted state for 30 days, and its ID cannot be reused during that time. To reuse the ID, restore the pool with gcloud iam workload-identity-pools undelete.