feat: mTLS configuration via x.509 for asynchronous session in google-auth

Signed-off-by: Radhika Agrawal <agrawalradhika@google.com>

Author: agrawalradhika-cell

google/auth/aio/transport/aiohttp.py

@@ -113,7 +113,7 @@ class Request(transport.Request):
     .. automethod:: __call__
     """
 
-    def __init__(self, session: aiohttp.ClientSession = None):
+    def __init__(self, session: Optional[aiohttp.ClientSession] = None):
         self._session = session
         self._closed = False
 

google/auth/aio/transport/mtls.py

@@ -17,14 +17,72 @@
 """
 
 import asyncio
+import contextlib
 import logging
+import os
+from os import getenv, path
+import ssl
+import tempfile
+from typing import Optional
 
 from google.auth import exceptions
 import google.auth.transport._mtls_helper
-import google.auth.transport.mtls
 
 _LOGGER = logging.getLogger(__name__)
 
+@contextlib.contextmanager
+def _create_temp_file(content: bytes):
+    """Creates a temporary file with the given content.
+
+    Args:
+        content (bytes): The content to write to the file.
+
+    Yields:
+        str: The path to the temporary file.
+    """
+    # Create a temporary file that is readable only by the owner.
+    fd, file_path = tempfile.mkstemp()
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(content)
+        yield file_path
+    finally:
+        # Securely delete the file after use.
+        if os.path.exists(file_path):
+            os.remove(file_path)
+
+
+def make_client_cert_ssl_context(
+    cert_bytes: bytes, key_bytes: bytes, passphrase: Optional[bytes] = None
+) -> ssl.SSLContext:
+    """Creates an SSLContext with the given client certificate and key.
+    This function writes the certificate and key to temporary files so that
+    ssl.create_default_context can load them, as the ssl module requires
+    file paths for client certificates.
+    Args:
+        cert_bytes (bytes): The client certificate content in PEM format.
+        key_bytes (bytes): The client private key content in PEM format.
+        passphrase (Optional[bytes]): The passphrase for the private key, if any.
+    Returns:
+        ssl.SSLContext: The configured SSL context with client certificate.
+
+    Raises:
+        google.auth.exceptions.TransportError: If there is an error loading the certificate.
+    """
+    try:
+        context = ssl.create_default_context(ssl.Purpose.SERVER_AUTH)
+
+        # Write cert and key to temp files because ssl.load_cert_chain requires paths
+        with _create_temp_file(cert_bytes) as cert_path:
+            with _create_temp_file(key_bytes) as key_path:
+                context.load_cert_chain(
+                    certfile=cert_path, keyfile=key_path, password=passphrase
+                )
+        return context
+    except (ssl.SSLError, OSError) as exc:
+        raise exceptions.TransportError(
+            "Failed to load client certificate and key for mTLS."
+        ) from exc
 
 async def _run_in_executor(func, *args):
     """Run a blocking function in an executor to avoid blocking the event loop.

google/auth/aio/transport/sessions.py

@@ -21,9 +21,12 @@
 from google.auth import _exponential_backoff, exceptions
 from google.auth.aio import transport
 from google.auth.aio.credentials import Credentials
+from google.auth.aio.transport import mtls
 from google.auth.exceptions import TimeoutError
+import google.auth.transport._mtls_helper
 
 try:
+    import aiohttp
     from google.auth.aio.transport.aiohttp import Request as AiohttpRequest
 
     AIOHTTP_INSTALLED = True
@@ -124,12 +127,70 @@ def __init__(
         _auth_request = auth_request
         if not _auth_request and AIOHTTP_INSTALLED:
             _auth_request = AiohttpRequest()
+        self._is_mtls = False
+        self._cached_cert = None
         if _auth_request is None:
             raise exceptions.TransportError(
                 "`auth_request` must either be configured or the external package `aiohttp` must be installed to use the default value."
             )
         self._auth_request = _auth_request
 
+    async def configure_mtls_channel(self, client_cert_callback=None):
+        """Configure the client certificate and key for SSL connection.
+
+        The function does nothing unless `GOOGLE_API_USE_CLIENT_CERTIFICATE` is
+        explicitly set to `true`. In this case if client certificate and key are
+        successfully obtained (from the given client_cert_callback or from application
+        default SSL credentials), the underlying transport will be reconfigured
+        to use mTLS.
+
+        Args:
+            client_cert_callback (Optional[Callable[[], (bytes, bytes)]]):
+                The optional callback returns the client certificate and private
+                key bytes both in PEM format.
+                If the callback is None, application default SSL credentials
+                will be used.
+
+        Raises:
+            google.auth.exceptions.MutualTLSChannelError: If mutual TLS channel
+                creation failed for any reason.
+        """
+        # Run the blocking check in an executor
+        use_client_cert = await mtls._run_in_executor(
+            google.auth.transport._mtls_helper.check_use_client_cert
+        )
+        if not use_client_cert:
+            self._is_mtls = False
+            return
+
+        try:
+            (
+                self._is_mtls,
+                cert,
+                key,
+            ) = await mtls.get_client_cert_and_key(client_cert_callback)
+
+            if self._is_mtls:
+                self._cached_cert = cert
+                ssl_context = await mtls._run_in_executor(
+                    mtls.make_client_cert_ssl_context, cert, key
+                )
+
+                # Re-create the auth request with the new SSL context
+                if AIOHTTP_INSTALLED and isinstance(self._auth_request, AiohttpRequest):
+                    connector = aiohttp.TCPConnector(ssl=ssl_context)
+                    new_session = aiohttp.ClientSession(connector=connector)
+                    await self._auth_request.close()
+                    self._auth_request = AiohttpRequest(session=new_session)
+
+        except (
+            exceptions.ClientCertError,
+            ImportError,
+            OSError,
+        ) as caught_exc:
+            new_exc = exceptions.MutualTLSChannelError(caught_exc)
+            raise new_exc from caught_exc
+
     async def request(
         self,
         method: str,
@@ -174,6 +235,8 @@ async def request(
         retries = _exponential_backoff.AsyncExponentialBackoff(
             total_attempts=transport.DEFAULT_MAX_RETRY_ATTEMPTS
         )
+        if headers is None:
+            headers = {}
         async with timeout_guard(max_allowed_time) as with_timeout:
             await with_timeout(
                 # Note: before_request will attempt to refresh credentials if expired.
@@ -261,6 +324,11 @@ async def delete(
             "DELETE", url, data, headers, max_allowed_time, timeout, **kwargs
         )
 
+    @property
+    def is_mtls(self):
+        """Indicates if mutual TLS is enabled."""
+        return self._is_mtls
+
     async def close(self) -> None:
         """
         Close the underlying auth request session.

