Pass through HTTPX Client config (#265)

* pass HTTPX client config

* add `trust_env` + `timeout` config

* fix imports

* remove `timeout` arg

results in mypy error (although this seems like a mistake, it would just overwrite the default timeout value if it was provided).

* verify can accept bool value

* HttpClientConfig docstring

* black formatting

* use future annotations with typing_extensions `NotRequired`

* pyupgrade

* pass down http_client_config from AzureAuthorizationCodeBearerBase

* refactor: trust the type checker for http_client_config

- drop the runtime unknown-key validation; the TypedDict is the
  contract and type checkers enforce it, so an invalid dict simply
  surfaces httpx2's own error
- narrow verify to ssl.SSLContext | bool: httpx2 deprecates the
  CA-bundle-path string form, so don't advertise it in a new API --
  the docstring shows ssl.create_default_context(cafile=...) instead

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore: bump version to 5.3.0

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Jonas Krüger Svensson <jonas@vibber.ai>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

fastapi_azure_auth/__init__.py

@@ -3,5 +3,6 @@
     MultiTenantAzureAuthorizationCodeBearer as MultiTenantAzureAuthorizationCodeBearer,
     SingleTenantAzureAuthorizationCodeBearer as SingleTenantAzureAuthorizationCodeBearer,
 )
+from fastapi_azure_auth.openid_config import HttpClientConfig as HttpClientConfig  # noqa: F401
 
-__version__ = '5.2.1'
+__version__ = '5.3.0'

fastapi_azure_auth/auth.py

@@ -30,7 +30,7 @@
     UnauthorizedHttp,
     UnauthorizedWebSocket,
 )
-from fastapi_azure_auth.openid_config import OpenIdConfig
+from fastapi_azure_auth.openid_config import HttpClientConfig, OpenIdConfig
 from fastapi_azure_auth.user import User
 from fastapi_azure_auth.utils import get_unverified_claims, get_unverified_header, is_guest
 
@@ -58,6 +58,7 @@ def __init__(
         openid_config_url: str | None = None,
         openapi_description: str | None = None,
         scheme_name: str = 'AzureAuthorizationCodeBearerBase',
+        http_client_config: HttpClientConfig | None = None,
     ) -> None:
         """
         Initialize settings.
@@ -108,6 +109,10 @@ def __init__(
         :param scheme_name: str
             The name of the security scheme to be used in OpenAPI documentation.
             Default is 'AzureAuthorizationCodeBearerBase'.
+        :param http_client_config: HttpClientConfig
+            Configuration for the HTTP client used to fetch the OpenID configuration and signing keys,
+            e.g. a custom SSL context. Note that these endpoints supply the token signing keys;
+            disabling certificate verification breaks the chain of trust for token validation.
         """
         self.auto_error = auto_error
         # Validate settings, making sure there's no misconfigured dependencies out there
@@ -124,6 +129,7 @@ def __init__(
             multi_tenant=self.multi_tenant,
             app_id=app_client_id if openid_config_use_app_id else None,
             config_url=openid_config_url or None,
+            http_client_config=http_client_config,
         )
 
         self.leeway: int = leeway
