auth-gate 0.1.0__py3-none-any.whl

auth_gate/__init__.py

@@ -0,0 +1,52 @@
+"""
+Tradelink Authentication Client
+
+Enterprise authentication client for microservices with Kong/Keycloak integration.
+"""
+
+from .config import AuthMode, AuthSettings
+from .fastapi_utils import (
+    get_current_user,
+    get_optional_user,
+    require_admin,
+    require_customer,
+    require_moderator,
+    require_roles,
+    require_scopes,
+    require_supplier,
+    require_supplier_or_admin,
+    verify_hmac_signature,
+)
+from .middleware import AuthMiddleware
+from .s2s_auth import CircuitBreaker, CircuitBreakerOpenError, ServiceAuthClient
+from .schemas import UserContext
+from .user_auth import UserValidator
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Configuration
+    "AuthSettings",
+    "AuthMode",
+    # Schemas
+    "UserContext",
+    # User Authentication
+    "UserValidator",
+    # Service-to-Service
+    "ServiceAuthClient",
+    "CircuitBreaker",
+    "CircuitBreakerOpenError",
+    # Middleware
+    "AuthMiddleware",
+    # FastAPI Dependencies
+    "get_current_user",
+    "get_optional_user",
+    "require_roles",
+    "require_scopes",
+    "require_admin",
+    "require_supplier",
+    "require_customer",
+    "require_moderator",
+    "require_supplier_or_admin",
+    "verify_hmac_signature",
+]

auth_gate/config.py

@@ -0,0 +1,99 @@
+"""
+Configuration management for Tradelink Auth Client
+"""
+
+from enum import Enum
+from typing import Optional
+
+from pydantic_settings import BaseSettings
+
+
+class AuthMode(Enum):
+    """Authentication modes for different environments"""
+
+    KONG_HEADERS = "kong_headers"  # Production: Kong validates tokens
+    DIRECT_KEYCLOAK = "direct_keycloak"  # Development: Direct Keycloak validation
+    BYPASS = "bypass"  # Testing only - NEVER use in production
+
+
+class AuthSettings(BaseSettings):
+    """
+    Centralized configuration for authentication client.
+    All settings can be overridden via environment variables.
+    """
+
+    model_config = {
+        "env_file": (".env", ".env.test", ".env.prod"),
+        "extra": "ignore",
+        "env_file_encoding": "utf-8",
+        "case_sensitive": True,
+    }
+
+    # Authentication Mode
+    AUTH_MODE: str = "kong_headers"
+
+    # Keycloak Configuration
+    KEYCLOAK_REALM_URL: str = "http://localhost:8080/realms/master"
+    KEYCLOAK_CLIENT_ID: str = "backend-service"
+    KEYCLOAK_CLIENT_SECRET: str = ""
+
+    # Service Account Configuration (for S2S)
+    SERVICE_CLIENT_ID: str = "service-account"
+    SERVICE_CLIENT_SECRET: str = ""
+
+    # HMAC Verification (optional)
+    VERIFY_HMAC: bool = False
+    INTERNAL_HMAC_KEY: str = ""
+
+    # Circuit Breaker Settings
+    CIRCUIT_BREAKER_FAILURE_THRESHOLD: int = 5
+    CIRCUIT_BREAKER_RECOVERY_TIMEOUT: int = 60
+
+    # Token Settings
+    TOKEN_CACHE_TTL: int = 300  # seconds
+    TOKEN_REFRESH_BUFFER: int = 30  # seconds before expiry
+
+    # HTTP Client Settings
+    HTTP_TIMEOUT: float = 10.0
+    HTTP_MAX_KEEPALIVE_CONNECTIONS: int = 10
+
+    @property
+    def auth_mode_enum(self) -> AuthMode:
+        """Get AUTH_MODE as enum"""
+        try:
+            return AuthMode(self.AUTH_MODE.lower())
+        except ValueError:
+            raise ValueError(f"Invalid AUTH_MODE: {self.AUTH_MODE}")
+
+    @property
+    def is_production(self) -> bool:
+        """Check if running in production mode"""
+        return self.auth_mode_enum == AuthMode.KONG_HEADERS
+
+    @property
+    def is_development(self) -> bool:
+        """Check if running in development mode"""
+        return self.auth_mode_enum == AuthMode.DIRECT_KEYCLOAK
+
+    @property
+    def is_testing(self) -> bool:
+        """Check if running in testing/bypass mode"""
+        return self.auth_mode_enum == AuthMode.BYPASS
+
+
+# Global settings instance
+_settings: Optional[AuthSettings] = None
+
+
+def get_settings() -> AuthSettings:
+    """Get or create settings instance"""
+    global _settings
+    if _settings is None:
+        _settings = AuthSettings()
+    return _settings
+
+
+def reset_settings() -> None:
+    """Reset settings (useful for testing)"""
+    global _settings
+    _settings = None

