vibrant-auth-middleware-fastapi 0.1.0__tar.gz

vibrant_auth_middleware_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: vibrant-auth-middleware-fastapi
+Version: 0.1.0
+Summary: FastAPI authentication middleware with JWT verification and Azure integration
+Author-email: Vibrant Engineering <engineering@vibrant.com>
+License: ISC
+Requires-Python: >=3.11
+Requires-Dist: azure-appconfiguration<2.0.0,>=1.7.0
+Requires-Dist: azure-identity<2.0.0,>=1.15.0
+Requires-Dist: azure-keyvault-secrets<5.0.0,>=4.8.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: python-jose[cryptography]<4.0.0,>=3.3.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<0.20.0,>=0.19.0; extra == 'dev'
+Requires-Dist: pytest<8.0.0,>=7.1.2; extra == 'dev'
+Requires-Dist: ruff<1.0.0,>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Vibrant Auth Middleware for FastAPI
+
+JWT authentication middleware with Azure integration for FastAPI applications.
+
+## Features
+
+- JWT verification with automatic algorithm detection (HS256/RS256)
+- Azure Key Vault integration for HS256 secrets
+- Azure App Configuration integration for RS256 public keys
+- FastAPI dependency injection support
+- Cookie-based authentication support (access_token + token_type)
+- Automatic fallback from Authorization header to cookies
+- Caching for improved performance
+
+## Installation
+
+```bash
+pip install vibrant-auth-middleware
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI, Depends
+from vibrant_auth_middleware import get_user_id
+
+app = FastAPI()
+
+@app.get("/protected")
+def protected_route(user_id: str = Depends(get_user_id)):
+    return {"user_id": user_id}
+```
+
+## Configuration
+
+Configure via environment variables:
+
+### HS256 (Symmetric Key)
+
+```bash
+# Option 1: Direct secret
+JWT_SECRET_KEY=your-secret-key
+
+# Option 2: Azure Key Vault
+AZURE_KEY_VAULT_URI=https://your-vault.vault.azure.net/
+AZURE_KEY_VAULT_JWT_SECRET=jwt-secret-key  # optional, default: "jwt-secret-key"
+```
+
+### RS256 (Asymmetric Key)
+
+```bash
+# Option 1: Direct public key
+JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
+
+# Option 2: Azure App Configuration
+AZURE_APP_CONFIG_ENDPOINT=https://your-config.azconfig.io
+# or
+AZURE_APP_CONFIG_CONNECTION_STRING=Endpoint=...
+AZURE_APP_CONFIG_JWT_KEY=jwt-public-key  # optional, default: "jwt-public-key"
+```
+
+### JWT Verification Options
+
+```bash
+JWT_AUDIENCE=your-audience      # optional
+JWT_ISSUER=your-issuer          # optional
+JWT_LEEWAY=0                    # optional, seconds for time validation
+```
+
+### Azure Authentication
+
+```bash
+APP_ENV=production  # Uses WorkloadIdentityCredential
+APP_ENV=dev         # Uses DefaultAzureCredential (default)
+```
+
+## API Reference
+
+### `get_user_id`
+
+FastAPI dependency that extracts and validates user_id from JWT token. Supports both Authorization header and cookie-based authentication with automatic fallback.
+
+**Authentication methods (in order of priority):**
+1. Authorization header: `Authorization: Bearer <token>`
+2. Cookies: `access_token` + `token_type` (token_type must be "Bearer")
+
+```python
+@app.get("/me")
+def get_me(user_id: str = Depends(get_user_id)):
+    return {"user_id": user_id}
+```
+
+### `get_user`
+
+FastAPI dependency that extracts and validates the full JWT payload. Supports both Authorization header and cookie-based authentication with automatic fallback.
+
+```python
+from vibrant_auth_middleware import get_user
+
+@app.get("/me")
+def get_me(user: dict = Depends(get_user)):
+    return {"user": user}
+```
+
+### `get_user_id_from_cookie`
+
+FastAPI dependency that extracts and validates user_id exclusively from cookies. Requires both `access_token` and `token_type` cookies, where `token_type` must be "Bearer".
+
+```python
+from vibrant_auth_middleware import get_user_id_from_cookie
+
+@app.get("/me")
+def get_me(user_id: str = Depends(get_user_id_from_cookie)):
+    return {"user_id": user_id}
+```
+
+**Expected cookies:**
+- `access_token`: The JWT token
+- `token_type`: Must be "Bearer"
+
+### `verify_jwt_token`
+
+Verify a JWT token and return its payload.
+
+```python
+from vibrant_auth_middleware import verify_jwt_token
+
+payload = verify_jwt_token(token)
+```
+
+### `get_user_id_from_token`
+
+Extract user_id from a verified JWT token.
+
+```python
+from vibrant_auth_middleware import get_user_id_from_token
+
+user_id = get_user_id_from_token(token)
+```
+
+### `get_token_payload`
+
+Get the full verified token payload.
+
+```python
+from vibrant_auth_middleware import get_token_payload
+
+payload = get_token_payload(token)
+```
+
+## License
+
+ISC

