auth-guardian 0.1.15

Libreria de autenticacion OIDC con Keycloak para FastAPI

Auth Guardian

Librería Python para integrar autenticación OIDC con Keycloak en FastAPI — con foco en seguridad, revocación inmediata y configuración mínima.

---

¿Qué resuelve?

Sin auth-guardian tendrías que implementar a mano el flujo OIDC completo, la validación de tokens, el manejo de cookies y la revocación en logout. Con esta librería, todo eso queda resuelto en unas pocas líneas:

Problema	Solución
Flujo OIDC completo	Rutas /login, /oidc/callback, /logout listas para usar
Protección de endpoints	Depends(auth.get_current_user)
Control de acceso por rol	Depends(auth.require_role("admin"))
Validación de token en cada request	Introspection contra Keycloak (activo por defecto)
Revocación inmediata en logout	Revoke del refresh token + invalidación por introspection

---

Instalación

pip install auth-guardian

Requisitos: Python >= 3.10

---

Configuración rápida

1. Variables de entorno obligatorias

La librería falla al iniciar con un mensaje claro si falta alguna de estas:

KEYCLOAK_BASE_URL=https://auth.tudominio.com
KEYCLOAK_REALM=tu-realm
KEYCLOAK_CLIENT_ID=tu-cliente
KEYCLOAK_CLIENT_SECRET=tu-secreto

KEYCLOAK_CLIENT_SECRET se usa tanto para introspection como para firmar/verificar el state anti-CSRF.

2. Configuración en Keycloak

Antes de arrancar, verifica que tu cliente en Keycloak esté configurado correctamente:

1. Crear cliente de tipo OIDC.
2. Activar Client authentication (cliente confidencial).
3. Configurar el Client Secret.
4. Agregar la Redirect URI de tu app para el callback OIDC.
5. Asignar roles en realm o client según tu modelo de autorización.

---

Integración con FastAPI

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

app = FastAPI()
auth = AuthGuardian()

# Registra /login, /oidc/callback y /logout automáticamente
app.include_router(
    create_auth_router(
        auth=auth,
        login_redirect_url="/dashboard",
        logout_redirect_url="/login",
    )
)

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

# Endpoint protegido por autenticación
@app.get("/perfil")
async def perfil(user: dict = Depends(auth.get_current_user)):
    return {
        "mensaje": f"Hola {user.get('preferred_username')}",
        "email": user.get("email"),
    }

# Endpoint protegido por rol
@app.get("/admin")
async def admin(user: dict = Depends(auth.require_role("admin"))):
    return {"mensaje": "Acceso permitido para rol admin"}

Con solo esto tienes los tres endpoints de autenticación y protección granular por usuario o por rol.

---

Flujos de autenticación

1. Login OIDC

El usuario accede a /login y es redirigido al servidor Keycloak. Una vez que ingresa sus credenciales, Keycloak devuelve un code al callback, que la librería intercambia por los tokens.

---

2. Request protegido (introspection)

En cada request a un endpoint protegido, el token del cliente es validado en tiempo real contra Keycloak. No hay caché ni validación local por defecto.

---

3. Logout

El logout revoca el refresh token en Keycloak antes de borrar las cookies, garantizando que la sesión quede inválida de inmediato en el servidor.

---

Validación de token

AuthGuardian usa introspection por defecto — cada request verifica el token contra Keycloak en tiempo real.

Modo	Comportamiento
introspection (default)	Llama a /token/introspect en cada request

Comportamiento ante errores:

Situación	Respuesta
active: false	401 Unauthorized
Keycloak no disponible	503 Service Unavailable (sin exponer detalles internos)
API de Keycloak caída	Falla introspection aunque la BD de Keycloak esté activa

---

API pública estable

Estos son los símbolos exportados que puedes importar directamente:

from auth_guardian import (
    AuthGuardian,           # Clase principal — instanciar y usar con Depends()
    create_auth_router,     # Genera el router OIDC para FastAPI
    extract_client_roles,   # Extrae roles de client del payload JWT
    AuthConfig,             # Configuración interna
    AuthTokenValidator,     # Validador de tokens
    AuthOIDCClient,         # Cliente OIDC hacia Keycloak
    KeycloakAuthError,      # Error de autenticación con Keycloak
    TokenValidationError,   # Error de validación de token
    KeycloakAPIError,       # Error de comunicación con la API de Keycloak
)

---

Troubleshooting

Missing required configuration variables

Causa: Falta una o más variables de entorno obligatorias.

Solución: Completar las cuatro variables en tu .env:

KEYCLOAK_BASE_URL=
KEYCLOAK_REALM=
KEYCLOAK_CLIENT_ID=
KEYCLOAK_CLIENT_SECRET=

---

Introspection devuelve 401 o 403

Causa: El cliente no está configurado como confidencial en Keycloak, o el secret es incorrecto.

Solución:

• Verificar KEYCLOAK_CLIENT_SECRET en tu .env.
• Confirmar que el cliente tiene Client authentication activado en Keycloak.

---

Login falla en callback (Redirect URI mismatch)

Causa: La Redirect URI configurada en Keycloak no coincide con la que usa la app.

Solución:

• Revisar la Valid Redirect URIs del cliente en Keycloak.
• Si estás detrás de un proxy inverso, verificar que se pasen correctamente las cabeceras Host y X-Forwarded-*.