auth-gate 0.1.0

Enterprise-grade authentication for microservices with Kong and Keycloak integration

Auth Gate

Enterprise-grade authentication for microservices with Kong and Keycloak integration.

Features

• Dual-mode authentication: Support for both Kong header-based auth (production) and direct Keycloak validation (development)
• Service-to-service authentication: Built-in client credentials flow for secure inter-service communication
• Circuit breaker pattern: Resilient handling of Keycloak failures with automatic recovery
• FastAPI integration: Ready-to-use dependencies for protecting endpoints
• Role-based access control: Fine-grained permission management with role and scope validation
• Middleware support: Automatic request authentication with configurable exclusions

Installation

pip install auth-gate

For Development

pip install auth-gate[dev]

Quick Start

Basic Usage

from fastapi import FastAPI, Depends
from auth_gate import (
    AuthMiddleware,
    get_current_user,
    require_admin,
    UserContext,
    AuthSettings
)

# Initialize FastAPI app
app = FastAPI()

# Add authentication middleware
app.add_middleware(
    AuthMiddleware,
    excluded_paths={"/health", "/metrics"},
    excluded_prefixes={"/docs", "/openapi.json"}
)

# Protected endpoint - requires authentication
@app.get("/api/profile")
async def get_profile(user: UserContext = Depends(get_current_user)):
    return {
        "user_id": user.user_id,
        "username": user.username,
        "roles": user.roles
    }

# Admin-only endpoint
@app.get("/api/admin/users")
async def list_users(admin: UserContext = Depends(require_admin)):
    return {"message": "Admin access granted"}

# Role-based access
from auth_gate import require_roles

require_supplier_or_admin = require_roles("supplier", "admin")

@app.get("/api/products")
async def list_products(user: UserContext = Depends(require_supplier_or_admin)):
    return {"products": []}

Service-to-service Auth

from auth_gate import ServiceAuthClient
import httpx

# Get service auth client
auth_client = ServiceAuthClient()

# Make authenticated service call
async def call_other_service():
    # Get service token (automatically cached and refreshed)
    auth_header = await auth_client.get_service_token()

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "http://other-service/api/data",
            headers={"Authorization": auth_header}
        )
        return response.json()

Configuration

Configure via envirinment variables:

# Authentication mode
AUTH_MODE=kong_headers  # or "direct_keycloak", "bypass" (testing only)

# Keycloak settings
KEYCLOAK_REALM_URL=https://keycloak.example.com/realms/tradelink
KEYCLOAK_CLIENT_ID=my-service
KEYCLOAK_CLIENT_SECRET=secret

# Service account (for S2S auth)
SERVICE_CLIENT_ID=my-service-account
SERVICE_CLIENT_SECRET=secret

# Optional settings
VERIFY_HMAC=false
INTERNAL_HMAC_KEY=your-hmac-key

Advanced Features

Custom Excluded Paths

app.add_middleware(
    AuthMiddleware,
    excluded_paths={"/health", "/metrics", "/public"},
    excluded_prefixes={"/static", "/docs"},
    optional_auth_paths={"/api/products"}  # Auth optional for these paths
)

Direct Validator Usage

from auth_gate import UserValidator, AuthMode

validator = UserValidator(mode=AuthMode.DIRECT_KEYCLOAK)
user_context = await validator.validate_keycloak_token(token)

Circuit Breaker Configuration

The S2S auth client includes automatic circuit breaker protection:

• Opens after 5 consecutive failures
• Attempts recovery after 60 seconds
• Provides fail-fast behavior when Keycloak is unavailable

Development

Running Tests

pytest tests/ --cov=auth_gate

Code quality

black src/
ruff check src/
mypy src/

License

For use within tradelink suite of services - See LICENSE file for details.

Support

For issues and questions, please use the GitHub issue tracker.