API Reference

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

Authentication Providers

The library supports multiple authentication providers for different identity systems:

Services

Additional services for cross-cutting concerns like M2M detection, rate limiting, audit logging, and metrics:

Utilities

Additional utilities and helper components:

Quick Reference

Common Classes and Functions

Middleware

auth_middleware.JwtAuthMiddleware - Main authentication middleware

Authentication Functions

auth_middleware.guards.functions.require_user() - Require authenticated user
auth_middleware.guards.functions.require_groups() - Require group membership
auth_middleware.guards.functions.require_permissions() - Require specific permissions
auth_middleware.guards.functions.get_current_user() - Get current user from request

Providers

auth_middleware.providers.aws.cognito_provider.CognitoProvider - AWS Cognito
auth_middleware.providers.azure.entra_id_provider.EntraIdProvider - Azure Entra ID
auth_middleware.providers.oidc.oidc_provider.OidcProvider - Generic OIDC (Authentik, Keycloak, Auth0, Okta, …)
auth_middleware.contracts.jwt_provider.JWTProvider - Base contract for building custom providers

Exceptions

auth_middleware.exceptions.invalid_token_exception.InvalidTokenException - Token validation failures

Types

auth_middleware.types.user.User - User representation

Usage Patterns

Basic Setup

from fastapi import FastAPI
from auth_middleware import JwtAuthMiddleware
from auth_middleware.providers.aws.cognito_provider import CognitoProvider
from auth_middleware.providers.aws.cognito_authz_provider_settings import (
    CognitoAuthzProviderSettings,
)

app = FastAPI()

# Setup authentication
auth_settings = CognitoAuthzProviderSettings(
    user_pool_id="your-user-pool-id",
    user_pool_region="us-east-1",
    user_pool_client_id="your-app-client-id",  # recommended: rejects tokens from other app clients
)
auth_provider = CognitoProvider(settings=auth_settings)

app.add_middleware(JwtAuthMiddleware, auth_provider=auth_provider)

Endpoint Protection

from fastapi import Depends
from auth_middleware.guards 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.invalid_token_exception import InvalidTokenException

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