@@ -303,6 +309,7 @@ def __init__(
         openapi_token_url: str | None = None,
         openapi_description: str | None = None,
         scheme_name: str = 'AzureAD_PKCE_single_tenant',
+        http_client_config: HttpClientConfig | None = None,
     ) -> None:
         """
         Initialize settings for a single tenant application.
@@ -341,6 +348,10 @@ def __init__(
         :param scheme_name: str
             The name of the security scheme to be used in OpenAPI documentation.
             Default is 'AzureAD_PKCE_single_tenant'.
+        :param http_client_config: HttpClientConfig
+            Configuration for the HTTP client used to fetch the OpenID configuration and signing keys,
+            e.g. a custom SSL context. Note that these endpoints supply the token signing keys;
+            disabling certificate verification breaks the chain of trust for token validation.
         """
         super().__init__(
             app_client_id=app_client_id,
@@ -353,6 +364,7 @@ def __init__(
             openapi_authorization_url=openapi_authorization_url,
             openapi_token_url=openapi_token_url,
             openapi_description=openapi_description,
+            http_client_config=http_client_config,
         )
         self.scheme_name: str = scheme_name
 
@@ -372,6 +384,7 @@ def __init__(
         openapi_token_url: str | None = None,
         openapi_description: str | None = None,
         scheme_name: str = 'AzureAD_PKCE_multi_tenant',
+        http_client_config: HttpClientConfig | None = None,
     ) -> None:
         """
         Initialize settings for a multi-tenant application.
@@ -415,6 +428,10 @@ def __init__(
         :param scheme_name: str
             The name of the security scheme to be used in OpenAPI documentation.
             Default is 'AzureAD_PKCE_multi_tenant'.
+        :param http_client_config: HttpClientConfig
+            Configuration for the HTTP client used to fetch the OpenID configuration and signing keys,
+            e.g. a custom SSL context. Note that these endpoints supply the token signing keys;
+            disabling certificate verification breaks the chain of trust for token validation.
         """
         super().__init__(
             app_client_id=app_client_id,
@@ -429,6 +446,7 @@ def __init__(
             openapi_authorization_url=openapi_authorization_url,
             openapi_token_url=openapi_token_url,
             openapi_description=openapi_description,
+            http_client_config=http_client_config,
         )
         self.scheme_name: str = scheme_name
 
@@ -448,6 +466,7 @@ def __init__(
         openapi_token_url: str | None = None,
         openapi_description: str | None = None,
         scheme_name: str = 'AzureAD_PKCE_B2C_multi_tenant',
+        http_client_config: HttpClientConfig | None = None,
     ) -> None:
         """
         Initialize settings for a B2C multi-tenant application.
@@ -486,6 +505,10 @@ def __init__(
         :param scheme_name: str
             The name of the security scheme to be used in OpenAPI documentation.
             Default is 'AzureAD_PKCE_B2C_multi_tenant'.
+        :param http_client_config: HttpClientConfig
+            Configuration for the HTTP client used to fetch the OpenID configuration and signing keys,
+            e.g. a custom SSL context. Note that these endpoints supply the token signing keys;
+            disabling certificate verification breaks the chain of trust for token validation.
         """
         super().__init__(
             app_client_id=app_client_id,
@@ -501,5 +524,6 @@ def __init__(
             openapi_authorization_url=openapi_authorization_url,
             openapi_token_url=openapi_token_url,
             openapi_description=openapi_description,
+            http_client_config=http_client_config,
         )
         self.scheme_name: str = scheme_name

fastapi_azure_auth/openid_config.py

@@ -1,6 +1,7 @@
 import logging
+import ssl
 from datetime import datetime, timedelta
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, NotRequired, TypedDict
 
 import jwt
 from fastapi import HTTPException, status
@@ -12,20 +13,51 @@
 log = logging.getLogger('fastapi_azure_auth')
 
 
+class HttpClientConfig(TypedDict):
+    """
+    Configuration for the HTTP client used to fetch the OpenID configuration and signing keys.
+
+    verify - (optional) `True` (the default) verifies TLS certificates against the OS trust store,
+        an `ssl.SSLContext` uses a custom trust configuration (e.g.
+        `ssl.create_default_context(cafile='path/to/ca-bundle.pem')`), and `False`
+        disables verification entirely.
+
+        .. warning::
+            This endpoint supplies the keys used to validate every access token. Disabling
+            verification allows an attacker who can intercept traffic to inject their own
+            signing keys, which breaks the entire chain of trust.
+    trust_env - (optional) Enables or disables reading proxy/SSL configuration from environment variables.
+    timeout - (optional) Request timeout in seconds. Defaults to 10.
+    """
+
+    verify: NotRequired[ssl.SSLContext | bool]
+    trust_env: NotRequired[bool]
+    timeout: NotRequired[float]
+
+
 class OpenIdConfig:
     def __init__(
         self,
         tenant_id: str | None = None,
         multi_tenant: bool = False,
         app_id: str | None = None,
         config_url: str | None = None,
+        http_client_config: HttpClientConfig | None = None,
     ) -> None:
         self.tenant_id: str | None = tenant_id
         self._config_timestamp: datetime | None = None
         self.multi_tenant: bool = multi_tenant
         self.app_id = app_id
         self.config_url = config_url
 
+        if http_client_config is not None and http_client_config.get('verify') is False:
+            log.warning(
+                'TLS certificate verification is disabled for the OpenID configuration endpoint. '
+                'This endpoint supplies the token signing keys; only disable verification in development.'
+            )
+        # Store a copy so a dict mutated by the caller can't change behaviour at the next config refresh.
+        self.http_client_config: HttpClientConfig = http_client_config.copy() if http_client_config else {}
+
         self.authorization_endpoint: str
         self.signing_keys: dict[str, AllowedPublicKeys]
         self.token_endpoint: str
@@ -72,7 +104,8 @@ async def _load_openid_config(self) -> None:
         if self.app_id:
             config_url += f'?appid={self.app_id}'
 
-        async with AsyncClient(timeout=10) as client:
+        client_config: dict[str, Any] = {'timeout': 10, **self.http_client_config}
+        async with AsyncClient(**client_config) as client:
             log.info('Fetching OpenID Connect config from %s', config_url)
             openid_response = await client.get(config_url)
             openid_response.raise_for_status()

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-azure-auth"
-version = "5.2.1"  # Remember to change in __init__.py as well
+version = "5.3.0"  # Remember to change in __init__.py as well
 description = "Easy and secure implementation of Azure Entra ID for your FastAPI APIs"
 authors = [{ name = "Jonas Krüger Svensson", email = "jonas@vibber.ai" }]
 requires-python = ">=3.11"

tests/test_provider_config.py

@@ -1,3 +1,4 @@
+import logging
 from datetime import datetime, timedelta
 
 import pytest
@@ -6,6 +7,7 @@
 
 from demo_project.api.dependencies import azure_scheme
 from demo_project.main import app
+from fastapi_azure_auth import HttpClientConfig, SingleTenantAzureAuthorizationCodeBearer
 from fastapi_azure_auth.openid_config import OpenIdConfig
 from tests.utils import build_access_token, build_openid_keys, openid_configuration
 
@@ -68,3 +70,69 @@ async def test_custom_config_id(httpx2_mock):
     )
     await openid_config.load_config()
     assert len(openid_config.signing_keys) == 2
+
+
+def _capture_client_kwargs(mocker):
+    """Patch the AsyncClient used for config fetching so the kwargs it receives can be asserted."""
+    import fastapi_azure_auth.openid_config as openid_config_module
+
+    captured = {}
+    real_client = openid_config_module.AsyncClient
+
+    def capture(**kwargs):
+        captured.update(kwargs)
+        return real_client(**kwargs)
+
+    mocker.patch.object(openid_config_module, 'AsyncClient', side_effect=capture)
+    return captured
+
+
+@pytest.mark.anyio
+async def test_http_client_config_passed_to_client(httpx2_mock, mocker):
+    captured = _capture_client_kwargs(mocker)
+    openid_config = OpenIdConfig('vibber_tenant', http_client_config={'trust_env': False, 'timeout': 30})
+    httpx2_mock.get('https://login.microsoftonline.com/vibber_tenant/v2.0/.well-known/openid-configuration').respond(
+        json=openid_configuration()
+    )
+    httpx2_mock.get('https://login.microsoftonline.com/vibber_tenant/discovery/v2.0/keys').respond(
+        json=build_openid_keys()
+    )
+    await openid_config.load_config()
+    assert captured == {'timeout': 30, 'trust_env': False}
+    assert len(openid_config.signing_keys) == 2
+
+
+@pytest.mark.anyio
+async def test_http_client_config_defaults_to_ten_second_timeout(httpx2_mock, mocker):
+    captured = _capture_client_kwargs(mocker)
+    openid_config = OpenIdConfig('vibber_tenant')
+    httpx2_mock.get('https://login.microsoftonline.com/vibber_tenant/v2.0/.well-known/openid-configuration').respond(
+        json=openid_configuration()
+    )
+    httpx2_mock.get('https://login.microsoftonline.com/vibber_tenant/discovery/v2.0/keys').respond(
+        json=build_openid_keys()
+    )
+    await openid_config.load_config()
+    assert captured == {'timeout': 10}
+
+
+def test_http_client_config_verify_false_warns(caplog):
+    with caplog.at_level(logging.WARNING, logger='fastapi_azure_auth'):
+        OpenIdConfig('vibber_tenant', http_client_config={'verify': False})
+    assert 'TLS certificate verification is disabled' in caplog.text
+
+
+def test_http_client_config_is_copied_at_construction():
+    config: HttpClientConfig = {'trust_env': False}
+    openid_config = OpenIdConfig('vibber_tenant', http_client_config=config)
+    config['trust_env'] = True
+    assert openid_config.http_client_config == {'trust_env': False}
+
+
+def test_http_client_config_passed_through_scheme():
+    scheme = SingleTenantAzureAuthorizationCodeBearer(
+        app_client_id='client-id',
+        tenant_id='vibber_tenant',
+        http_client_config={'trust_env': False},
+    )
+    assert scheme.openid_config.http_client_config == {'trust_env': False}