Repository navigation
feat: Enable Bound Token for Agentic Identities - #13873
Merged
macastelaz merged 41 commits intoOct 3, 2026
Merged
macastelaz merged 41 commits into
macastelaz merged 41 commits into
Conversation
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR introduces a feature which enables the auth library to acquire bound access-tokens and bound id-tokens in Agentic Environments.
We detect certs in default paths and check if they match the SPIFFE format for agents.
If 1. is a yes then we call the MDS endpoint in a POST request with the certificate in the body.
Note this PR was based on #13169
Manual Testing & End-to-End Verification
We verified this feature end-to-end across both a Live Cloud Run Agent Identity environment (testing against the live Google Metadata Server, Security Token Service, and Vertex AI with the Java Agent Development Kit (
com.google.adk:google-adk:1.9.0)) and a 10-Scenario Local Mock MDS Simulation Harness (testing exact HTTP request payloads, true cryptographic certificate/key rotation, combined bundle private-key stripping, well-known directory discovery, non-agent SPIFFE fallback, environment variable precedence, non-atomic rotation retries, and asynchronous container startup polling).1. Live Cloud Run Agent Identity Verification (
<PROJECT_ID>,us-central1)We deployed a containerized Java test application built against this branch (
google-auth-library-oauth2-http:1.50.0-SNAPSHOT@27776f6d62a) + Java ADK (com.google.adk:google-adk:1.9.0) to Cloud Run with Agent Identity enabled (--functional-type=agent --identity-type=agent-identity).Execution A: Default Bound Token Acquisition (
GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKENunset / defaulttrue)agent-bound-token-java-test-cjrgp(latest run with Step 4D) &agent-bound-token-java-test-dd9gm/var/run/secrets/workload-spiffe-credentials/credentials.jsonspiffe://agents.global.org-<ORG_NUMBER>.system.id.goog/resources/run/projects/<PROJECT_NUMBER>/locations/us-central1/jobs/agent-bound-token-java-testx5t#S256):5Ggf2ofOIkHkvBAwfku6eKQVI5pYzW50whzv-VwSAM8ComputeEngineCredentials):POSTto Metadata Server (ya29.d.c0AZ4bNp...).IdTokenCredentials) & Cryptographic Binding Verification (RFC 8705 § 3.1):https://example-target-service.run.app.textPayload) and verified live Google STS embedded thecnf(Confirmation) claim containing the SHA-256 thumbprint (x5t#S256) of the workload's leaf X.509 certificate:[PASS] JWT x5t#S256 thumbprint EXACTLY matches local leaf certificate SHA-256!).com.google.adk:google-adk:1.9.0) +google-genai& mTLS Proof-of-Possession Verification (Steps 4A, 4B, 4C, 4D):HttpClientFactoryNon-mTLS Transport): Inspected ADK's sharedOkHttpClient(sun.security.ssl.SSLSocketFactoryImpl, no client cert). Calling Google APIs over this non-mTLS channel with the bound token is rejected at the auth layer withHTTP 401 UNAUTHENTICATED.LlmAgent+GeminiTurn on Vertex AI): InvokingInMemoryRunner.runAsync(...)withGemini(gemini-2.5-flash) fails on turn 1 withcom.google.genai.errors.ClientException: 401 . Request had invalid authentication credentials, confirming the known limitation wheregoogle-genaisends bound tokens over a non-mTLS channel.OkHttpClient(configured with/var/run/secrets/workload-spiffe-credentials/certificates.pem+private_key.pem,x5t#S256 = 5Ggf2ofOIkHkvBAwfku6eKQVI5pYzW50whzv-VwSAM8) tohttps://cloudresourcemanager.mtls.googleapis.com/v1/projects/<PROJECT_ID>passes authentication (HTTP 403 PERMISSION_DENIEDIAM check instead of401 UNAUTHENTICATED), proving Google API Frontend verified the token binding against the TLS client certificate handshake.https://cloudresourcemanager.mtls.googleapis.com/v1/projects/<PROJECT_ID>over an mTLSOkHttpClientconfigured with a different X.509 client certificate (x5t#S256 = -57ZjYVm89oczfdO02Hf3Sz-FaYQIVH1DD3c9zaBIKA) is rejected at the auth layer withHTTP 401 UNAUTHENTICATED, confirming that Google API Frontend enforces cryptographic thumbprint matching (cnf.x5t#S256 == SHA256(TLS client cert)).Execution B: Opt-Out Unbound Token Acquisition (
GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false)agent-bound-token-java-test-t7b98--set-env-vars="GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false,GOOGLE_CLOUD_LOCATION=global,GOOGLE_GENAI_USE_VERTEXAI=true".ComputeEngineCredentialsandIdTokenCredentialsfell back to standardHTTP GETrequests against MDS and issued standard unbound tokens (decoded JWT payload confirmed absence of thecnfclaim).Step 4B): WithGOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false, the unbound token works overgoogle-genai's non-mTLS channel and the live ADKLlmAgent+Geminiturn SUCCEEDS:[ADK Event] author=bound-token-verify-agent, content=Hello! Yes, as an agent designed to test bound token behavior with the Java ADK, I am expected to receive and process bound tokens.2. Local End-to-End Simulation & Wire Verification (10 Scenarios)
To verify internal wire-level, discovery, rotation, environment-variable, and error-handling behavior between the client and MDS, we executed our local simulation suite (
LocalSimulationRunner.java) spinning up a local Mock MDS (HttpServer) across 10 end-to-end scenarios:ComputeEngineCredentials+GOOGLE_API_CERTIFICATE_CONFIG): VerifiedHTTP POSTto/computeMetadata/v1/instance/service-accounts/default/token?scopes=https://www.googleapis.com/auth/cloud-platform, verified JSON body{"certificate_chain": "-----BEGIN CERTIFICATE-----\n..."}(serialized as a single PEM string), and verified no extra fields are included in the JSON payload.IdTokenCredentials+GOOGLE_API_CERTIFICATE_CONFIG): VerifiedHTTP POSTto/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://target.run.app(withaudiencepassed as a URL query parameter) and JSON body{"certificate_chain": "-----BEGIN CERTIFICATE-----\n..."}.Gen-1Gen-2): Generated a new X.509 SPIFFE certificate and matching 2048-bit RSA key pair on disk, updated filemtime, and verifiedAgentIdentityUtils.getAgentIdentityCertInfo()invalidated its cache, verified the new key pair, and transmitted the rotatedGen-2certificate chain (!req3.body.equals(req1.body)).GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false): Verified settingGOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=falseswitches requests back toHTTP GETwith an empty request body.credentialbundle.pem) + Private Key Stripping: UnsetGOOGLE_API_CERTIFICATE_CONFIG, wrote a combinedcredentialbundle.pemcontaining both-----BEGIN CERTIFICATE-----and-----BEGIN PRIVATE KEY-----in the well-known directory, and verified thatAgentIdentityUtilsresolvedcertPath == keyPath, verified the key pair, and stripped thePRIVATE KEYblock from the transmittedPOSTpayload.certificates.pem+private_key.pem): UnsetGOOGLE_API_CERTIFICATE_CONFIG, removedcredentialbundle.pem, placed separatecertificates.pemandprivate_key.pemin the well-known directory, and verified boundHTTP POSTacquisition.shouldRequestBoundToken == false): Configured a valid X.509 certificate with a standard GKE Workload Identity SAN (spiffe://my-standard-gke-project.svc.id.goog/ns/default/sa/my-ksa); verifiedAgentIdentityUtilsdid not throw, cachedshouldRequestBoundToken = false, and fell back to standardHTTP GET.GOOGLE_API_USE_CLIENT_CERTIFICATEMatrix:GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES=false(withGOOGLE_API_ENABLE_RUNTIME_BOUND_TOKENunset)HTTP GET.GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=trueoverrides legacyGOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES=falseHTTP POST.GOOGLE_API_USE_CLIENT_CERTIFICATE=falsewith valid agent certs on diskHTTP GET) without startup polling.GOOGLE_API_USE_CLIENT_CERTIFICATE=truewith missing cert filesIOExceptionafter retries instead of silently downgrading to an unbound token.CERT_KEY_MATCH_RETRIES): Wrote a newGen-3non-prod SPIFFE certificate (spiffe://agents-nonprod.global.org-54321.system.id.goog/...) first while delaying the matchingprivate_key.pemupdate on a background thread; verifiedloadAndVerifyCredentials()retried cleanly viaCERT_KEY_MATCH_RETRIESand transmittedGen-3.TOTAL_POLL_CYCLES): Started with an empty well-known directory on initial startup (GOOGLE_API_USE_CLIENT_CERTIFICATE=true), deliveredcertificates.pem+private_key.pemasynchronously from a background thread after ~180ms, and verified the initialrefreshAccessToken()polled until the files arrived and succeeded with a boundHTTP POST.3. Reproducible Test Artifacts & Execution Logs (
gpaste- Internal Corp Access Only)cjrgp& Opt-Outt7b98) + Java ADK + Local 10-Scenario SimulationCloudRunAgentVerifyApp.javacnf.x5t#S256match, and ADK Steps 4A/4B/4C/4D)LocalSimulationRunner.javaHttpServer) testing all 10 scenariosDockerfilegoogle-genaiand overlaying our local PR JARdeploy_cloud_run_job.sh--identity-type=agent-identity, and executebuild_and_run_local.shcjrgp)gcloud logging readfor default Bound Token execution (with inline decoded JWT & ADK Steps 4A/4B/4C/4D)t7b98)gcloud logging readforGOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=falseexecution (showing live ADK Gemini response)Quick Reproduction Steps
To replicate the live Cloud Run test in any GCP project with Agent Identity enabled: