feat(auth): add bound token support for access and JWT id tokens for Cloud Run by nbayati · Pull Request #17698 · googleapis/google-cloud-python

nbayati · 2026-07-13T05:15:47Z

This PR adds the following:

Switch the MDS token acquisition from a GET to a POST request when the agentic cert is detected.
Add get_agent_identity_certificate_and_bytes() utility to read the raw certificate bytes alongside the parsed cert.
Update _metadata.get_service_account_token() (for access tokens) and IDTokenCredentials.refresh() (for ID tokens) to send a POST request with the certificate_chain payload instead of a GET request when bound tokens are supported.
Update _metadata.get() helper to support method and body params.
Add and update unit tests to verify the new POST request flows.

design: go/sdk-mds-bound-token

id token verification:

test script: paste/4514812804595712
log results: paste/6316867684794368

Note:

This PR relies on the existing pattern of locating the certificates using the path provided by the config file available at GOOGLE_API_CERTIFICATE_CONFIG. It does not currently fallback on checking the well known location if the env var is not set, which would limit the scope to CR, as GKE and GCE don't set this env var.
It uses the same condition to decide if a bound token should be requested for both access token and id token. We might decide to add a separate env var to opt out.
it still uses the existing GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES flag to opt out. We might update it and add a new env var, but will keep the old one for backward compatibility.

gemini-code-assist

Code Review

This pull request updates the Google Auth library to request bound tokens from the Compute Engine metadata server using a POST request with the certificate chain in the body, rather than passing a fingerprint in the URL. To support this, get_agent_identity_certificate_and_bytes was introduced to retrieve both the parsed certificate and its raw bytes, and the metadata get helper was updated to support POST requests and bodies. Feedback on the changes suggests simplifying a redundant tuple check in credentials.py by directly unpacking the returned value from get_agent_identity_certificate_and_bytes.