vibrant_auth_middleware_fastapi-0.1.0/README.md

@@ -0,0 +1,153 @@
+# Vibrant Auth Middleware for FastAPI
+
+JWT authentication middleware with Azure integration for FastAPI applications.
+
+## Features
+
+- JWT verification with automatic algorithm detection (HS256/RS256)
+- Azure Key Vault integration for HS256 secrets
+- Azure App Configuration integration for RS256 public keys
+- FastAPI dependency injection support
+- Cookie-based authentication support (access_token + token_type)
+- Automatic fallback from Authorization header to cookies
+- Caching for improved performance
+
+## Installation
+
+```bash
+pip install vibrant-auth-middleware
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI, Depends
+from vibrant_auth_middleware import get_user_id
+
+app = FastAPI()
+
+@app.get("/protected")
+def protected_route(user_id: str = Depends(get_user_id)):
+    return {"user_id": user_id}
+```
+
+## Configuration
+
+Configure via environment variables:
+
+### HS256 (Symmetric Key)
+
+```bash
+# Option 1: Direct secret
+JWT_SECRET_KEY=your-secret-key
+
+# Option 2: Azure Key Vault
+AZURE_KEY_VAULT_URI=https://your-vault.vault.azure.net/
+AZURE_KEY_VAULT_JWT_SECRET=jwt-secret-key  # optional, default: "jwt-secret-key"
+```
+
+### RS256 (Asymmetric Key)
+
+```bash
+# Option 1: Direct public key
+JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
+
+# Option 2: Azure App Configuration
+AZURE_APP_CONFIG_ENDPOINT=https://your-config.azconfig.io
+# or
+AZURE_APP_CONFIG_CONNECTION_STRING=Endpoint=...
+AZURE_APP_CONFIG_JWT_KEY=jwt-public-key  # optional, default: "jwt-public-key"
+```
+
+### JWT Verification Options
+
+```bash
+JWT_AUDIENCE=your-audience      # optional
+JWT_ISSUER=your-issuer          # optional
+JWT_LEEWAY=0                    # optional, seconds for time validation
+```
+
+### Azure Authentication
+
+```bash
+APP_ENV=production  # Uses WorkloadIdentityCredential
+APP_ENV=dev         # Uses DefaultAzureCredential (default)
+```
+
+## API Reference
+
+### `get_user_id`
+
+FastAPI dependency that extracts and validates user_id from JWT token. Supports both Authorization header and cookie-based authentication with automatic fallback.
+
+**Authentication methods (in order of priority):**
+1. Authorization header: `Authorization: Bearer <token>`
+2. Cookies: `access_token` + `token_type` (token_type must be "Bearer")
+
+```python
+@app.get("/me")
+def get_me(user_id: str = Depends(get_user_id)):
+    return {"user_id": user_id}
+```
+
+### `get_user`
+
+FastAPI dependency that extracts and validates the full JWT payload. Supports both Authorization header and cookie-based authentication with automatic fallback.
+
+```python
+from vibrant_auth_middleware import get_user
+
+@app.get("/me")
+def get_me(user: dict = Depends(get_user)):
+    return {"user": user}
+```
+
+### `get_user_id_from_cookie`
+
+FastAPI dependency that extracts and validates user_id exclusively from cookies. Requires both `access_token` and `token_type` cookies, where `token_type` must be "Bearer".
+
+```python
+from vibrant_auth_middleware import get_user_id_from_cookie
+
+@app.get("/me")
+def get_me(user_id: str = Depends(get_user_id_from_cookie)):
+    return {"user_id": user_id}
+```
+
+**Expected cookies:**
+- `access_token`: The JWT token
+- `token_type`: Must be "Bearer"
+
+### `verify_jwt_token`
+
+Verify a JWT token and return its payload.
+
+```python
+from vibrant_auth_middleware import verify_jwt_token
+
+payload = verify_jwt_token(token)
+```
+
+### `get_user_id_from_token`
+
+Extract user_id from a verified JWT token.
+
+```python
+from vibrant_auth_middleware import get_user_id_from_token
+
+user_id = get_user_id_from_token(token)
+```
+
+### `get_token_payload`
+
+Get the full verified token payload.
+
+```python
+from vibrant_auth_middleware import get_token_payload
+
+payload = get_token_payload(token)
+```
+
+## License
+
+ISC

