auth-guardian 0.1.6

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

Revocacion de tokens

Por defecto AuthGuardian usa memoria local:

• Logout revoca el refresh_token en Keycloak inmediatamente.
• Logout borra cookies del navegador.
• El access_token queda en blacklist local hasta que expire.

Para multi-instancia con revocacion global, implementa RevocationBackend:

from auth_guardian import AuthGuardian, RevocationBackend


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

    async def is_revoked(self, jti: str) -> bool:
        ...


auth = AuthGuardian(revocation_backend=MiRedisBackend())

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