parthea · 2026-07-13T14:58:02Z

    # look up the certificate.
    is_opted_out = (
        os.environ.get(
            environment_vars.GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES,


From AI code review

To align with the cross-SDK standardization for certificate-bound tokens, we should support both the standard environment variable GOOGLE_API_PREVENT_TOKEN_SHARING_FOR_GCP_SERVICES (without the _AGENT infix) as well as the legacy GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES flag.

Could we update this check to look for both env vars so we maintain backward compatibility while adopting the unified standard?

We are waiting for the product decision on the new env var name as GOOGLE_API_PREVENT_TOKEN_SHARING_FOR_GCP_SERVICES is not finalized yet.

Just double checking - did this get finalized now?

lsirac · 2026-07-16T00:26:38Z

Both ID token unit tests (test_refresh_with_agent_identity and test_refresh_with_agent_identity_opt_out_or_not_agent) return fake certificates from get_agent_identity_certificate_and_bytes(). Please add a unit test where get_agent_identity_certificate_and_bytes() returns (None, None) so the standard fallback path (running without an agent identity certificate on disk) is fully covered.

nbayati · 2026-07-17T06:03:40Z

Can't be merged before CR MDS is ready. Currently targeting a date between July 31 and Aug 7.

macastelaz · 2026-07-30T17:21:42Z

    # look up the certificate.
    is_opted_out = (
        os.environ.get(
            environment_vars.GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES,


Just double checking - did this get finalized now?

macastelaz · 2026-07-30T17:36:38Z

        return_none_for_not_found_error (Optional[bool]): If True, returns None
            for 404 error instead of throwing an exception.
+        method (str): The HTTP method to use for the request. Defaults to "GET".
+        body (Optional[bytes]): The HTTP request body payload to send. Defaults to None.


Does it make sense to raise a ValueError (or similar) here to "exit early" if a body is specified byt the method is GET. While I think technically valid to include a body in GET requests (most often I think the body just gets ignored), it may lead a caller to think it is getting a bound token when in reality it isn't?

Yes! that's a great suggestion! Done!

macastelaz · 2026-07-30T20:05:44Z

+            (
+                cert,
+                cert_bytes,
+            ) = _agent_identity_utils.get_agent_identity_certificate_and_bytes()


nit: It looks like both this and should_request_bound_token check GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES and call _mtls_helper._check_use_client_cert_env() - I wonder if we can optimize this in any way?

Yeah you're right, they do both check the env var but I don't think we can eliminate it because the two methods have different callers and come from different paths (compute engine and identity pool) so we need to have the check in both places. We could probably do some refactoring, but I'm leaning toward keeping the code as is since the env var reading is not an expensive operation and this way we can keep the methods self contained.

lsirac · 2026-09-15T23:39:07Z

-        return None
+        return None, None
+
+    return parse_certificate(cert_bytes), cert_bytes


If cert_path points to a combined bundle (credentialbundle.pem), sending raw cert_file.read() puts the private key into certificate_chain over plain HTTP (and GKE MDS rejects non-CERTIFICATE PEM blocks with 400). Also, cert_bytes.decode("utf-8") will raise an uncaught UnicodeDecodeError if there are non-UTF-8 OpenSSL bag attributes outside the PEM boundaries.

We should extract only the CERTIFICATE blocks before returning, e.g. with a non-greedy r"-----BEGIN CERTIFICATE-----.+?-----END CERTIFICATE-----\r?\n?" (_mtls_helper._CERT_REGEX is greedy and would still grab an interleaved key).

In this PR discovery only resolves cert_path from GOOGLE_API_CERTIFICATE_CONFIG (which on Cloud Run points to the standalone certificates.pem file). Automatic discovery of GKE's combined credentialbundle.pem is not active here.

In our follow-up PR adding GKE support, get_agent_identity_certificate_and_bytes() will be updated to extract only -----BEGIN CERTIFICATE-----...-----END CERTIFICATE----- blocks via non-greedy regex. That strips any private key blocks from combined bundles and discards any non-UTF-8 OpenSSL bag attributes outside the PEM boundaries prior to UTF-8 decoding.

I'll mark this as resolved since it's out of the scope of this PR and will be addressed in the GKE PR.

We should fix this in this PR before merging rather than deferring to the GKE follow-up. GOOGLE_API_CERTIFICATE_CONFIG is not Cloud Run specific. GKE/GCE can set this today with cert_path and key_path pointing to the same combined PEM bundle.

Switch the MDS token acquisition from a GET to a POST request when the agentic cert is detected. * Add `get_agent_identity_certificate_and_bytes()` utility to read the raw certificate bytes alongside the parsed cert. * Update `_metadata.get_service_account_token()` (for access tokens) and `IDTokenCredentials.refresh()` (for ID tokens) to send a POST request with the `certificate_chain` payload instead of a GET request when bound tokens are supported. * Update `_metadata.get()` helper to support `method` and `body` params. * Add and update unit tests to verify the new POST request flows.

…and update docstrings and comments

…eplace outdated mocks

…llback to deprecated var

…certificate_and_bytes

…icate_and_bytes

…ertificate rotation

…hy 38 compatibility

…nt identity tests

lsirac · 2026-09-19T18:22:11Z

+        ) = _agent_identity_utils.get_agent_identity_certificate_and_bytes()
+
+        expected_certs = NON_AGENT_IDENTITY_CERT_BYTES + NON_AGENT_IDENTITY_CERT_BYTES
+        assert isinstance(cert, x509.Certificate)


Can we use AGENT_IDENTITY_CERT_BYTES as the first block and NON_AGENT_IDENTITY_CERT_BYTES as the second in combined_bundle, and assert _is_agent_identity_certificate(cert)? Right now both blocks are NON_AGENT_IDENTITY_CERT_BYTES, so changing return certs[0] to return certs[-1] in parse_certificate still passes the test suite.

lsirac · 2026-09-19T18:22:11Z

-"""Environment variable to prevent agent token sharing for GCP services."""
+"""Environment variable to prevent agent token sharing for GCP services.
+
+.. deprecated::


Nit: .. deprecated:: needs a version argument on the same line like credentials.py line 93, otherwise Sphinx renders the first line of text as the version string.

lsirac · 2026-09-19T18:22:11Z

 file. This variable is the fallback of GOOGLE_API_CERTIFICATE_CONFIG."""

+GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN = "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN"
+"""Environment variable controlling whether to enable runtime bound tokens."""


Nit: Can we note in the docstring that this defaults to enabled, only a case-insensitive false disables it, and setting it takes precedence over GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES?

lsirac · 2026-09-19T18:22:11Z

+    def test_parse_certificate_full_chain_rejects_malformed_intermediate(
+        self, second_cert_block, monkeypatch
+    ):
+        monkeypatch.delattr(x509, "load_pem_x509_certificates", raising=False)


Nit: Can we drop this monkeypatch.delattr line and the unused monkeypatch parameter now that parse_certificate calls load_pem_x509_certificate instead of load_pem_x509_certificates?

lsirac · 2026-09-19T18:22:11Z

    """
    try:
        from cryptography import x509
+        from google.auth.transport import _mtls_helper


Nit: Can we move from google.auth.transport import _mtls_helper outside the try block like lines 264 and 412 so an import error in _mtls_helper does not get reported as CRYPTOGRAPHY_NOT_FOUND_ERROR?

lsirac · 2026-09-19T18:22:11Z

-    if len(cert_match) != 1:
+    if not cert_match:
        raise exceptions.ClientCertError("Client SSL certificate is missing or invalid")
+    cert_chain = b"".join(


Nit: Can we extract a small helper for this 4-line PEM block join and reuse it here and in _read_cert_file at line 543, plus add a test case where the first block has no trailing newline so the else branch is covered?

lsirac · 2026-09-19T18:22:11Z

    return get(request, path, params={"recursive": "true"})


+def _get_token_request_params(metrics_header_value):


Nit: Could we rename _get_token_request_params to _build_token_request_options since params in this file refers to the URL query parameters dict right next to it at line 533?

lsirac · 2026-09-19T18:22:11Z

    _, kwargs = request.call_args
-    url = kwargs["url"]
-    assert "bindCertificateFingerprint" not in url
+    assert kwargs.get("method", "GET") == "GET"


Nit: Can we change kwargs.get("method", "GET") == "GET" to kwargs["method"] == "GET" here and at line 870 like test_credentials.py line 979 does, so the test fails if method is omitted?

lsirac · 2026-09-19T18:22:11Z

+            "https://my-service-123456.us-central1.mtls.run.app/v1",
+        ],
+    )
+    def test_cert_rotation_triggered_on_psc_url(self, mtls_url):


Nit: Can we rename test_cert_rotation_triggered_on_psc_url to test_cert_rotation_triggered_on_mtls_url here and in test_urllib3.py line 705 now that it is parametrized over both PSC and Cloud Run URLs?

nbayati requested review from a team as code owners July 13, 2026 05:15

nbayati requested a review from lsirac July 13, 2026 05:16

gemini-code-assist Bot reviewed Jul 13, 2026

View reviewed changes

Comment thread packages/google-auth/google/auth/compute_engine/credentials.py Outdated

parthea assigned lsirac Jul 13, 2026

parthea reviewed Jul 13, 2026

View reviewed changes

parthea assigned nbayati Jul 13, 2026

macastelaz reviewed Jul 15, 2026

View reviewed changes

parthea unassigned lsirac Jul 16, 2026

nbayati added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Jul 17, 2026

macastelaz mentioned this pull request Jul 23, 2026

feat: Enable Bound Token for Agentic Identities googleapis/google-cloud-java#13873

Open

nbayati force-pushed the bound_token_post branch from 2766928 to ccc2a5d Compare July 29, 2026 21:35

nbayati requested review from macastelaz and parthea July 29, 2026 21:36

macastelaz approved these changes Jul 30, 2026

View reviewed changes

macastelaz reviewed Jul 30, 2026

View reviewed changes

lsirac requested changes Sep 15, 2026

View reviewed changes

nbayati and others added 7 commits September 17, 2026 21:02

Refactor bound token request logic in compute_engine for consistency …

865fc5b

…and update docstrings and comments

test(auth): update compute_engine tests for bound token headers and r…

939d005

…eplace outdated mocks

feat(auth): add GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN env var with fa…

93cd395

…llback to deprecated var

Add defensive error handling and unit tests

82a07c4

fix(auth): extract only CERTIFICATE PEM blocks in get_agent_identity_…

7a295e1

…certificate_and_bytes

fix(auth): handle OSError and ValueError in get_agent_identity_certif…

f7fdd75

…icate_and_bytes

nbayati force-pushed the bound_token_post branch from ccc2a5d to f7fdd75 Compare September 18, 2026 06:42

nbayati requested review from lsirac and macastelaz September 18, 2026 06:44

nbayati removed the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Sep 18, 2026

nbayati removed their assignment Sep 18, 2026

nbayati added 3 commits September 18, 2026 23:35

fix(auth): validate full agent identity cert chain

dbef436

fix(auth): support Cloud Run mTLS (*.mtls.run.app) endpoints in 401 c…

76147a3

…ertificate rotation

fix(auth): use load_pem_x509_certificate per PEM block for cryptograp…

901c5f3

…hy 38 compatibility

lsirac requested changes Sep 19, 2026

View reviewed changes

nbayati added 3 commits September 19, 2026 04:58

fix(auth): resolve symlinks in _is_in_well_known_dir and clean up age…

a6be0d2

…nt identity tests

fix(auth): refactor MDS token request helper

d053dde

fix(auth): use non-greedy PEM cert and key regexes in _mtls_helper

de557d6

lsirac requested changes Sep 19, 2026

View reviewed changes

		return get(request, path, params={"recursive": "true"})


		def _get_token_request_params(metrics_header_value):

Conversation

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

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lsirac commented Jul 16, 2026

Uh oh!

nbayati commented Jul 17, 2026

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nbayati commented Jul 13, 2026 •

edited

Loading