noxfile.py

@@ -91,7 +91,7 @@ def blacken(session):
 @nox.session(python=DEFAULT_PYTHON_VERSION)
 def mypy(session):
     """Verify type hints are mypy compatible."""
-    session.install("-e", ".")
+    session.install("-e", ".[aiohttp]")
     session.install(
         "mypy",
         "types-certifi",

tests/transport/aio/test_sessions_mtls.py

@@ -0,0 +1,119 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import os
+import ssl
+from unittest import mock
+
+import pytest
+
+from google.auth import exceptions
+from google.auth.aio import credentials
+from google.auth.aio.transport import sessions
+
+# This is the valid "workload" format the library expects
+VALID_WORKLOAD_CONFIG = {
+    "version": 1,
+    "cert_configs": {
+        "workload": {"cert_path": "/tmp/mock_cert.pem", "key_path": "/tmp/mock_key.pem"}
+    },
+}
+
+
+class TestSessionsMtls:
+    @pytest.mark.asyncio
+    @mock.patch.dict(os.environ, {"GOOGLE_API_USE_CLIENT_CERTIFICATE": "true"})
+    @mock.patch("os.path.exists")
+    @mock.patch(
+        "builtins.open",
+        new_callable=mock.mock_open,
+        read_data=json.dumps(VALID_WORKLOAD_CONFIG),
+    )
+    @mock.patch("google.auth.aio.transport.mtls.get_client_cert_and_key")
+    @mock.patch("ssl.create_default_context")
+    async def test_configure_mtls_channel(
+        self, mock_ssl, mock_helper, mock_file, mock_exists
+    ):
+        """
+        Tests that the mTLS channel configures correctly when a
+        valid workload config is mocked.
+        """
+        mock_exists.return_value = True
+        mock_helper.return_value = (True, b"fake_cert_data", b"fake_key_data")
+
+        mock_context = mock.Mock(spec=ssl.SSLContext)
+        mock_ssl.return_value = mock_context
+
+        mock_creds = mock.Mock(spec=credentials.Credentials)
+        session = sessions.AsyncAuthorizedSession(mock_creds)
+        await session.configure_mtls_channel()
+
+        assert session._is_mtls is True
+        assert mock_context.load_cert_chain.called
+
+    @pytest.mark.asyncio
+    @mock.patch.dict(os.environ, {"GOOGLE_API_USE_CLIENT_CERTIFICATE": "true"})
+    @mock.patch("os.path.exists")
+    async def test_configure_mtls_channel_disabled(self, mock_exists):
+        """
+        Tests behavior when the config file does not exist.
+        """
+        mock_exists.return_value = False
+        mock_creds = mock.Mock(spec=credentials.Credentials)
+
+        session = sessions.AsyncAuthorizedSession(mock_creds)
+        await session.configure_mtls_channel()
+
+        # If the file doesn't exist, it shouldn't error; it just won't use mTLS
+        assert session._is_mtls is False
+
+    @pytest.mark.asyncio
+    @mock.patch.dict(os.environ, {"GOOGLE_API_USE_CLIENT_CERTIFICATE": "true"})
+    @mock.patch("os.path.exists")
+    @mock.patch(
+        "builtins.open", new_callable=mock.mock_open, read_data='{"invalid": "format"}'
+    )
+    async def test_configure_mtls_channel_invalid_format(self, mock_file, mock_exists):
+        """
+        Verifies that the MutualTLSChannelError is raised for bad formats.
+        """
+        mock_exists.return_value = True
+        mock_creds = mock.Mock(spec=credentials.Credentials)
+
+        session = sessions.AsyncAuthorizedSession(mock_creds)
+        with pytest.raises(exceptions.MutualTLSChannelError):
+            await session.configure_mtls_channel()
+
+    @pytest.mark.asyncio
+    @mock.patch.dict(os.environ, {"GOOGLE_API_USE_CLIENT_CERTIFICATE": "true"})
+    @mock.patch(
+        "google.auth.aio.transport.mtls.has_default_client_cert_source",
+        return_value=True,
+    )
+    async def test_configure_mtls_channel_mock_callback(self, mock_has_cert):
+        """
+        Tests mTLS configuration using bytes-returning callback.
+        """
+
+        def mock_callback():
+            return (b"fake_cert_bytes", b"fake_key_bytes")
+
+        mock_creds = mock.Mock(spec=credentials.Credentials)
+
+        with mock.patch("ssl.SSLContext.load_cert_chain"):
+            session = sessions.AsyncAuthorizedSession(mock_creds)
+            await session.configure_mtls_channel(client_cert_callback=mock_callback)
+
+            assert session._is_mtls is True