Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python
15.2 KB
Raw Blame
"""JWT signature verification utilities for OAuth tokens."""

from __future__ import annotations

from typing import Any, cast

import httpx
import jwt
from cachetools import TTLCache
from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicKey
from jwt.algorithms import RSAAlgorithm

from utils.logging_config import get_logger

logger = get_logger(__name__)

# JWKS cache: 1 hour TTL, max 10 entries
_jwks_cache: TTLCache = TTLCache(maxsize=10, ttl=3600)

# JWKS endpoints
GOOGLE_JWKS_URL = "https://www.googleapis.com/oauth2/v3/certs"
# v2 tokens (iss = login.microsoftonline.com/…/v2.0) use /v2.0/keys.
# v1 tokens (iss = sts.windows.net/…)              use /keys (no /v2.0/).
# Selected at runtime based on the `ver` claim.
MICROSOFT_JWKS_URL_V2_TEMPLATE = "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys"
MICROSOFT_JWKS_URL_V1_TEMPLATE = "https://login.microsoftonline.com/{tenant}/discovery/keys"


class JWTVerificationError(Exception):
    """Base exception for JWT verification errors."""

    pass


class InvalidSignatureError(JWTVerificationError):
    """JWT signature is invalid."""

    pass


class ExpiredTokenError(JWTVerificationError):
    """JWT token has expired."""

    pass


class InvalidAudienceError(JWTVerificationError):
    """JWT audience claim is invalid."""

    pass


class InvalidIssuerError(JWTVerificationError):
    """JWT issuer claim is invalid."""

    pass


def _fetch_jwks(url: str) -> dict[str, Any]:
    """
    Fetch JWKS from URL with caching.

    Args:
        url: JWKS endpoint URL

    Returns:
        JWKS dictionary

    Raises:
        JWTVerificationError: If JWKS fetch fails
    """
    # Check cache first
    if url in _jwks_cache:
        logger.debug(f"JWKS cache hit for {url}")
        return _jwks_cache[url]

    # Fetch from endpoint
    try:
        logger.debug(f"Fetching JWKS from {url}")
        response = httpx.get(url, timeout=5.0)
        response.raise_for_status()
        jwks = response.json()

        # Cache the result
        _jwks_cache[url] = jwks
        logger.debug(f"JWKS cached for {url}")

        return jwks
    except Exception as e:
        logger.error(f"Failed to fetch JWKS from {url}", error=str(e))
        raise JWTVerificationError(f"Failed to fetch JWKS: {e}") from e


def _get_signing_key(token: str, jwks: dict[str, Any]) -> Any:
    """
    Extract signing key from JWKS based on token header.

    Args:
        token: JWT token
        jwks: JWKS dictionary

    Returns:
        RSA public key object

    Raises:
        JWTVerificationError: If key not found
    """
    try:
        # Decode header without verification to get kid
        unverified_header = jwt.get_unverified_header(token)
        kid = unverified_header.get("kid")

        if not kid:
            raise JWTVerificationError("Token header missing 'kid' field")

        # Find matching key in JWKS
        for key in jwks.get("keys", []):
            if key.get("kid") == kid:
                # Use PyJWT's built-in JWK to PEM conversion
                public_key = RSAAlgorithm.from_jwk(key)
                return public_key

        raise JWTVerificationError(f"Signing key with kid '{kid}' not found in JWKS")

    except jwt.DecodeError as e:
        raise JWTVerificationError(f"Failed to decode token header: {e}") from e


def verify_google_id_token(token: str, client_id: str) -> dict[str, Any]:
    """
    Verify Google ID token with FULL validation.

    Performs:
    - Signature verification using Google's JWKS
    - Issuer validation (accounts.google.com)
    - Expiration validation
    - Audience validation (requires client_id)

    Args:
        token: Google ID token (JWT)
        client_id: Expected audience (Google OAuth client ID)

    Returns:
        Verified token claims

    Raises:
        InvalidSignatureError: If signature is invalid
        ExpiredTokenError: If token has expired
        InvalidAudienceError: If audience doesn't match
        InvalidIssuerError: If issuer is invalid
        JWTVerificationError: For other verification failures
    """
    if not client_id:
        raise JWTVerificationError("client_id is required for Google ID token verification")

    try:
        # Fetch JWKS
        jwks = _fetch_jwks(GOOGLE_JWKS_URL)

        # Get signing key
        signing_key = _get_signing_key(token, jwks)

        # Verify token with FULL validation
        claims = jwt.decode(
            token,
            signing_key,
            algorithms=["RS256"],
            audience=client_id,
            issuer=["https://accounts.google.com", "accounts.google.com"],
            options={
                "verify_signature": True,
                "verify_exp": True,
                "verify_aud": True,
                "verify_iss": True,
            },
        )

        logger.debug("Google ID token verified successfully")
        return claims

    except jwt.InvalidSignatureError as e:
        logger.warning("Google ID token has invalid signature", error=str(e))
        raise InvalidSignatureError(f"Invalid signature: {e}") from e
    except jwt.ExpiredSignatureError as e:
        logger.warning("Google ID token has expired", error=str(e))
        raise ExpiredTokenError(f"Token expired: {e}") from e
    except jwt.InvalidAudienceError as e:
        logger.warning("Google ID token has invalid audience", error=str(e))
        raise InvalidAudienceError(f"Invalid audience: {e}") from e
    except jwt.InvalidIssuerError as e:
        logger.warning("Google ID token has invalid issuer", error=str(e))
        raise InvalidIssuerError(f"Invalid issuer: {e}") from e
    except JWTVerificationError:
        raise
    except Exception as e:
        logger.error("Google ID token verification failed", error=str(e))
        raise JWTVerificationError(f"Verification failed: {e}") from e