auth_gate/fastapi_utils.py

@@ -0,0 +1,275 @@
+"""
+FastAPI dependency injection utilities for authentication
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import Depends, Header, HTTPException, Request, status
+
+from .config import get_settings
+from .schemas import UserContext
+from .user_auth import HMACVerifier, get_user_validator
+
+logger = logging.getLogger(__name__)
+
+
+# Core authentication dependencies
+async def get_current_user(
+    request: Request,
+    authorization: Optional[str] = Header(None),
+    x_token_verified: Optional[str] = Header(None, alias="X-Token-Verified"),
+    x_user_id: Optional[str] = Header(None, alias="X-User-ID"),
+    x_username: Optional[str] = Header(None, alias="X-Username"),
+    x_user_email: Optional[str] = Header(None, alias="X-User-Email"),
+    x_user_roles: Optional[str] = Header(None, alias="X-User-Roles"),
+    x_user_scopes: Optional[str] = Header(None, alias="X-User-Scopes"),
+    x_session_id: Optional[str] = Header(None, alias="X-Session-ID"),
+    x_client_id: Optional[str] = Header(None, alias="X-Client-ID"),
+    x_auth_source: Optional[str] = Header(None, alias="X-Auth-Source"),
+) -> UserContext:
+    """
+    Main dependency for getting authenticated user.
+
+    This is the primary dependency to use in your FastAPI endpoints.
+
+    Example:
+        @app.get("/api/profile")
+        async def get_profile(user: UserContext = Depends(get_current_user)):
+            return {"user_id": user.user_id}
+
+    Args:
+        Various authentication headers
+
+    Returns:
+        UserContext with authenticated user information
+
+    Raises:
+        HTTPException: If authentication fails
+    """
+    validator = get_user_validator()
+    return await validator.get_current_user(
+        request,
+        authorization,
+        x_token_verified,
+        x_user_id,
+        x_username,
+        x_user_email,
+        x_user_roles,
+        x_user_scopes,
+        x_session_id,
+        x_client_id,
+        x_auth_source,
+    )
+
+
+async def get_optional_user(
+    request: Request,
+    authorization: Optional[str] = Header(None),
+    x_token_verified: Optional[str] = Header(None, alias="X-Token-Verified"),
+    x_user_id: Optional[str] = Header(None, alias="X-User-ID"),
+    x_username: Optional[str] = Header(None, alias="X-Username"),
+    x_user_email: Optional[str] = Header(None, alias="X-User-Email"),
+    x_user_roles: Optional[str] = Header(None, alias="X-User-Roles"),
+    x_user_scopes: Optional[str] = Header(None, alias="X-User-Scopes"),
+    x_session_id: Optional[str] = Header(None, alias="X-Session-ID"),
+    x_client_id: Optional[str] = Header(None, alias="X-Client-ID"),
+    x_auth_source: Optional[str] = Header(None, alias="X-Auth-Source"),
+) -> Optional[UserContext]:
+    """
+    Optional authentication - returns None if not authenticated.
+
+    Use this for endpoints where authentication is optional.
+
+    Example:
+        @app.get("/api/products")
+        async def list_products(user: Optional[UserContext] = Depends(get_optional_user)):
+            if user:
+                # Show personalized products
+                pass
+            else:
+                # Show public products
+                pass
+
+    Args:
+        Various authentication headers
+
+    Returns:
+        UserContext if authenticated, None otherwise
+    """
+    try:
+        return await get_current_user(
+            request,
+            authorization,
+            x_token_verified,
+            x_user_id,
+            x_username,
+            x_user_email,
+            x_user_roles,
+            x_user_scopes,
+            x_session_id,
+            x_client_id,
+            x_auth_source,
+        )
+    except HTTPException:
+        return None
+
+
+# Role-based access control factories
+def require_roles(*required_roles: str):
+    """
+    Factory for role-checking dependencies.
+
+    Creates a dependency that ensures the user has at least one of the specified roles.
+
+    Example:
+        require_editor = require_roles("editor", "admin")
+
+        @app.post("/api/articles")
+        async def create_article(user: UserContext = Depends(require_editor)):
+            return {"created_by": user.user_id}
+
+    Args:
+        *required_roles: Variable number of role names
+
+    Returns:
+        Dependency function that validates roles
+    """
+
+    async def role_checker(user: UserContext = Depends(get_current_user)) -> UserContext:
+        if not user.has_any_role(list(required_roles)):
+            logger.warning(f"User {user.user_id} lacks required roles: {required_roles}")
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Requires one of roles: {', '.join(required_roles)}",
+            )
+        return user
+
+    return role_checker
+
+
+def require_scopes(*required_scopes: str):
+    """
+    Factory for scope-checking dependencies.
+
+    Creates a dependency that ensures the user has all specified scopes.
+
+    Example:
+        require_write = require_scopes("write", "publish")
+
+        @app.post("/api/publish")
+        async def publish(user: UserContext = Depends(require_write)):
+            return {"published_by": user.user_id}
+
+    Args:
+        *required_scopes: Variable number of scope names
+
+    Returns:
+        Dependency function that validates scopes
+    """
+
+    async def scope_checker(user: UserContext = Depends(get_current_user)) -> UserContext:
+        missing_scopes = [s for s in required_scopes if not user.has_scope(s)]
+        if missing_scopes:
+            logger.warning(f"User {user.user_id} lacks required scopes: {missing_scopes}")
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Requires scopes: {', '.join(missing_scopes)}",
+            )
+        return user
+
+    return scope_checker
+
+
+# Pre-configured role dependencies for common use cases
+require_admin = require_roles("admin")
+"""Dependency that requires admin role"""
+
+require_supplier = require_roles("supplier")
+"""Dependency that requires supplier role"""
+
+require_customer = require_roles("customer")
+"""Dependency that requires customer role"""
+
+require_moderator = require_roles("moderator")
+"""Dependency that requires moderator role"""
+
+require_supplier_or_admin = require_roles("supplier", "admin")
+"""Dependency that requires either supplier or admin role"""
+
+
+# HMAC verification for service-to-service communication
+async def verify_hmac_signature(
+    request: Request,
+    x_authz_signature: Optional[str] = Header(None, alias="X-Authz-Signature"),
+    x_authz_ts: Optional[str] = Header(None, alias="X-Authz-Ts"),
+    user: UserContext = Depends(get_current_user),
+) -> UserContext:
+    """
+    Dependency to verify HMAC signatures from Kong.
+
+    Use this when Kong is configured with HMAC plugin for additional security.
+
+    Example:
+        @app.post("/api/sensitive")
+        async def sensitive_operation(user: UserContext = Depends(verify_hmac_signature)):
+            return {"verified_user": user.user_id}
+
+    Args:
+        request: FastAPI request
+        x_authz_signature: HMAC signature header
+        x_authz_ts: Timestamp header
+        user: Authenticated user context
+
+    Returns:
+        UserContext if HMAC is valid
+
+    Raises:
+        HTTPException: If HMAC verification fails
+    """
+    settings = get_settings()
+
+    if not settings.VERIFY_HMAC:
+        return user
+
+    if not x_authz_signature or not x_authz_ts:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing HMAC headers",
+        )
+
+    verifier = HMACVerifier(settings.INTERNAL_HMAC_KEY)
+
+    if not verifier.verify_signature(
+        x_authz_signature,
+        x_authz_ts,
+        user.user_id,
+        user.session_id or "",
+        request.method,
+        request.url.path,
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid HMAC signature",
+        )
+
+    return user
+
+
+# Utility functions for checking authentication mode
+def is_using_kong() -> bool:
+    """Check if using Kong authentication"""
+    settings = get_settings()
+    return settings.is_production
+
+
+def is_using_keycloak() -> bool:
+    """Check if using direct Keycloak authentication"""
+    settings = get_settings()
+    return settings.is_development
+
+
+def is_bypass_mode() -> bool:
+    """Check if in bypass/testing mode"""
+    settings = get_settings()
+    return settings.is_testing

auth_gate/middleware.py

@@ -0,0 +1,205 @@
+"""
+FastAPI middleware for authentication
+"""
+
+import logging
+import time
+from typing import Optional, Set
+
+from fastapi import HTTPException, Request, status
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+
+from .config import get_settings
+from .user_auth import get_user_validator
+
+logger = logging.getLogger(__name__)
+
+
+class AuthMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware for handling authentication in Kong/Keycloak environment.
+
+    Features:
+    - Automatic authentication based on configured mode
+    - Configurable path exclusions
+    - Optional authentication paths
+    - Request enrichment with user context
+    - Security headers injection
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        excluded_paths: Optional[Set[str]] = None,
+        excluded_prefixes: Optional[Set[str]] = None,
+        optional_auth_paths: Optional[Set[str]] = None,
+    ):
+        """
+        Initialize authentication middleware.
+
+        Args:
+            app: ASGI application
+            excluded_paths: Exact paths that don't require authentication
+            excluded_prefixes: Path prefixes that don't require authentication
+            optional_auth_paths: Paths where authentication is optional
+        """
+        super().__init__(app)
+
+        # Paths that don't require authentication
+        self.excluded_paths = excluded_paths or {
+            "/health",
+            "/metrics",
+            "/openapi.json",
+            "/favicon.ico",
+        }
+
+        # Path prefixes that don't require authentication
+        self.excluded_prefixes = excluded_prefixes or {
+            "/api/docs",
+            "/api/redoc",
+            "/static",
+            "/_health",
+        }
+
+        # Paths where authentication is optional
+        self.optional_auth_paths = optional_auth_paths or set()
+
+        self.validator = get_user_validator()
+        self.settings = get_settings()
+
+    def is_excluded(self, path: str) -> bool:
+        """Check if path is excluded from authentication"""
+        # Exact match
+        if path in self.excluded_paths:
+            return True
+
+        # Prefix match
+        for prefix in self.excluded_prefixes:
+            if path.startswith(prefix):
+                return True
+
+        return False
+
+    def is_optional_auth(self, path: str) -> bool:
+        """Check if path has optional authentication"""
+        return path in self.optional_auth_paths
+
+    async def dispatch(self, request: Request, call_next):
+        """Process request with authentication"""
+        start_time = time.time()
+
+        # Add request ID for tracing
+        request_id = request.headers.get("X-Request-ID", str(time.time()))
+
+        # Skip authentication for excluded paths
+        if self.is_excluded(request.url.path):
+            response = await call_next(request)
+            self._add_security_headers(response, request_id, start_time)
+            return response
+
+        try:
+            # Extract authentication headers
+            auth_headers = self._extract_auth_headers(request)
+
+            # Check if we have any authentication
+            has_auth = self._has_authentication(auth_headers)
+
+            if not has_auth:
+                # No authentication present
+                if self.is_optional_auth(request.url.path):
+                    request.state.user = None
+                else:
+                    logger.warning(f"Missing authentication for {request.url.path}")
+                    return JSONResponse(
+                        status_code=status.HTTP_401_UNAUTHORIZED,
+                        content={
+                            "error": "unauthorized",
+                            "message": "Authentication required",
+                            "request_id": request_id,
+                        },
+                    )
+            else:
+                # Validate authentication
+                user_context = await self.validator.get_current_user(request, **auth_headers)
+                request.state.user = user_context
+
+                # Log authentication details
+                logger.info(
+                    f"Authenticated request: user={user_context.user_id}, "
+                    f"roles={user_context.roles}, path={request.url.path}, "
+                    f"method={request.method}, source={user_context.auth_source}"
+                )
+
+            # Process request
+            response = await call_next(request)
+
+            # Add security headers
+            self._add_security_headers(response, request_id, start_time)
+
+            return response
+
+        except HTTPException as e:
+            # Handle authentication exceptions
+            logger.warning(f"Auth failed: {e.detail}, path={request.url.path}")
+            return JSONResponse(
+                status_code=e.status_code,
+                content={
+                    "error": "authentication_failed",
+                    "message": e.detail,
+                    "request_id": request_id,
+                },
+            )
+        except Exception as e:
+            # Handle unexpected errors
+            logger.error(f"Middleware error: {e}", exc_info=True)
+            return JSONResponse(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                content={
+                    "error": "internal_error",
+                    "message": "An internal error occurred",
+                    "request_id": request_id,
+                },
+            )
+
+    def _extract_auth_headers(self, request: Request) -> dict:
+        """Extract all authentication-related headers"""
+        return {
+            "authorization": request.headers.get("Authorization"),
+            "x_token_verified": request.headers.get("X-Token-Verified"),
+            "x_user_id": request.headers.get("X-User-ID"),
+            "x_username": request.headers.get("X-Username"),
+            "x_user_email": request.headers.get("X-User-Email"),
+            "x_user_roles": request.headers.get("X-User-Roles"),
+            "x_user_scopes": request.headers.get("X-User-Scopes"),
+            "x_session_id": request.headers.get("X-Session-ID"),
+            "x_client_id": request.headers.get("X-Client-ID"),
+            "x_auth_source": request.headers.get("X-Auth-Source"),
+        }
+
+    def _has_authentication(self, auth_headers: dict) -> bool:
+        """Check if request has any authentication"""
+        if self.settings.is_production:
+            # Kong mode - check for verified token header
+            return auth_headers.get("x_token_verified") == "true"
+        elif self.settings.is_development:
+            # Direct Keycloak mode - check for Bearer token
+            auth: str = auth_headers.get("authorization", "")
+            return auth.startswith("Bearer ")
+        elif self.settings.is_testing:
+            # Bypass mode - always authenticated
+            return True
+        return False
+
+    def _add_security_headers(self, response, request_id: str, start_time: float):
+        """Add security and performance headers to response"""
+        response.headers["X-Request-ID"] = request_id
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
+
+        # Add performance metrics
+        process_time = time.time() - start_time
+        response.headers["X-Process-Time"] = str(process_time)