auth-guardian 0.1.2

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

Opcional (revocacion con Redis):

pip install "auth-guardian[redis]"

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

Redis: opcional pero recomendado

Redis NO es obligatorio para usar la libreria.

• Sin Redis: autenticacion y roles funcionan normal.
• Sin Redis: al hacer logout se borran cookies en el navegador, pero el access token puede seguir valido hasta su expiracion si alguien intenta reutilizarlo.
• Con Redis: se activa revocacion inmediata del token (blacklist), recomendado para mayor seguridad.

Si quieres activar Redis, agrega:

AUTH_REDIS_URL=redis://redis:6379

E instala el extra:

pip install "auth-guardian[redis]"

Docker Compose simple con Redis

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_REDIS_URL: "redis://redis:6379"
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    ports:
      - "6379:6379"

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 (Redis)

Si defines AUTH_REDIS_URL, auth-guardian puede invalidar tokens al hacer logout. Esto complementa el borrado de cookies con revocacion server-side inmediata.

AUTH_REDIS_URL=redis://localhost:6379

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).

Nota de documentacion

Este README.md es la documentacion principal del proyecto. Si se necesitan mas ejemplos (imagenes, flujos o casos de uso extendidos), se agregan aqui mismo para mantener un unico punto de entrada.