auth-guardian 0.1.21

Libreria de autenticacion OIDC con Keycloak para FastAPI

Auth Guardian

Librería para integrar FastAPI con Keycloak sin complicarte con OIDC desde cero.

---

¿Para qué sirve?

Con auth-guardian tienes listo:

• Login OIDC con Keycloak.
• Rutas /login, /oidc/callback y /logout.
• Protección de endpoints autenticados.
• Protección por rol (admin, etc.).
• Validación en tiempo real por introspection.
• Logout con revocación inmediata del refresh token.

---

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=
KEYCLOAK_REALM=
KEYCLOAK_CLIENT_ID=
KEYCLOAK_CLIENT_SECRET=

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

La forma más simple:

1. Copia el archivo de ejemplo:
   • examples/auth.py
2. Levántalo:

uvicorn examples.auth:app --reload

Ese ejemplo ya trae todo:

• login
• callback
• logout
• endpoint protegido (/perfil)
• endpoint por rol (/admin)
• registro opcional (/register)

Si quieres activar /register, agrega:

AUTH_ENABLE_REGISTER=true
KEYCLOAK_ADMIN_CLIENT_ID=
KEYCLOAK_ADMIN_CLIENT_SECRET=

Si prefieres integrarlo manualmente en tu propia app, este es el mínimo:

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

@app.get("/perfil")
async def perfil(user: dict = Depends(auth.get_current_user)):
    return user

---

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 valida el token en cada request consultando a Keycloak en tiempo real mediante /token/introspect.

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

Uso habitual:

• AuthGuardian
• create_auth_router
• auth.get_current_user
• auth.require_role

---

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