vibrant_auth_middleware_fastapi-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "vibrant-auth-middleware-fastapi"
+version = "0.1.0"
+description = "FastAPI authentication middleware with JWT verification and Azure integration"
+authors = [{ name = "Vibrant Engineering", email = "engineering@vibrant.com" }]
+license = { text = "ISC" }
+requires-python = ">=3.11"
+readme = "README.md"
+dependencies = [
+    "fastapi>=0.100.0",
+    "python-jose[cryptography]>=3.3.0,<4.0.0",
+    "azure-appconfiguration>=1.7.0,<2.0.0",
+    "azure-identity>=1.15.0,<2.0.0",
+    "azure-keyvault-secrets>=4.8.0,<5.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.1.2,<8.0.0",
+    "ruff>=0.9.0,<1.0.0",
+    "pytest-asyncio>=0.19.0,<0.20.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vibrant_auth_middleware"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

vibrant_auth_middleware_fastapi-0.1.0/src/vibrant_auth_middleware/__init__.py

@@ -0,0 +1,63 @@
+"""
+Vibrant Auth Middleware for FastAPI.
+
+A library for JWT authentication with Azure integration, supporting both
+HS256 (symmetric) and RS256 (asymmetric) algorithms.
+
+Usage:
+    ```python
+    from fastapi import FastAPI, Depends
+    from vibrant_auth_middleware import get_user_id
+
+    app = FastAPI()
+
+    @app.get("/protected")
+    def protected_route(user_id: str = Depends(get_user_id)):
+        return {"user_id": user_id}
+    ```
+
+Environment Variables:
+    JWT_SECRET_KEY: HS256 secret key (or use Azure Key Vault)
+    JWT_PUBLIC_KEY: RS256 public key (or use Azure App Configuration)
+    AZURE_KEY_VAULT_URI: Azure Key Vault URI for HS256 secret
+    AZURE_KEY_VAULT_JWT_SECRET: Secret name in Key Vault (default: "jwt-secret-key")
+    AZURE_APP_CONFIG_ENDPOINT: Azure App Configuration endpoint for RS256 public key
+    AZURE_APP_CONFIG_CONNECTION_STRING: App Configuration connection string
+    AZURE_APP_CONFIG_JWT_KEY: Key name in App Configuration (default: "jwt-public-key")
+    JWT_AUDIENCE: Optional audience claim for token verification
+    JWT_ISSUER: Optional issuer claim for token verification
+    JWT_LEEWAY: Leeway in seconds for time validation (default: 0)
+    APP_ENV: "production" for WorkloadIdentityCredential, else DefaultAzureCredential
+"""
+
+from .config import JWTConfig, jwt_config
+from .dependencies import (
+    OAUTH2_SCHEME,
+    OAuth2PasswordToken,
+    get_user,
+    get_user_id,
+    get_user_id_from_cookie,
+)
+from .jwt_auth import (
+    get_token_payload,
+    get_user_id_from_token,
+    verify_jwt_token,
+)
+
+__all__ = [
+    # Configuration
+    "JWTConfig",
+    "jwt_config",
+    # FastAPI dependencies
+    "get_user",
+    "get_user_id",
+    "get_user_id_from_cookie",
+    "OAUTH2_SCHEME",
+    "OAuth2PasswordToken",
+    # Core functions
+    "verify_jwt_token",
+    "get_user_id_from_token",
+    "get_token_payload",
+]
+
+__version__ = "0.1.0"

vibrant_auth_middleware_fastapi-0.1.0/src/vibrant_auth_middleware/config.py

@@ -0,0 +1,41 @@
+"""
+Configuration for JWT authentication.
+
+Loads settings from environment variables for JWT verification,
+supporting both HS256 (symmetric) and RS256 (asymmetric) algorithms.
+"""
+
+import os
+from typing import Optional
+
+
+class JWTConfig:
+    """JWT configuration settings loaded from environment variables."""
+
+    def __init__(self):
+        # HS256 Secret Key (from Azure Key Vault or env var)
+        self.jwt_secret_key: Optional[str] = os.getenv("JWT_SECRET_KEY")
+        self.azure_key_vault_secret_name: str = os.getenv(
+            "AZURE_KEY_VAULT_JWT_SECRET", "jwt-secret-key"
+        )
+        self.azure_key_vault_uri: Optional[str] = os.getenv("AZURE_KEY_VAULT_URI")
+
+        # RS256 Public Key (from Azure App Configuration or env var)
+        self.jwt_public_key: Optional[str] = os.getenv("JWT_PUBLIC_KEY")
+        self.azure_app_config_jwt_key: str = os.getenv(
+            "AZURE_APP_CONFIG_JWT_KEY", "jwt-public-key"
+        )
+        self.azure_app_config_endpoint: Optional[str] = os.getenv(
+            "AZURE_APP_CONFIG_ENDPOINT"
+        )
+        self.azure_app_config_connection_string: Optional[str] = os.getenv(
+            "AZURE_APP_CONFIG_CONNECTION_STRING"
+        )
+
+        # JWT verification options
+        self.jwt_audience: Optional[str] = os.getenv("JWT_AUDIENCE")
+        self.jwt_issuer: Optional[str] = os.getenv("JWT_ISSUER")
+        self.jwt_leeway: int = int(os.getenv("JWT_LEEWAY", "0"))
+
+
+jwt_config = JWTConfig()

vibrant_auth_middleware_fastapi-0.1.0/src/vibrant_auth_middleware/dependencies.py

@@ -0,0 +1,234 @@
+"""
+FastAPI dependencies for authentication.
+
+Provides injectable dependencies for use with FastAPI's Depends system.
+"""
+
+from typing import Any, Dict, Optional, cast
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.openapi.models import OAuthFlows as OAuthFlowsModel
+from fastapi.security import OAuth2
+from fastapi.security.utils import get_authorization_scheme_param
+
+from .jwt_auth import get_token_payload, get_user_id_from_token
+
+
+class OAuth2PasswordToken(OAuth2):
+    """OAuth2 scheme for extracting Bearer token from Authorization header."""
+
+    def __init__(
+        self,
+        tokenUrl: str = "/auth/token",
+        scheme_name: Optional[str] = None,
+        scopes: Optional[dict] = None,
+    ):
+        if not scopes:
+            scopes = {}
+        flows = OAuthFlowsModel(password={"tokenUrl": tokenUrl, "scopes": scopes})
+        super().__init__(flows=flows, scheme_name=scheme_name, auto_error=False)
+
+    async def __call__(self, request: Request) -> Optional[str]:
+        authorization: str = request.headers.get("Authorization")
+        scheme, param = get_authorization_scheme_param(authorization)
+        if not authorization or scheme.lower() != "bearer":
+            return None
+        return cast(str, param)
+
+
+OAUTH2_SCHEME = OAuth2PasswordToken(tokenUrl="/auth/token")
+
+
+def _get_token_from_cookie(request: Request) -> Optional[str]:
+    """
+    Extract JWT token from cookies using access_token and token_type pair.
+
+    Looks for 'access_token' and 'token_type' cookies. If both are present
+    and token_type is 'Bearer', returns the access_token.
+
+    Args:
+        request: The incoming HTTP request.
+
+    Returns:
+        The access_token if valid cookie pair exists, None otherwise.
+    """
+    access_token = request.cookies.get("access_token")
+    token_type = request.cookies.get("token_type")
+
+    if access_token and token_type and token_type.lower() == "bearer":
+        return access_token
+
+    return None
+
+
+async def get_user_id_from_cookie(request: Request) -> str:
+    """
+    Extract user_id from JWT token stored in cookies.
+
+    This dependency:
+    1. Extracts access_token and token_type from cookies
+    2. Validates that token_type is 'Bearer'
+    3. Verifies the token signature using HS256 or RS256 (auto-detected)
+    4. Extracts user_id from the verified token payload
+
+    Args:
+        request: The incoming HTTP request.
+
+    Returns:
+        The user_id as a string.
+
+    Raises:
+        HTTPException: If cookies are missing, invalid, or token lacks user_id.
+
+    Usage:
+        ```python
+        from fastapi import FastAPI, Depends
+        from vibrant_auth_middleware import get_user_id_from_cookie
+
+        app = FastAPI()
+
+        @app.get("/protected")
+        def protected_route(user_id: str = Depends(get_user_id_from_cookie)):
+            return {"user_id": user_id}
+        ```
+    """
+    token = _get_token_from_cookie(request)
+
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated: missing or invalid cookie credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    try:
+        return get_user_id_from_token(token)
+    except HTTPException:
+        raise
+    except Exception:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Could not validate credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+async def get_user_id(
+    request: Request,
+    token: Optional[str] = Depends(OAUTH2_SCHEME),
+) -> str:
+    """
+    Extract user_id from verified JWT token in Authorization header or cookies.
+
+    This dependency:
+    1. First tries to extract the Bearer token from the Authorization header
+    2. Falls back to cookies (access_token + token_type pair) if header is missing
+    3. Verifies the token signature using HS256 or RS256 (auto-detected)
+    4. Extracts user_id from the verified token payload
+
+    Supports multiple user_id fields from ClinicUserPayload:
+    - user_id (string or number)
+    - userId (number, alternative field)
+    - internal_user_id (fallback field)
+
+    Args:
+        request: The incoming HTTP request.
+        token: Bearer token extracted from Authorization header (injected by Depends)
+
+    Returns:
+        The user_id as a string.
+
+    Raises:
+        HTTPException: If token is missing, invalid, or lacks user_id.
+
+    Usage:
+        ```python
+        from fastapi import FastAPI, Depends
+        from vibrant_auth_middleware import get_user_id
+
+        app = FastAPI()
+
+        @app.get("/protected")
+        def protected_route(user_id: str = Depends(get_user_id)):
+            return {"user_id": user_id}
+        ```
+    """
+    # Try Authorization header first, then fall back to cookies
+    if not token:
+        token = _get_token_from_cookie(request)
+
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    try:
+        return get_user_id_from_token(token)
+    except HTTPException:
+        raise
+    except Exception:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Could not validate credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+async def get_user(
+    request: Request,
+    token: Optional[str] = Depends(OAUTH2_SCHEME),
+) -> Dict[str, Any]:
+    """
+    Extract full payload from verified JWT token in Authorization header or cookies.
+
+    This dependency:
+    1. First tries to extract the Bearer token from the Authorization header
+    2. Falls back to cookies (access_token + token_type pair) if header is missing
+    3. Verifies the token signature using HS256 or RS256 (auto-detected)
+    4. Returns the verified token payload
+
+    Args:
+        request: The incoming HTTP request.
+        token: Bearer token extracted from Authorization header (injected by Depends)
+
+    Returns:
+        The verified token payload as a dictionary.
+
+    Raises:
+        HTTPException: If token is missing or invalid.
+
+    Usage:
+        ```python
+        from fastapi import FastAPI, Depends
+        from vibrant_auth_middleware import get_user
+
+        app = FastAPI()
+
+        @app.get("/protected")
+        def protected_route(user: dict = Depends(get_user)):
+            return {"user": user}
+        ```
+    """
+    # Try Authorization header first, then fall back to cookies
+    if not token:
+        token = _get_token_from_cookie(request)
+
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    try:
+        return get_token_payload(token)
+    except HTTPException:
+        raise
+    except Exception:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Could not validate credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )

