auth-guardian 0.1.1

Reusable Keycloak SDK for auth-service and microservices

Auth Guardian

Auth Guardian es un SDK extremadamente simple, plug-and-play y agnóstico, diseñado para proteger aplicaciones y microservicios en Python utilizando Keycloak (u otros proveedores OIDC compatibles).

Ha sido diseñado para evitar configuraciones redundantes: con un par de variables de entorno, tu aplicación tendrá flujos de login, logout, callbacks y validación de roles y permisos automáticamente.

---

Instalación

pip install auth-guardian

---

Configuración (Plug-and-Play)

AuthGuardian es lo suficientemente inteligente como para configurarse por sí mismo. Solo necesitas definir las siguientes variables de entorno:

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

Nota: También soporta las variables legacy KEYCLOAK_BASE_URL, KEYCLOAK_REALM y KEYCLOAK_CLIENT_ID de forma automática.

---

Uso en FastAPI

1. Inyectando Rutas Automáticas (Login, Logout, Callback)

Para aplicaciones frontend/Fullstack, AuthGuardian puede inyectar los endpoints completos del flujo OIDC (/login, /logout, /oidc/callback) para que no tengas que escribirlos:

from fastapi import FastAPI
from auth_guardian import AuthGuardian, create_auth_router

app = FastAPI()

# 1. Instancia el guardián
auth = AuthGuardian()

# 2. Crea el router que manejará automáticamente login, callback y logout
auth_router = create_auth_router(
    auth=auth,
    login_redirect_url="/dashboard", # Dónde enviar al usuario tras loguearse
    logout_redirect_url="/login"     # Dónde enviar al usuario tras desloguearse
)

# 3. Registra el router en tu app
app.include_router(auth_router)

¡Eso es todo! Automáticamente tienes:

• GET /login -> Redirige al login de Keycloak.
• GET /oidc/callback -> Maneja el intercambio de código, genera las cookies seguras e inicia la sesión local.
• GET /logout -> Elimina cookies y redirige al cierre de sesión de Keycloak.

2. Protegiendo tus Endpoints (Para Principiantes)

En FastAPI, "proteger" una ruta significa que si alguien entra sin haber iniciado sesión, el sistema le bloqueará el acceso automáticamente.

Para lograr esto, FastAPI usa algo llamado Depends (Dependencias). Si agregas Depends(auth.get_current_user) en tu función, AuthGuardian se encargará de verificar si el usuario tiene sesión activa antes de ejecutar el código.

Ejemplo 1: Bloquear acceso a usuarios no logueados

from fastapi import Depends

@app.get("/recurso-seguro")
async def get_seguro(user: dict = Depends(auth.get_current_user)):
    # Si llega aquí, es porque el usuario SÍ está logueado.
    # 'user' contendrá la información de su perfil.
    return {
        "mensaje": f"Hola {user.get('preferred_username')}",
        "email": user.get('email')
    }

Ejemplo 2: Bloquear acceso según el Rol del usuario Si tienes zonas exclusivas (como un panel de administrador), puedes usar auth.require_role("nombre_del_rol").

@app.get("/zona-admin")
async def get_admin(user: dict = Depends(auth.require_role("admin"))):
    # Solo entrarán usuarios que se hayan logueado y que tengan el rol "admin"
    return {"mensaje": "¡Bienvenido, administrador!"}

Características Avanzadas (v0.1.0+)

1. Redis Blacklisting (Revocación Inmediata)

Keycloak usa JWTs (Tokens de corta duración). Si un usuario hace "logout", el token sigue siendo matemáticamente válido hasta que expire. Para evitar esto y asegurar una revocación inmediata de permisos, auth-guardian soporta Blacklisting mediante Redis.

Para activarlo:

1. Instala el SDK con la extensión de Redis: pip install auth-guardian[redis]
2. Define la variable de entorno: AUTH_REDIS_URL=redis://localhost:6379

Al hacer logout, el SDK insertará el jti (Token ID) en Redis. Todas las peticiones subsecuentes con ese token serán rechazadas automáticamente con un 401 Unauthorized.

2. Multi-Tenancy (Múltiples Realms)

Si tu aplicación SaaS maneja múltiples "clientes" (tenants) donde cada uno tiene su propio Realm en Keycloak, puedes usar el tenant_resolver:

async def get_tenant_from_request(request: Request) -> str | None:
    # Extrae el tenant desde un subdominio, header o parámetro
    return request.headers.get("X-Tenant-ID")

auth = AuthGuardian(tenant_resolver=get_tenant_from_request)

Al hacer esto, el SDK resolverá dinámicamente el Realm, la validación del JWT, y los endpoints de OIDC específicos para el tenant activo en cada petición.

3. Silent Refresh Automático

La dependencia Depends(auth.get_current_user) inspecciona tanto el pfx_token como el pfx_id_token. Si el pfx_token expiró pero hay un ID token válido y una sesión de servidor, el SDK (próximamente soportado de forma completa vía refresh tokens) interceptará la petición, renovará silenciosamente los tokens por debajo, inyectará las nuevas cookies en la respuesta, y dejará pasar la petición sin desloguear al usuario.

---

Opciones Avanzadas

Validación Manual de Tokens

Si no usas FastAPI o necesitas validar un token manualmente, el SDK expone internamente el validador:

payload = await auth.get_validator().decode_access_token("eyJhbGciOiJIUz...")
print(payload)

Hook Personalizado de Login

Al usar create_auth_router, puedes inyectar un hook que se ejecute justo cuando el usuario hace login exitosamente (por ejemplo, para guardar/actualizar el usuario en tu base de datos):

async def sync_user_in_db(payload: dict):
    email = payload.get("email")
    print(f"Sincronizando usuario {email} en base de datos...")

auth_router = create_auth_router(
    auth=auth,
    on_login_success=sync_user_in_db # Se ejecuta después del callback, antes de redirigir
)

---

Contrato Público API

El contrato público exportado es estable y mantenido a través del __init__.py.

• AuthGuardian: Clase principal y Facade de autenticación.
• create_auth_router: Constructor automático de endpoints OIDC para FastAPI.
• extract_client_roles(payload, client_id): Función helper para extraer los roles.
• AuthConfig, AuthTokenValidator, AuthOIDCClient: Accesibles para usos complejos o manuales.
• Manejo de Errores: KeycloakAuthError, TokenValidationError, KeycloakAPIError.