auth-guardian 0.1.16

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

Todo lo que necesitas está disponible directamente desde auth_guardian. Aquí un resumen de qué hace cada cosa y cuándo la usarías:

from auth_guardian import (
    AuthGuardian,           # Lo primero que instancias. Da acceso a get_current_user y require_role.
    create_auth_router,     # Crea las rutas /login, /oidc/callback y /logout para registrar en tu app.
    extract_client_roles,   # Función de utilidad: extrae los roles de un cliente a partir del token decodificado.
    AuthConfig,             # Si necesitas personalizar la configuración más allá de las variables de entorno.
    AuthTokenValidator,     # Validador de tokens. Úsalo si quieres extender o reemplazar la lógica de validación.
    AuthOIDCClient,         # Cliente que habla con Keycloak. Útil si necesitas hacer llamadas OIDC directamente.
    KeycloakAuthError,      # Excepción: el usuario no está autenticado o su sesión no es válida.
    TokenValidationError,   # Excepción: el token existe pero no pasa la validación.
    KeycloakAPIError,       # Excepción: no se pudo comunicar con Keycloak (timeout, caída, etc.).
)

Para el uso habitual solo necesitas AuthGuardian y create_auth_router. El resto está disponible si quieres extender el comportamiento o manejar errores de forma personalizada.

---

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