def _resolve_ms_jwks_url(tenant_id: str, token_version: str) -> str:
    """
    Return the correct JWKS URL for the given tenant and token version.

    Per Microsoft docs: v1.0 tokens must be validated against the v1 metadata
    endpoint (no /v2.0/), v2.0 tokens against the v2 endpoint.
    """
    if token_version == "1.0":
        return MICROSOFT_JWKS_URL_V1_TEMPLATE.format(tenant=tenant_id)
    return MICROSOFT_JWKS_URL_V2_TEMPLATE.format(tenant=tenant_id)


# Known Microsoft issuer URL prefixes used when the JWKS key entry omits "issuer".
_MS_ISSUER_PREFIXES = (
    "https://login.microsoftonline.com/",
    "https://sts.windows.net/",
)


def _validate_ms_issuer(issuer: str, token_tid: str, signing_key_issuer: str | None) -> None:
    """
    Validate the token issuer following Microsoft's documented algorithm:

    1. When the JWKS key entry carries an ``issuer`` property, substitute
       ``{tenantid}`` and require an exact match against the token ``iss`` claim
       (Microsoft's documented multi-tenant issuer validation algorithm).
    2. When the key entry omits ``issuer`` (common for tenant-specific JWKS
       endpoints), fall back to verifying that ``iss`` starts with a known
       Microsoft issuer URL prefix — preventing cross-issuer attacks without
       rejecting otherwise valid tokens.
    3. In both cases, confirm that the ``tid`` claim matches the tenant segment
       embedded in the ``iss`` URL.

    Raises InvalidIssuerError on any failure.
    """
    if signing_key_issuer:
        # Keys from the tenant-independent endpoint carry "{tenantid}" as a
        # placeholder; tenant-specific keys may carry a literal issuer URL.
        resolved_key_issuer = signing_key_issuer.replace("{tenantid}", token_tid)
        if resolved_key_issuer != issuer:
            raise InvalidIssuerError(
                f"Token issuer {issuer!r} does not match signing key issuer "
                f"{resolved_key_issuer!r} (tid={token_tid!r})"
            )
    else:
        # JWKS key entry has no issuer field — validate against known MS prefixes.
        if not any(issuer.startswith(prefix) for prefix in _MS_ISSUER_PREFIXES):
            raise InvalidIssuerError(
                f"Token issuer {issuer!r} is not a recognised Microsoft issuer URL"
            )

    # Confirm the tid claim matches the tenant GUID segment in the iss URL.
    # Handles both v2 form (login.microsoftonline.com/{tid}/v2.0)
    # and v1 form (sts.windows.net/{tid}/).
    iss_segments = issuer.rstrip("/").split("/")
    tid_in_iss = next(
        (seg for seg in iss_segments if seg and "-" in seg and len(seg) == 36),
        None,
    )
    if tid_in_iss and tid_in_iss != token_tid:
        raise InvalidIssuerError(
            f"Tenant ID in issuer URL {tid_in_iss!r} does not match tid claim {token_tid!r}"
        )


