docs(auth): document certificate-bound tokens for agent identities

[macastelaz]

Important

Merge after #14559, which adds IdTokenProvider.Option.BIND_ID_TOKEN_FALSE documented here. Both must merge before the agentic-identities-bound-token feature branch is merged to main.

What this adds

Docs only; no code changes.

• google-auth-library-java/README.md: new section "Certificate-bound tokens for agent identities":
  • Bound tokens (access and ID tokens) are the default when an agent identity workload certificate is present.
  • Bound tokens need mTLS with the same certificate. GAX-based client libraries handle this automatically; custom HTTP clients must configure it themselves.
  • When a bound token is requested: certificate discovery through GOOGLE_API_CERTIFICATE_CONFIG or the default directory, and an agent identity SPIFFE trust domain.
  • Turning off binding: GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false, which takes precedence over the legacy GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES. GOOGLE_API_USE_CLIENT_CERTIFICATE=false also turns binding off. Values are case-insensitive, the opt-out applies to the whole process, and it's strongly discouraged.
  • Requesting unbound ID tokens for specific targets: targets reached over standard HTTPS (a Cloud Run *.run.app URL or a custom domain) reject bound ID tokens, so callers pass IdTokenProvider.Option.BIND_ID_TOKEN_FALSE for those targets, with a code example. Access tokens and other targets stay bound.
  • Known limitation: ADK for Java doesn't use mTLS yet, so it hits a 401; the workaround is the opt-out.
• ComputeEngineCredentials class Javadoc: the same behavior in brief, including the per-target ID-token option and the fail-fast cases. If the certificate config points to missing files, or the metadata server doesn't support bound tokens, requests throw IOException instead of silently falling back to unbound tokens.

All statements were checked against AgentIdentityUtils and ComputeEngineCredentials on agentic-identities-bound-token, and against #14559 for the new option.

The Cloud Run public docs are being updated separately (internal CL), and the README links to https://cloud.google.com/run/docs/ai/authenticate-agents.

Release notes

google-auth-library-java/CHANGELOG.md is generated, so release notes come from commit messages. Suggested text for the BEGIN_COMMIT_OVERRIDE block of the feature-branch → main merge PR:

feat(auth): request certificate-bound tokens for agent identities by default. Set GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false to opt out.
feat(auth): add IdTokenProvider.Option.BIND_ID_TOKEN_FALSE to request unbound ID tokens for specific targets.
docs(auth): known limitation: ADK for Java doesn't support mTLS yet; agents that use it must set GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false.

Testing

• fmt-maven-plugin:check passes.

[gemini-code-assist]

Code Review

This pull request introduces support for certificate-bound access and ID tokens for agent identities within ComputeEngineCredentials. It adds a new AgentIdentityUtils utility class to manage certificate discovery, SPIFFE trust domain validation, cryptographic key-pair verification, and credential caching. ComputeEngineCredentials is updated to request bound tokens via POST requests to the metadata server when a workload certificate is available. Feedback on the changes suggests improving code readability in the test suite by avoiding fully qualified class names when the class is already imported.

[gemini-code-assist]

Avoid using fully qualified class names (such as java.nio.file.attribute.FileTime) if there is no class name conflict in the file and the class is already imported, as it unnecessarily reduces code readability.

    Files.setLastModifiedTime(
        keyPath, FileTime.fromMillis(System.currentTimeMillis() + 10000));

References

1. Do not use fully qualified class names if there is no class name conflict in the file and the class is already imported, as it unnecessarily reduces code readability.