feat: Enable Bound Token for Agentic Identities by macastelaz · Pull Request #13873 · googleapis/google-cloud-java

macastelaz · 2026-07-23T14:42:16Z

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

gemini-code-assist

Code Review

This pull request introduces Agent Identity token binding support for Cloud Run. It adds AgentIdentityUtils to resolve, load, and verify certificates and private keys, and updates ComputeEngineCredentials to request bound tokens via POST requests when a valid certificate chain is present. The review feedback suggests a cohesive improvement to implement a single-read pattern for certificate files. By reading the certificate chain once, caching it in CertInfo, and passing it to parseCertificate and getBoundTokenPayload, the implementation can avoid redundant disk I/O and prevent potential race conditions during certificate rotation.

macastelaz · 2026-07-23T21:38:31Z

+ // Environment variables
+ static final String GOOGLE_API_CERTIFICATE_CONFIG = "GOOGLE_API_CERTIFICATE_CONFIG";
+ static final String GOOGLE_API_PREVENT_TOKEN_SHARING_FOR_GCP_SERVICES =
+ "GOOGLE_API_PREVENT_TOKEN_SHARING_FOR_GCP_SERVICES";


Note that based on googleapis/google-cloud-python#17698 (comment) this is not yet finalized

1. POST request to MDS with cert-chain 2. Cert-key matching 3. Included logic to consider the user's choice by looking at GOOGLE_API_USE_CLIENT_CERTIFICATE env variable 4. Bound ID tokens. # Conflicts: # google-auth-library-java/oauth2_http/javatests/com/google/auth/oauth2/ComputeEngineCredentialsTest.java # google-auth-library-java/oauth2_http/javatests/com/google/auth/oauth2/MockMetadataServerTransport.java

…etry logic. Nit fixes. # Conflicts: # google-auth-library-java/oauth2_http/javatests/com/google/auth/oauth2/ComputeEngineCredentialsTest.java

# Conflicts: # google-auth-library-java/oauth2_http/java/com/google/auth/oauth2/ComputeEngineCredentials.java

…fill CI formatting rules

…n binding - Prevent 30-second polling delay and IOException on standard GCE/container environments when well-known credentials directory exists without certificate files unless mTLS is explicitly enabled. - Fail fast on malformed certificate config JSON without retrying. - Fix URI resource path decoding in AgentIdentityUtilsTest to prevent FileNotFoundException when workspace paths contain spaces. - Copy matching private key in well-known fallback test to verify full key pair loading. - Clean up static wellKnownDir state and temporary directories in ComputeEngineCredentialsTest. - Correct opt-out environment variable value in test setup from 'true' to 'false'.

lsirac · 2026-08-16T23:57:00Z

