auth-guardian 0.1.5

Reusable Keycloak SDK for auth-service and microservices

Auth Guardian

auth-guardian es una libreria Python para proteger APIs con Keycloak/OIDC en FastAPI, con configuracion minima y enfoque plug-and-play.

Que resuelve

• Login OIDC sin escribir todo el flujo a mano.
• Proteccion de endpoints autenticados.
• Control por roles (admin, support, etc.).
• Helpers para validacion de tokens y extraccion de roles.

Instalacion

pip install auth-guardian

Configuracion minima

Define estas variables de entorno:

AUTH_BASE_URL=https://auth.tu-dominio.com
AUTH_REALM=tu-realm
AUTH_CLIENT_ID=tu-cliente

Tambien se aceptan alias legacy:

• KEYCLOAK_BASE_URL
• KEYCLOAK_REALM
• KEYCLOAK_CLIENT_ID

Revocacion de tokens

AuthGuardian() ya trae seleccion automatica de backend de revocacion:

1. Si existe AUTH_DATABASE_URL usa base de datos (SQLAlchemy async).
2. Si no hay backend compartido, usa memoria local (single process).

• Sin backend compartido: autenticacion y roles funcionan normal.
• Sin backend compartido: logout elimina cookies, pero la revocacion global depende del TTL del token.
• Con Database backend: revocacion inmediata y consistente entre instancias.

Opcion Database (SQLAlchemy async)

AUTH_DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/dbname

pip install "auth-guardian[database]"

Docker Compose simple con Database (PostgreSQL)

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      AUTH_BASE_URL: "https://auth.tu-dominio.com"
      AUTH_REALM: "tu-realm"
      AUTH_CLIENT_ID: "tu-cliente"
      AUTH_DATABASE_URL: "postgresql+asyncpg://postgres:postgres@db:5432/auth_guardian"
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: auth_guardian
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"

Uso rapido en FastAPI

from fastapi import Depends, FastAPI
from auth_guardian import AuthGuardian, create_auth_router

app = FastAPI()
auth = AuthGuardian()

app.include_router(
    create_auth_router(
        auth=auth,
        login_redirect_url="/dashboard",
        logout_redirect_url="/login",
    )
)

@app.get("/health")
async def health() -> dict[str, str]:
    return {"status": "ok"}

@app.get("/ejemplo/v1")
async def ejemplo_v1(user: dict = Depends(auth.get_current_user)):
    return {
        "mensaje": f"Hola {user.get('preferred_username')}",
        "email": user.get("email"),
    }

@app.get("/ejemplo/v2")
async def ejemplo_v2(user: dict = Depends(auth.require_role("admin"))):
    return {"mensaje": "Acceso permitido para rol admin"}

Con esto tienes:

• GET /login
• GET /oidc/callback
• GET /logout
• Proteccion por usuario autenticado y por rol.

Casos de uso comunes

• Proteger endpoints internos de microservicios.
• Habilitar login/logout en apps FastAPI sin implementar OIDC desde cero.
• Restringir secciones administrativas por rol.
• Validar tokens manualmente en procesos asincronos o workers.

Ejemplo de validacion manual

payload = await auth.get_validator().decode_access_token(token)
print(payload.get("sub"))

Caracteristicas opcionales

Revocacion inmediata

Si defines AUTH_DATABASE_URL, auth-guardian invalida tokens al hacer logout. Ademas, al cerrar sesion revoca el refresh token en Keycloak para cortar renovaciones.

AUTH_DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/dbname

Multi-tenant (multiples realms)

from fastapi import Request

async def resolve_tenant(request: Request) -> str | None:
    return request.headers.get("X-Tenant-ID")

auth = AuthGuardian(tenant_resolver=resolve_tenant)

API publica estable

• AuthGuardian
• create_auth_router
• extract_client_roles(payload, client_id)
• AuthConfig
• AuthTokenValidator
• AuthOIDCClient
• KeycloakAuthError
• TokenValidationError
• KeycloakAPIError

Buenas practicas

• Usa variables de entorno por ambiente (dev/stage/prod).
• No hardcodees secretos en codigo fuente.
• Fija version en produccion (auth-guardian==x.y.z).