vibrant_auth_middleware_fastapi-0.1.0/src/vibrant_auth_middleware/jwt_auth.py

@@ -0,0 +1,364 @@
+"""
+JWT Authentication Service.
+
+Provides JWT token verification supporting both HS256 (symmetric) and RS256 (asymmetric) algorithms.
+Automatically detects the algorithm from the JWT header and uses the appropriate verification method:
+- HS256: Uses secret from Azure Key Vault or environment variable
+- RS256: Uses public key from Azure App Configuration or environment variable
+"""
+
+import logging
+import os
+import time
+from typing import Any, Dict, Optional
+
+from azure.appconfiguration import AzureAppConfigurationClient
+from azure.core.exceptions import ResourceNotFoundError
+from azure.identity import DefaultAzureCredential, WorkloadIdentityCredential
+from fastapi import HTTPException, status
+from jose import jwt
+from jose.exceptions import ExpiredSignatureError, JWTError
+
+from .config import jwt_config
+
+logger = logging.getLogger(__name__)
+
+# Cache for keys and configuration
+_jwt_secret_cache: Optional[str] = None
+_jwt_public_key_cache: Optional[str] = None
+_cache_timestamp: float = 0
+CACHE_TTL = 300  # 5 minutes cache
+
+
+def _get_azure_credential():
+    """
+    Get the appropriate Azure credential based on the environment.
+
+    Returns:
+        WorkloadIdentityCredential for production (Kubernetes/AKS),
+        DefaultAzureCredential for other environments (staging, dev).
+
+    Environment Variables:
+        APP_ENV: "production" uses WorkloadIdentityCredential,
+                 "staging" or "dev" uses DefaultAzureCredential (default: "dev")
+    """
+    app_env = os.getenv("APP_ENV", "dev").lower()
+
+    if app_env == "production":
+        logger.debug(
+            f"Using WorkloadIdentityCredential for Azure authentication (APP_ENV={app_env})"
+        )
+        return WorkloadIdentityCredential()
+    else:
+        logger.debug(
+            f"Using DefaultAzureCredential for Azure authentication (APP_ENV={app_env})"
+        )
+        return DefaultAzureCredential()
+
+
+def _get_azure_app_config_client() -> Optional[AzureAppConfigurationClient]:
+    """Create and return an Azure App Configuration client."""
+    connection_string = jwt_config.azure_app_config_connection_string
+    endpoint = jwt_config.azure_app_config_endpoint
+
+    if connection_string:
+        return AzureAppConfigurationClient.from_connection_string(connection_string)
+    elif endpoint:
+        credential = _get_azure_credential()
+        return AzureAppConfigurationClient(base_url=endpoint, credential=credential)
+
+    return None
+
+
+def _get_hs256_secret() -> str:
+    """
+    Get HS256 secret key from Azure Key Vault or environment.
+
+    Returns:
+        The secret key for HS256 verification.
+
+    Raises:
+        HTTPException: If secret cannot be retrieved.
+    """
+    global _jwt_secret_cache, _cache_timestamp
+
+    current_time = time.time()
+    # Return cached secret if still valid
+    if _jwt_secret_cache and (current_time - _cache_timestamp) < CACHE_TTL:
+        logger.debug("Using cached HS256 secret")
+        return _jwt_secret_cache
+
+    # Try environment variable first
+    if jwt_config.jwt_secret_key:
+        logger.debug("Using HS256 secret from environment variable")
+        _jwt_secret_cache = jwt_config.jwt_secret_key
+        _cache_timestamp = current_time
+        return _jwt_secret_cache
+
+    # Try Azure Key Vault
+    if jwt_config.azure_key_vault_uri:
+        try:
+            from azure.keyvault.secrets import SecretClient
+
+            credential = _get_azure_credential()
+            client = SecretClient(
+                vault_url=jwt_config.azure_key_vault_uri, credential=credential
+            )
+
+            logger.debug(
+                f"Fetching HS256 secret from Azure Key Vault: {jwt_config.azure_key_vault_secret_name}"
+            )
+            secret = client.get_secret(jwt_config.azure_key_vault_secret_name)
+            _jwt_secret_cache = secret.value
+            _cache_timestamp = current_time
+            logger.info("Successfully retrieved HS256 secret from Azure Key Vault")
+            return _jwt_secret_cache
+
+        except Exception as e:
+            logger.error(f"Failed to retrieve secret from Azure Key Vault: {e}")
+
+    raise HTTPException(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        detail="JWT secret not configured. Please set JWT_SECRET_KEY or configure Azure Key Vault.",
+    )
+
+
+def _get_rs256_public_key() -> str:
+    """
+    Get RS256 public key from Azure App Configuration or environment.
+
+    Returns:
+        The public key for RS256 verification.
+
+    Raises:
+        HTTPException: If public key cannot be retrieved.
+    """
+    global _jwt_public_key_cache, _cache_timestamp
+
+    current_time = time.time()
+    # Return cached public key if still valid
+    if _jwt_public_key_cache and (current_time - _cache_timestamp) < CACHE_TTL:
+        logger.debug("Using cached RS256 public key")
+        return _jwt_public_key_cache
+
+    # Try environment variable first
+    if jwt_config.jwt_public_key:
+        logger.debug("Using RS256 public key from environment variable")
+        _jwt_public_key_cache = jwt_config.jwt_public_key
+        _cache_timestamp = current_time
+        return _jwt_public_key_cache
+
+    # Try Azure App Configuration
+    client = _get_azure_app_config_client()
+    if client:
+        try:
+            logger.debug(
+                f"Fetching RS256 public key from Azure App Configuration: {jwt_config.azure_app_config_jwt_key}"
+            )
+            item = client.get_configuration_setting(
+                key=jwt_config.azure_app_config_jwt_key
+            )
+
+            # Handle Key Vault references
+            if (
+                item.content_type
+                == "application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8"
+            ):
+                logger.warning(
+                    f"Key Vault reference found for {item.key}. Attempting to resolve..."
+                )
+                if item.value:
+                    _jwt_public_key_cache = item.value
+                    _cache_timestamp = current_time
+                    logger.info(
+                        "Successfully retrieved RS256 public key from Key Vault reference"
+                    )
+                    return _jwt_public_key_cache
+            elif item.value:
+                _jwt_public_key_cache = item.value
+                _cache_timestamp = current_time
+                logger.info(
+                    "Successfully retrieved RS256 public key from Azure App Configuration"
+                )
+                return _jwt_public_key_cache
+
+        except ResourceNotFoundError:
+            logger.debug(
+                f"Public key not found in Azure App Configuration: {jwt_config.azure_app_config_jwt_key}"
+            )
+        except Exception as e:
+            logger.error(
+                f"Failed to retrieve public key from Azure App Configuration: {e}"
+            )
+
+    raise HTTPException(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        detail="JWT public key not configured. Please set JWT_PUBLIC_KEY or configure Azure App Configuration.",
+    )
+
+
+def _decode_key_with_pem_header(key: str, key_type: str) -> str:
+    """
+    Ensure the key has the proper PEM header/footer.
+
+    Args:
+        key: The key string.
+        key_type: Either 'PUBLIC' or 'PRIVATE'.
+
+    Returns:
+        The key with proper PEM formatting.
+    """
+    key = key.strip()
+    prefix = "-----BEGIN PUBLIC KEY-----"
+    suffix = "-----END PUBLIC KEY-----"
+
+    if key_type == "PUBLIC":
+        if not key.startswith("-----BEGIN"):
+            if "\\n" in key:
+                key = key.replace("\\n", "\n")
+            return f"{prefix}\n{key}\n{suffix}"
+        return key
+
+    return key
+
+
+def verify_jwt_token(token: str) -> Dict[str, Any]:
+    """
+    Verify a JWT token and return its payload.
+
+    Automatically detects the algorithm (HS256 or RS256) from the token header
+    and uses the appropriate verification method.
+
+    Args:
+        token: The JWT token string (without 'Bearer ' prefix).
+
+    Returns:
+        The decoded token payload as a dictionary.
+
+    Raises:
+        HTTPException: If token is invalid, expired, or verification fails.
+    """
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="No token provided",
+        )
+
+    try:
+        # Get the header to determine the algorithm
+        header = jwt.get_unverified_header(token)
+        algorithm = header.get("alg", "HS256")
+
+        logger.debug(f"Verifying JWT token with algorithm: {algorithm}")
+
+        # Prepare decode options
+        decode_options = {
+            "verify_signature": True,
+            "verify_exp": True,
+            "verify_iat": True,
+            "leeway": jwt_config.jwt_leeway,
+        }
+
+        # Verify based on algorithm
+        if algorithm == "HS256":
+            secret = _get_hs256_secret()
+            payload = jwt.decode(
+                token,
+                secret,
+                algorithms=[algorithm],
+                options=decode_options,
+                audience=jwt_config.jwt_audience,
+                issuer=jwt_config.jwt_issuer,
+            )
+        elif algorithm == "RS256":
+            public_key = _get_rs256_public_key()
+            public_key = _decode_key_with_pem_header(public_key, "PUBLIC")
+            payload = jwt.decode(
+                token,
+                public_key,
+                algorithms=[algorithm],
+                options=decode_options,
+                audience=jwt_config.jwt_audience,
+                issuer=jwt_config.jwt_issuer,
+            )
+        else:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=f"Unsupported algorithm: {algorithm}",
+            )
+
+        logger.debug("JWT token verified successfully")
+        return payload
+
+    except ExpiredSignatureError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Token has expired",
+        )
+    except JWTError as e:
+        logger.warning(f"JWT verification failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Invalid token: {str(e)}",
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error during JWT verification: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Token verification failed",
+        )
+
+
+def get_user_id_from_token(token: str) -> str:
+    """
+    Extract user_id from a verified JWT token.
+
+    Checks multiple possible fields in the token payload:
+    - user_id (string or number)
+    - userId (number, alternative field)
+    - internal_user_id (fallback field)
+
+    Args:
+        token: The JWT token string (without 'Bearer ' prefix).
+
+    Returns:
+        The user_id as a string.
+
+    Raises:
+        HTTPException: If token is invalid or user_id cannot be extracted.
+    """
+    payload = verify_jwt_token(token)
+
+    # Try different fields for user_id based on ClinicUserPayload interface
+    user_id = (
+        payload.get("user_id")
+        or payload.get("userId")
+        or payload.get("internal_user_id")
+    )
+
+    if not user_id:
+        logger.warning("Token verified but no user_id found in payload")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Token does not contain user_id",
+        )
+
+    return str(user_id)
+
+
+def get_token_payload(token: str) -> Dict[str, Any]:
+    """
+    Get the full verified token payload.
+
+    Args:
+        token: The JWT token string (without 'Bearer ' prefix).
+
+    Returns:
+        The complete token payload as a dictionary.
+
+    Raises:
+        HTTPException: If token is invalid.
+    """
+    return verify_jwt_token(token)