def verify_microsoft_access_token(
    token: str,
    client_id: str,
    tenant_id: str | None = None,
    allowed_tenant_ids: set[str] | None = None,
) -> dict[str, Any]:
    """
    Verify a Microsoft access token following the Microsoft identity platform docs.

    Scope of validation:

    - Validate only tokens issued to this OpenRAG application. Microsoft Graph
      access tokens are intended for Graph to validate, so callers that only pass
      a token through to Graph should not use this helper.
    - Perform full validation: signature, expiry, audience, issuer, and optional
      tenant allow-list.

    Signature validation details (when performed):
    - JWKS endpoint selected by token version: v1 tokens (/discovery/keys),
      v2 tokens (/discovery/v2.0/keys).
    - Signing key looked up by kid header claim.
    - Issuer validated against the signing key's own issuer property in the JWKS
      document, with {tenantid} placeholder substituted by the token's tid claim
      (Microsoft's documented multi-tenant issuer validation algorithm).
    - tid segment of iss URL verified to match tid claim.

    Optionally (business policy, not a standards requirement):
    - Tenant allow-list enforced when MICROSOFT_ALLOWED_TENANT_IDS is configured.

    Args:
        token:              Raw JWT access token string.
        client_id:          OpenRAG's Azure AD app client ID.
        tenant_id:          Optional hint for tenant-specific JWKS endpoint
                            selection. When omitted, the common endpoint is used.
        allowed_tenant_ids: Optional set of permitted Azure AD tenant UUIDs.

    Returns:
        Verified token claims dict.

    Raises:
        InvalidSignatureError: Signature does not match the signing key.
        ExpiredTokenError:     Token exp claim is in the past.
        InvalidAudienceError:  aud matches our client_id but fails verification.
        InvalidIssuerError:    iss / tid mismatch, or tenant not in allow-list.
        JWTVerificationError:  Any other verification failure.
    """
    if not client_id:
        raise JWTVerificationError("client_id is required for Microsoft access token verification")

    try:
        # Use the caller's tenant hint when available; otherwise validate against
        # Microsoft's common endpoint. Try v2 first, then v1, without trusting
        # unverified claims to choose the metadata endpoint.
        jwks_tenant = tenant_id or "common"
        jwks_candidates = (
            ("2.0", _resolve_ms_jwks_url(jwks_tenant, "2.0")),
            ("1.0", _resolve_ms_jwks_url(jwks_tenant, "1.0")),
        )

        # Find the signing key by kid and record its issuer property from the
        # JWKS document — needed for Microsoft's documented issuer validation.
        last_key_error: JWTVerificationError | None = None
        claims: dict[str, Any] | None = None
        token_version = "2.0"

        for candidate_version, jwks_url in jwks_candidates:
            jwks = _fetch_jwks(jwks_url)
            try:
                signing_key = cast(RSAPublicKey, _get_signing_key(token, jwks))
            except JWTVerificationError as e:
                last_key_error = e
                continue

            unverified_header = jwt.get_unverified_header(token)
            kid = unverified_header.get("kid")
            signing_key_entry = next(
                (k for k in jwks.get("keys", []) if k.get("kid") == kid),
                None,
            )
            if signing_key_entry is None:
                last_key_error = JWTVerificationError(
                    f"Signing key with kid '{kid}' not found in JWKS"
                )
                continue
            signing_key_issuer = signing_key_entry.get("issuer") or None

            # Verify signature, expiry, and audience.
            # verify_iss=False: issuer validated manually below per Microsoft's algorithm.
            claims = jwt.decode(
                token,
                signing_key,
                algorithms=["RS256"],
                audience=client_id,
                options={
                    "verify_signature": True,
                    "verify_exp": True,
                    "verify_aud": True,
                    "verify_iss": False,
                    "require": ["exp"],
                },
            )
            verified_tid = claims.get("tid", "")
            if not verified_tid:
                raise JWTVerificationError("Token is missing the 'tid' claim.")
            issuer = claims.get("iss", "")
            try:
                _validate_ms_issuer(issuer, verified_tid, signing_key_issuer)
            except InvalidIssuerError as e:
                last_key_error = e
                claims = None
                continue

            token_version = candidate_version
            break

        if claims is None:
            if last_key_error is not None:
                raise last_key_error
            raise JWTVerificationError("No Microsoft JWKS signing key candidates were available")

        verified_tid = claims.get("tid", "")

        # Tenant allow-list (optional business policy).
        if allowed_tenant_ids is not None and verified_tid not in allowed_tenant_ids:
            logger.warning(
                "Microsoft token tenant not in allow-list",
                verified_tid=verified_tid,
            )
            raise InvalidIssuerError(
                f"Tenant '{verified_tid}' is not in the configured allowed tenant list"
            )

        logger.debug(
            "Microsoft access token verified",
            tenant=verified_tid,
            token_version=token_version,
        )
        return claims

    except jwt.InvalidSignatureError as e:
        logger.warning("Microsoft access token has invalid signature", error=str(e))
        raise InvalidSignatureError(f"Invalid signature: {e}") from e
    except jwt.ExpiredSignatureError as e:
        logger.warning("Microsoft access token has expired", error=str(e))
        raise ExpiredTokenError(f"Token expired: {e}") from e
    except jwt.InvalidAudienceError as e:
        logger.warning("Microsoft access token has invalid audience", error=str(e))
        raise InvalidAudienceError(f"Invalid audience: {e}") from e
    except (jwt.InvalidIssuerError, InvalidIssuerError) as e:
        logger.warning("Microsoft access token has invalid issuer", error=str(e))
        raise InvalidIssuerError(f"Invalid issuer: {e}") from e
    except JWTVerificationError:
        raise
    except Exception as e:
        logger.error("Microsoft access token verification failed", error=str(e))
        raise JWTVerificationError(f"Verification failed: {e}") from e


def clear_jwks_cache():
    """Clear the JWKS cache. Useful for testing."""
    _jwks_cache.clear()
    logger.debug("JWKS cache cleared")


# Made with Bob