fastapi-multiauth 0.1.0__py3-none-any.whl

fastapi_multiauth/oauth/client.py

@@ -0,0 +1,246 @@
+"""OAuth 2.0 / OIDC network operations: discovery, code exchange, userinfo."""
+
+import functools
+from typing import Any, Literal, NamedTuple
+
+import httpx
+from async_lru import alru_cache
+
+from .._http import DEFAULT_TIMEOUT, _get_json, _require_https
+from .._imports import require_extra
+from ..exceptions import OAuthDiscoveryError, OAuthExchangeError, OAuthUserinfoError
+
+__all__ = [
+    "OIDCEndpoints",
+    "oauth_exchange_code",
+    "oauth_fetch_userinfo",
+    "oauth_resolve_provider_urls",
+]
+
+_DISCOVERY_SUFFIX = "/.well-known/openid-configuration"
+_DISCOVERY_CACHE_TTL = 3600
+
+TokenEndpointAuthMethod = Literal["client_secret_post", "client_secret_basic"]
+
+
+class OIDCEndpoints(NamedTuple):
+    """Validated endpoint URLs from an OIDC discovery document.
+
+    All URLs are HTTPS-checked (loopback hosts excepted). Optional fields are
+    ``None`` when the provider does not advertise them.
+    """
+
+    authorization_endpoint: str
+    token_endpoint: str
+    userinfo_endpoint: str | None
+    jwks_uri: str | None
+    end_session_endpoint: str | None
+    issuer: str | None
+
+
+def _validate_issuer(discovery_url: str, issuer: Any) -> None:
+    """Check the discovery document claims the issuer it was fetched from."""
+    if not discovery_url.endswith(_DISCOVERY_SUFFIX):
+        return
+    expected = discovery_url.removesuffix(_DISCOVERY_SUFFIX).rstrip("/")
+    if not isinstance(issuer, str) or issuer.rstrip("/") != expected:
+        raise OAuthDiscoveryError(
+            f"discovery document issuer {issuer!r} does not match the "
+            f"expected issuer {expected!r} derived from the discovery URL"
+        )
+
+
+@functools.lru_cache(maxsize=1)
+def _import_httpx_oauth() -> Any:
+    """Import ``httpx_oauth.oauth2`` lazily (the optional ``oauth`` extra)."""
+    try:
+        from httpx_oauth import oauth2
+    except ImportError:  # pragma: no cover
+        require_extra("httpx-oauth", "oauth")
+    return oauth2
+
+
+@functools.lru_cache(maxsize=1)
+def _oauth2_client_class() -> type:
+    """Return an httpx-oauth ``OAuth2`` subclass with an explicit timeout."""
+
+    class _TimeoutOAuth2(_import_httpx_oauth().OAuth2):
+        """OAuth2 client whose HTTP calls run under an explicit timeout."""
+
+        def __init__(
+            self,
+            client_id: str,
+            client_secret: str,
+            access_token_endpoint: str,
+            timeout: float,
+            token_endpoint_auth_method: TokenEndpointAuthMethod,
+        ) -> None:
+            super().__init__(
+                client_id,
+                client_secret,
+                # Only the token endpoint is used; the authorization redirect
+                # is built by oauth_build_authorization_redirect().
+                authorize_endpoint="",
+                access_token_endpoint=access_token_endpoint,
+                token_endpoint_auth_method=token_endpoint_auth_method,
+            )
+            self._timeout = timeout
+
+        def get_httpx_client(self) -> httpx.AsyncClient:
+            return httpx.AsyncClient(timeout=self._timeout)
+
+    return _TimeoutOAuth2
+
+
+@alru_cache(maxsize=32, ttl=_DISCOVERY_CACHE_TTL)
+async def oauth_resolve_provider_urls(
+    discovery_url: str,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> OIDCEndpoints:
+    """Fetch the OIDC discovery document and return its validated endpoints.
+
+    Cached for one hour. The discovery URL must come from configuration, never
+    from request input (SSRF / cache-poisoning).
+
+    Args:
+        discovery_url: Provider's openid-configuration URL.
+        timeout: Discovery request timeout in seconds.
+
+    Returns:
+        Validated :class:`OIDCEndpoints`; optional fields are ``None`` when absent.
+
+    Raises:
+        ValueError: If *discovery_url* is not HTTPS.
+        OAuthDiscoveryError: If the document is unreachable, malformed, or
+            advertises non-HTTPS endpoints or a mismatched issuer.
+    """
+    _require_https(discovery_url, "OIDC discovery URL")
+    cfg = await _get_json(
+        discovery_url,
+        timeout=timeout,
+        error_cls=OAuthDiscoveryError,
+        description="OIDC discovery document",
+    )
+    if not isinstance(cfg, dict):
+        raise OAuthDiscoveryError("OIDC discovery document is not a JSON object")
+    _validate_issuer(discovery_url, cfg.get("issuer"))
+
+    def _optional(key: str) -> str | None:
+        url = cfg.get(key)
+        return None if url is None else _require_https(url, f"OIDC {key}")
+
+    try:
+        return OIDCEndpoints(
+            authorization_endpoint=_require_https(
+                cfg["authorization_endpoint"], "OIDC authorization_endpoint"
+            ),
+            token_endpoint=_require_https(cfg["token_endpoint"], "OIDC token_endpoint"),
+            userinfo_endpoint=_optional("userinfo_endpoint"),
+            jwks_uri=_optional("jwks_uri"),
+            end_session_endpoint=_optional("end_session_endpoint"),
+            issuer=cfg.get("issuer"),
+        )
+    except KeyError as exc:
+        raise OAuthDiscoveryError(
+            f"OIDC discovery document is missing the {exc.args[0]!r} endpoint"
+        ) from exc
+    except ValueError as exc:
+        raise OAuthDiscoveryError(str(exc)) from exc
+
+
+async def oauth_exchange_code(
+    *,
+    token_url: str,
+    code: str,
+    client_id: str,
+    client_secret: str,
+    redirect_uri: str,
+    required_scopes: str | None = None,
+    code_verifier: str | None = None,
+    token_endpoint_auth_method: TokenEndpointAuthMethod = "client_secret_post",  # noqa: S107 — method name, not a secret
+    timeout: float = DEFAULT_TIMEOUT,
+) -> dict[str, Any]:
+    """Exchange an authorization code for tokens and return the token response.
+
+    Delegates the exchange (including PKCE) to httpx-oauth (the ``oauth`` extra).
+
+    Args:
+        token_url: Provider's token endpoint.
+        code: Authorization code from the provider's callback.
+        client_id: OAuth application client ID.
+        client_secret: OAuth application client secret.
+        redirect_uri: Redirect URI used in the authorization request.
+        required_scopes: Space-separated scopes that must be present in the
+            token response (RFC 6749 §3.3).
+        code_verifier: PKCE code verifier matching the challenge sent earlier
+            (from :func:`~fastapi_multiauth.oauth.oauth_generate_pkce_pair`).
+        token_endpoint_auth_method: How credentials are sent — in the POST body
+            (``client_secret_post``, default) or as a Basic header.
+        timeout: Timeout in seconds for the token request.
+
+    Returns:
+        The full token response as a ``dict`` (``access_token`` plus whatever
+        else the provider returned).
+
+    Raises:
+        ValueError: If *token_url* is not HTTPS.
+        OAuthExchangeError: If the exchange is rejected or fails, grants a
+            non-bearer token, or omits a required scope.
+    """
+    _require_https(token_url, "OAuth token_url")
+
+    oauth_client = _oauth2_client_class()(
+        client_id, client_secret, token_url, timeout, token_endpoint_auth_method
+    )
+    try:
+        token_data = await oauth_client.get_access_token(
+            code, redirect_uri, code_verifier=code_verifier
+        )
+    except _import_httpx_oauth().GetAccessTokenError as exc:
+        raise OAuthExchangeError(str(exc)) from exc
+
+    token_type = token_data.get("token_type", "bearer")
+    if not isinstance(token_type, str) or token_type.lower() != "bearer":
+        raise OAuthExchangeError(f"unsupported token_type: {token_type!r}")
+
+    if required_scopes is not None:
+        scope = token_data.get("scope", "")
+        # Fail closed on a malformed (non-string) scope field.
+        granted = set(scope.split()) if isinstance(scope, str) else set()
+        missing = set(required_scopes.split()) - granted
+        if missing:
+            raise OAuthExchangeError(
+                f"provider did not grant required scopes: {missing}"
+            )
+
+    return dict(token_data)
+
+
+async def oauth_fetch_userinfo(
+    *,
+    userinfo_url: str,
+    access_token: str,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> dict[str, Any]:
+    """Fetch the userinfo payload with a bearer access token.
+
+    Args:
+        userinfo_url: Provider's userinfo endpoint.
+        access_token: Access token from :func:`oauth_exchange_code`.
+        timeout: Timeout in seconds for the userinfo request.
+
+    Returns:
+        The JSON payload returned by the userinfo endpoint as a plain ``dict``.
+
+    Raises:
+        ValueError: If *userinfo_url* is not HTTPS.
+        OAuthUserinfoError: If the endpoint fails or does not return JSON.
+    """
+    _require_https(userinfo_url, "OAuth userinfo_url")
+    return await _get_json(
+        userinfo_url,
+        timeout=timeout,
+        error_cls=OAuthUserinfoError,
+        description="userinfo",
+        headers={"Authorization": f"Bearer {access_token}"},
+    )

fastapi_multiauth/oauth/utils.py

@@ -0,0 +1,159 @@
+"""Pure OAuth helpers: state, PKCE, and the authorization redirect (no I/O)."""
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+from collections.abc import Sequence
+from urllib.parse import urlencode, urlsplit
+
+from fastapi import status
+from fastapi.responses import RedirectResponse
+
+__all__ = [
+    "oauth_build_authorization_redirect",
+    "oauth_decode_state",
+    "oauth_encode_state",
+    "oauth_generate_pkce_pair",
+    "oauth_generate_state_token",
+]
+
+
+def oauth_generate_state_token() -> str:
+    """Generate a cryptographically random CSRF token for the OAuth ``state`` parameter."""
+    return secrets.token_urlsafe(32)
+
+
+def oauth_generate_pkce_pair() -> tuple[str, str]:
+    """Generate a PKCE ``(code_verifier, code_challenge)`` pair (RFC 7636, S256).
+
+    Store the verifier server-side and pass it back to
+    :func:`~fastapi_multiauth.oauth.oauth_exchange_code` on the callback.
+
+    Returns:
+        A ``(code_verifier, code_challenge)`` tuple; the challenge is the
+        base64url SHA-256 of the verifier.
+    """
+    code_verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
+    code_challenge = base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+    return code_verifier, code_challenge
+
+
+def oauth_build_authorization_redirect(
+    authorization_url: str,
+    *,
+    client_id: str,
+    scopes: str,
+    redirect_uri: str,
+    destination: str,
+    state_token: str,
+    code_challenge: str | None = None,
+) -> RedirectResponse:
+    """Return an OAuth 2.0 authorization ``RedirectResponse`` (303 See Other).
+
+    Args:
+        authorization_url: Provider's authorization endpoint.
+        client_id: OAuth application client ID.
+        scopes: Space-separated list of requested scopes.
+        redirect_uri: URI the provider should redirect back to.
+        destination: Post-login URL (embedded in ``state``).
+        state_token: CSRF token from :func:`oauth_generate_state_token`; verify
+            it with :func:`oauth_decode_state` on the callback.
+        code_challenge: PKCE challenge from :func:`oauth_generate_pkce_pair`;
+            when set, ``code_challenge_method=S256`` is sent along.
+
+    Returns:
+        A :class:`~fastapi.responses.RedirectResponse` to the provider's
+        authorization page, retaining any query string already present.
+    """
+    params = {
+        "client_id": client_id,
+        "response_type": "code",
+        "scope": scopes,
+        "redirect_uri": redirect_uri,
+        "state": oauth_encode_state(destination, state_token),
+    }
+    if code_challenge is not None:
+        params["code_challenge"] = code_challenge
+        params["code_challenge_method"] = "S256"
+    sep = "&" if urlsplit(authorization_url).query else "?"
+    return RedirectResponse(
+        f"{authorization_url}{sep}{urlencode(params)}",
+        status_code=status.HTTP_303_SEE_OTHER,
+    )
+
+
+def oauth_encode_state(url: str, state_token: str) -> str:
+    """Encode a destination URL and CSRF token into an OAuth ``state`` parameter.
+
+    Args:
+        url: Post-login destination URL.
+        state_token: CSRF token from :func:`oauth_generate_state_token`.
+    """
+    payload = json.dumps({"n": state_token, "d": url}, separators=(",", ":"))
+    return base64.urlsafe_b64encode(payload.encode()).decode()
+
+
+def _destination_allowed(destination: str, allowed_hosts: Sequence[str]) -> bool:
+    """Check a decoded destination against the open-redirect allowlist."""
+    # Browsers normalize backslashes to slashes, turning "/\evil.com" into a
+    # scheme-relative redirect — reject them outright.
+    if "\\" in destination:
+        return False
+    parsed = urlsplit(destination)
+    if not parsed.scheme and not parsed.netloc:
+        return destination.startswith("/") and not destination.startswith("//")
+    if parsed.scheme not in ("http", "https"):
+        return False
+    return parsed.hostname in allowed_hosts
+
+
+def oauth_decode_state(
+    state: str | None,
+    *,
+    expected_state_token: str,
+    fallback: str,
+    allowed_hosts: Sequence[str] | None = (),
+) -> str:
+    """Decode and CSRF-verify an OAuth ``state`` parameter (constant-time).
+
+    The stored token is single-use: delete it from the session after this call,
+    matched or not, so a captured callback cannot be replayed.
+
+    Args:
+        state: Raw ``state`` query parameter from the callback.
+        expected_state_token: Token stored before the authorization redirect;
+            a mismatch returns ``fallback``.
+        fallback: URL returned when ``state`` is absent, malformed, or fails
+            verification.
+        allowed_hosts: Open-redirect guard — the decoded destination must be a
+            relative path or an absolute http(s) URL whose host is listed. The
+            default (``()``) allows relative paths only; ``None`` disables the check.
+
+    Returns:
+        The destination URL embedded in ``state``, or ``fallback``.
+    """
+    if not state or state == "null":  # "null" guards against JS JSON.stringify(null)
+        return fallback
+    try:
+        padded = state + "=" * (-len(state) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(padded).decode("utf-8"))
+        if not isinstance(payload, dict):
+            return fallback
+        token = payload.get("n", "")
+        if not isinstance(token, str) or not hmac.compare_digest(
+            token.encode(), expected_state_token.encode()
+        ):
+            return fallback
+        destination = payload["d"]
+        if not isinstance(destination, str):
+            return fallback
+        if allowed_hosts is not None and not _destination_allowed(
+            destination, allowed_hosts
+        ):
+            return fallback
+        return destination
+    except (UnicodeDecodeError, ValueError, KeyError):
+        return fallback

fastapi_multiauth/sources/__init__.py

@@ -0,0 +1,17 @@
+"""Built-in authentication source implementations."""
+
+from .basic import HTTPBasicAuth
+from .bearer import HTTPBearerAuth
+from .cookie import APIKeyCookieAuth
+from .header import APIKeyHeaderAuth
+from .multi import MultiAuth
+from .query import APIKeyQueryAuth
+
+__all__ = [
+    "APIKeyCookieAuth",
+    "APIKeyHeaderAuth",
+    "APIKeyQueryAuth",
+    "HTTPBasicAuth",
+    "HTTPBearerAuth",
+    "MultiAuth",
+]

fastapi_multiauth/sources/basic.py

@@ -0,0 +1,68 @@
+"""HTTP Basic authentication source."""
+
+import base64
+from typing import Any, Callable
+
+from fastapi import Request
+from fastapi.security import HTTPBasic
+
+from fastapi_multiauth.exceptions import UnauthorizedError
+
+from ..abc import ValidatedAuthSource
+from ..utils import authorization_credential
+
+
+class HTTPBasicAuth(ValidatedAuthSource):
+    """HTTP Basic authentication source (wraps ``HTTPBasic`` for OpenAPI, RFC 7617).
+
+    The validator is called as ``await validator(username, password, **kwargs)``;
+    compare the password in constant time (``secrets.compare_digest``).
+
+    Args:
+        validator: Sync or async callable receiving ``(username, password)`` and
+            returning the identity; raises
+            :class:`~fastapi_multiauth.exceptions.UnauthorizedError` on failure.
+        realm: Optional protection-space name for the ``WWW-Authenticate`` challenge.
+        scheme_name: OpenAPI security scheme name (default ``HTTPBasic``).
+        **kwargs: Extra keyword arguments forwarded to the validator on every call.
+    """
+
+    def __init__(
+        self,
+        validator: Callable[..., Any],
+        *,
+        realm: str | None = None,
+        scheme_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._realm = realm
+        super().__init__(
+            validator,
+            HTTPBasic(auto_error=False, scheme_name=scheme_name),
+            **kwargs,
+        )
+
+    def www_authenticate(self) -> str:
+        """``Basic`` challenge, with the realm when configured (RFC 7617 §2)."""
+        if self._realm is not None:
+            return f'Basic realm="{self._realm}"'
+        return "Basic"
+
+    async def extract(self, request: Request) -> str | None:
+        """Return the base64 credentials blob, or ``None`` when absent or empty.
+
+        The ``Basic`` scheme is matched case-insensitively; decoding and the
+        split happen in :meth:`authenticate`, so a malformed blob is a 401.
+        """
+        return authorization_credential(request, "basic")
+
+    async def authenticate_scoped(self, credential: str, scopes: list[str]) -> Any:
+        """Decode the blob, forwarding route-declared scopes to the validator."""
+        try:
+            decoded = base64.b64decode(credential, validate=True).decode("utf-8")
+        except ValueError:  # covers binascii.Error and UnicodeDecodeError
+            raise UnauthorizedError() from None
+        username, sep, password = decoded.partition(":")
+        if not sep:
+            raise UnauthorizedError()
+        return await self._call_validator(username, password, scopes=scopes)

fastapi_multiauth/sources/bearer.py

@@ -0,0 +1,80 @@
+"""Bearer token authentication source."""
+
+import secrets
+from typing import Any, Callable
+
+from fastapi import Request
+from fastapi.security import HTTPBearer
+
+from fastapi_multiauth.exceptions import UnauthorizedError
+
+from ..abc import ValidatedAuthSource
+from ..utils import authorization_credential
+
+
+class HTTPBearerAuth(ValidatedAuthSource):
+    """Bearer token authentication source (wraps ``HTTPBearer`` for OpenAPI).
+
+    The validator is called as ``await validator(credential, **kwargs)``.
+
+    Args:
+        validator: Sync or async callable returning the identity; raises
+            :class:`~fastapi_multiauth.exceptions.UnauthorizedError` on failure.
+        prefix: Optional token prefix (e.g. ``"user_"``); only tokens with this
+            prefix are matched, and the prefix is kept in the validated value.
+        scheme_name: OpenAPI security scheme name (default ``HTTPBearer``); give
+            each source a distinct name when several appear in the same app.
+        **kwargs: Extra keyword arguments forwarded to the validator on every call.
+    """
+
+    def __init__(
+        self,
+        validator: Callable[..., Any],
+        *,
+        prefix: str | None = None,
+        scheme_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._prefix = prefix
+        super().__init__(
+            validator,
+            HTTPBearer(auto_error=False, scheme_name=scheme_name),
+            **kwargs,
+        )
+
+    def www_authenticate(self) -> str:
+        """``Bearer`` challenge per RFC 6750 §3."""
+        return "Bearer"
+
+    async def extract(self, request: Request) -> str | None:
+        """Return the bearer token, or ``None`` when absent, empty, or mismatched.
+
+        The ``Bearer`` scheme is matched case-insensitively; the prefix, when
+        configured, is kept in the returned value.
+        """
+        token = authorization_credential(request, "bearer")
+        if token is None:
+            return None
+        if self._prefix is not None and not token.startswith(self._prefix):
+            return None
+        return token
+
+    async def authenticate_scoped(self, credential: str, scopes: list[str]) -> Any:
+        """Validate the credential, re-checking the prefix and forwarding scopes."""
+        if self._prefix is not None and not credential.startswith(self._prefix):
+            raise UnauthorizedError()
+        return await self._call_validator(credential, scopes=scopes)
+
+    def generate_token(self, nbytes: int = 32) -> str:
+        """Generate a secure URL-safe random token, prefixed when configured.
+
+        Args:
+            nbytes: Number of random bytes before base64 encoding (default 32).
+
+        Returns:
+            A ready-to-use token string (e.g. ``"user_Xk3..."``).
+        """
+        token = secrets.token_urlsafe(nbytes)
+        if self._prefix is not None:
+            return f"{self._prefix}{token}"
+        return token