API Reference

This section provides comprehensive API documentation for all components of the auth-middleware library.

Core Components

• jwt_auth_middleware
  • JwtAuthMiddleware
• Authentication Functions
  • Authentication Decorators
  • Utility Functions
  • Advanced Usage Examples
  • Error Handling
  • API Reference
• Type Definitions
  • Core Types
  • Token Types
  • Authentication Context
  • Exception Types
  • Provider-Specific Types
  • Validation Types
  • Usage Examples
  • API Reference
• Exception Handling
  • Exception Hierarchy
  • Exception Types
  • Exception Handling Patterns
  • API Reference

Authentication Providers

The library supports multiple authentication providers for different identity systems:

• AWS Cognito Provider
  • Overview
  • Configuration
  • Example Application
  • API Reference
• Azure Entra ID Authentication Provider
  • Overview
  • Configuration
  • Environment Variables
  • Token Structure
  • Azure AD App Registration
  • Integration Examples
  • Token Acquisition
  • Error Handling
  • Best Practices
  • Troubleshooting
  • API Reference
• JWT Authentication Provider
  • Overview
  • Configuration
  • Token Structure
  • Integration Examples
  • Best Practices
  • API Reference

Utilities

Additional utilities and helper components:

• jwt_bearer_manager
  • JWTBearerManager
• The User Property

Quick Reference

Common Classes and Functions

Middleware

• auth_middleware.JwtAuthMiddleware - Main authentication middleware

Authentication Functions

• auth_middleware.require_user() - Require authenticated user

• auth_middleware.require_groups() - Require group membership

• auth_middleware.require_permissions() - Require specific permissions

• auth_middleware.get_current_user() - Get current user from request

Providers

• auth_middleware.providers.authn.cognito_provider.CognitoProvider - AWS Cognito

• auth_middleware.providers.authn.entra_id_provider.EntraIdProvider - Azure Entra ID

• auth_middleware.providers.authn.jwt_provider.JWTProvider - Generic JWT

Exceptions

• auth_middleware.exceptions.AuthenticationError - Authentication failures

• auth_middleware.exceptions.AuthorizationError - Authorization failures

• auth_middleware.exceptions.ConfigurationError - Configuration issues

Types

• auth_middleware.types.User - User representation

• auth_middleware.types.AuthenticatedRequest - Extended request with auth context

Usage Patterns

Basic Setup

from fastapi import FastAPI
from auth_middleware import JwtAuthMiddleware
from auth_middleware.providers.authn.cognito_provider import CognitoProvider

app = FastAPI()

# Setup authentication
auth_provider = CognitoProvider(
    user_pool_id="your-user-pool-id",
    client_id="your-client-id",
    region="us-east-1"
)

app.add_middleware(JwtAuthMiddleware, auth_provider=auth_provider)

Endpoint Protection

from fastapi import Depends
from auth_middleware import require_user, require_groups

@app.get("/protected", dependencies=[Depends(require_user())])
async def protected_endpoint(request):
    user = request.state.current_user
    return {"message": f"Hello {user.name}"}

@app.get("/admin", dependencies=[Depends(require_groups(["administrators"]))])
async def admin_endpoint(request):
    return {"message": "Admin access granted"}

Error Handling

from fastapi.responses import JSONResponse
from auth_middleware.exceptions import AuthenticationError, AuthorizationError

@app.exception_handler(AuthenticationError)
async def auth_error_handler(request, exc):
    return JSONResponse(
        status_code=401,
        content={"error": "Authentication failed"}
    )

@app.exception_handler(AuthorizationError)
async def authz_error_handler(request, exc):
    return JSONResponse(
        status_code=403,
        content={"error": "Access denied"}
    )