+@InternalApi
+public final class AgentIdentityUtils {
+
+ /** Javadoc. */


Remove placeholder /** Javadoc. */ everywhere and replace with real docs where applicable

lsirac · 2026-08-17T00:00:37Z

+ static {
+ List<Long> intervals = new ArrayList<>();
+ for (int i = 0; i < FAST_POLL_CYCLES; i++) {
+ intervals.add(FAST_POLL_INTERVAL_MS);
+ }
+ long remainingTime = TOTAL_TIMEOUT_MS - (FAST_POLL_CYCLES * FAST_POLL_INTERVAL_MS);
+ int slowPollCycles = (int) (remainingTime / SLOW_POLL_INTERVAL_MS);
+ for (int i = 0; i < slowPollCycles; i++) {
+ intervals.add(SLOW_POLL_INTERVAL_MS);
+ }
+ POLLING_INTERVALS = Collections.unmodifiableList(intervals);
+ }


Why not do this directly in the polling loop?

lsirac · 2026-08-17T00:01:44Z

+ static final String GOOGLE_API_CERTIFICATE_CONFIG = "GOOGLE_API_CERTIFICATE_CONFIG";
+
+ /** Javadoc. */
+ static final String GOOGLE_API_PREVENT_TOKEN_SHARING_FOR_GCP_SERVICES =


GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES for the old one.
but I think they picked a new one.

lsirac · 2026-08-17T00:03:52Z

+ * @throws IOException If an I/O error occurs while reading the files, or if the key-pair
+ * verification fails after retries.
+ */
+ static CertInfo getAgentIdentityCertInfo() throws IOException {


Should we first check if GOOGLE_API_USE_CLIENT_CERTIFICATE=false? AIP 4114

lsirac · 2026-08-17T00:16:01Z

+ private static final int CERT_KEY_MATCH_RETRIES = 3;
+
+ /** Javadoc. */
+ private static final long CERT_KEY_MATCH_RETRY_INTERVAL_MS = 100;


AIP-4118 recommends ~5s between attempts. What does Python do?

lsirac · 2026-08-17T00:24:50Z

+ /** Javadoc. */
+ private static final List<Pattern> AGENT_IDENTITY_SPIFFE_PATTERNS =
+ ImmutableList.of(
+ Pattern.compile("^agents\\.global\\.org-\\d+\\.system\\.id\\.goog$"),


I think in Python @nbayati went back and added non prod patterns. Let's add that + tests?

lsirac · 2026-08-17T00:31:04Z

+ }
+
+ if (!matched) {
+ throw new IOException(


should this be an IOException or something else? perhaps a retryable GoogleAuthException?

lsirac · 2026-08-17T00:32:21Z

+ transportFactory.transport.getRequest();
+ assertEquals("POST", transportFactory.transport.getRequestMethod());
+ String body = request.getContentAsString();
+ assertTrue(body.contains("certificate_chain"));


Let's validate that it contains the full cert in these tests

lsirac · 2026-08-17T00:33:39Z

+ "spiffe://agents.global.org-INVALID.system.id.goog/path";
+
+ private TestEnvironmentProvider envProvider;
+ private Path tempDir;


use @TempDir

lsirac · 2026-08-17T00:35:33Z

+ * <p>To handle transient race conditions during certificate rotation on disk, this method employs
+ * a retry mechanism with backoff when reading the configuration and certificate files.
+ *
+ * @return A {@link CertInfo} object containing the loaded certificate and its path, or {@code


doesn't store the path?

gemini-code-assistBot reviewed Jul 23, 2026
View reviewed changes

macastelaz changed the title ~~Pr 13169 fixes~~feat: Enable Bound Token for Agentic IdentitiesJul 23, 2026

macastelaz commented Jul 23, 2026
View reviewed changes

macastelaz marked this pull request as ready for review July 24, 2026 03:21

macastelaz requested review from a team as code owners July 24, 2026 03:21

macastelaz assigned macastelaz, lsirac and nbayati and unassigned macastelaz Jul 24, 2026

lsirac requested a review from nbayati July 24, 2026 17:43

macastelaz closed this Jul 28, 2026

macastelaz force-pushed the pr-13169-fixes branch from f5e81cc to db1c39cCompare July 28, 2026 18:23

macastelaz reopened this Jul 28, 2026

macastelaz requested a review from a team as a code owner July 28, 2026 18:35

macastelaz force-pushed the pr-13169-fixes branch from db1c39c to 3ada55fCompare July 28, 2026 19:08

vvermanand others added 13 commits July 29, 2026 03:35

Port Agent Identities feature for Cloud Run
0af6032

Added logic to verify key and cert to ensure no mismatch along with r…
a591db4
…etry logic. Nit fixes. # Conflicts: # google-auth-library-java/oauth2_http/javatests/com/google/auth/oauth2/ComputeEngineCredentialsTest.java

Added documentation and addressed comments.
18afacb

lint fix.
7a2ae21

Fix unaddressed comments from PR 13169
2c1c298

Fix incorrect fail-fast logic for custom certificate config paths
0e3d440

Fix AgentIdentityUtils token binding logic and TOCTOU vulnerabilities
c5fab1d

Fix token binding 30s timeout on permission and absent config errors
0036d0c

fix: resolve lint/formatting issues in AgentIdentityUtils
4d99d25

fix: resolve checkstyle and format violations
727b596

test: add edge case coverage and refactor brittle resource loading
bd2f98b

style: fix checkstyle violations in auth utilities
e3d105e
# Conflicts: # google-auth-library-java/oauth2_http/java/com/google/auth/oauth2/ComputeEngineCredentials.java

macastelaz added 5 commits July 29, 2026 03:35

Fix AgentIdentityUtilsTest compilation after checkstyle
cb71972

test: fix missing InputStream import in tests
a4b6192

Restore EnableAutoValue.txt for AutoValue annotation processor
71cd2c1

Restore accidentally deleted gradle-wrapper.jar
ea07ce4

style: fix formatting violations in oauth2_http
5b1c82b

macastelaz force-pushed the pr-13169-fixes branch from 93a7c86 to 5b1c82bCompare July 29, 2026 03:35

macastelaz added 2 commits July 29, 2026 19:59

docs(oauth2): Make AgentIdentityUtils Javadoc comments proper and ful…
0649e49
…fill CI formatting rules

macastelaz force-pushed the pr-13169-fixes branch from 73fa344 to 6181f6aCompare August 5, 2026 02:50

lsirac reviewed Aug 17, 2026
View reviewed changes

Uh oh!

Conversation

macastelaz commented Jul 23, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assistBot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

macastelaz commented Jul 23, 2026•
edited
Loading