auth-guardian 0.1.7

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

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

Revocación de tokens

Escenario	Comportamiento
Single instance (default)	Revocación inmediata en memoria local
Multi-instancia	Token válido hasta expirar en otras instancias
Con RevocationBackend propio	Revocación inmediata global

Al hacer logout, siempre ocurre:

• refresh_token revocado en Keycloak (no puede renovarse)
• Cookies borradas del navegador
• access_token en blacklist local hasta expirar

Para multi-instancia, implementa RevocationBackend con tu stack:

from auth_guardian import AuthGuardian, RevocationBackend

class SharedCacheRevocationBackend(RevocationBackend):
    async def revoke(self, jti: str, ttl: int) -> None: ...
    async def is_revoked(self, jti: str) -> bool: ...

auth = AuthGuardian(revocation_backend=SharedCacheRevocationBackend())

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

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