auth-guardian 0.0.1__tar.gz

auth_guardian-0.0.1/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: auth-guardian
+Version: 0.0.1
+Summary: Reusable Keycloak SDK for auth-service and microservices
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<0.29,>=0.28
+Requires-Dist: python-jose[cryptography]<4,>=3.5
+Provides-Extra: fastapi
+Requires-Dist: fastapi<0.119,>=0.118; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.3; extra == "dev"
+Requires-Dist: mypy<2,>=1.10; extra == "dev"
+Requires-Dist: pytest<9,>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=1.2; extra == "dev"
+Requires-Dist: respx<0.23,>=0.22; extra == "dev"
+Requires-Dist: ruff<0.15,>=0.14; extra == "dev"
+Requires-Dist: twine<7,>=6.2; extra == "dev"
+
+# Auth Guardian 
+
+**Auth Guardian** es un SDK extremadamente simple, *plug-and-play* y agnóstico, diseñado para proteger aplicaciones y microservicios en Python utilizando Keycloak (u otros proveedores OIDC compatibles).
+
+Ha sido diseñado para evitar configuraciones redundantes: con un par de variables de entorno, tu aplicación tendrá flujos de login, logout, callbacks y validación de roles y permisos automáticamente.
+
+---
+
+##  Instalación
+
+```bash
+pip install auth-guardian==0.0.1
+```
+
+---
+
+##  Configuración (Plug-and-Play)
+
+`AuthGuardian` es lo suficientemente inteligente como para configurarse por sí mismo. Solo necesitas definir las siguientes variables de entorno:
+
+```env
+AUTH_BASE_URL=https://auth.tu-dominio.com
+AUTH_REALM=tu-realm
+AUTH_CLIENT_ID=tu-cliente
+```
+
+> **Nota:** También soporta las variables legacy `KEYCLOAK_BASE_URL`, `KEYCLOAK_REALM` y `KEYCLOAK_CLIENT_ID` de forma automática.
+
+---
+
+##  Uso en FastAPI
+
+### 1. Inyectando Rutas Automáticas (Login, Logout, Callback)
+Para aplicaciones frontend/Fullstack, `AuthGuardian` puede inyectar los endpoints completos del flujo OIDC (`/login`, `/logout`, `/oidc/callback`) para que no tengas que escribirlos:
+
+```python
+from fastapi import FastAPI
+from auth_guardian import AuthGuardian, create_auth_router
+
+app = FastAPI()
+
+# 1. Instancia el guardián
+auth = AuthGuardian()
+
+# 2. Crea el router que manejará automáticamente login, callback y logout
+auth_router = create_auth_router(
+    auth=auth,
+    oidc_state_secret="tu_secreto_super_seguro_para_estado",
+    login_redirect_url="/dashboard", # Dónde enviar al usuario tras loguearse
+    logout_redirect_url="/login"     # Dónde enviar al usuario tras desloguearse
+)
+
+# 3. Registra el router en tu app
+app.include_router(auth_router)
+```
+
+**¡Eso es todo!** Automáticamente tienes:
+- `GET /login` -> Redirige al login de Keycloak.
+- `GET /oidc/callback` -> Maneja el intercambio de código, genera las cookies seguras e inicia la sesión local.
+- `GET /logout` -> Elimina cookies y redirige al cierre de sesión de Keycloak.
+
+### 2. Protegiendo tus Endpoints (Para Principiantes)
+En FastAPI, "proteger" una ruta significa que si alguien entra sin haber iniciado sesión, el sistema le bloqueará el acceso automáticamente.
+
+Para lograr esto, FastAPI usa algo llamado `Depends` (Dependencias). Si agregas `Depends(auth.get_current_user)` en tu función, AuthGuardian se encargará de verificar si el usuario tiene sesión activa antes de ejecutar el código.
+
+**Ejemplo 1: Bloquear acceso a usuarios no logueados**
+```python
+from fastapi import Depends
+
+@app.get("/recurso-seguro")
+async def get_seguro(user: dict = Depends(auth.get_current_user)):
+    # Si llega aquí, es porque el usuario SÍ está logueado.
+    # 'user' contendrá la información de su perfil.
+    return {
+        "mensaje": f"Hola {user.get('preferred_username')}",
+        "email": user.get('email')
+    }
+```
+
+**Ejemplo 2: Bloquear acceso según el Rol del usuario**
+Si tienes zonas exclusivas (como un panel de administrador), puedes usar `auth.require_role("nombre_del_rol")`.
+
+```python
+@app.get("/zona-admin")
+async def get_admin(user: dict = Depends(auth.require_role("admin"))):
+    # Solo entrarán usuarios que se hayan logueado y que tengan el rol "admin"
+    return {"mensaje": "¡Bienvenido, administrador!"}
+```
+
+---
+
+##  Opciones Avanzadas
+
+### Validación Manual de Tokens
+Si no usas FastAPI o necesitas validar un token manualmente, el SDK expone internamente el validador:
+
+```python
+payload = await auth.validator.decode_access_token("eyJhbGciOiJIUz...")
+print(payload)
+```
+
+### Hook Personalizado de Login
+Al usar `create_auth_router`, puedes inyectar un hook que se ejecute justo cuando el usuario hace login exitosamente (por ejemplo, para guardar/actualizar el usuario en tu base de datos):
+
+```python
+async def sync_user_in_db(payload: dict):
+    email = payload.get("email")
+    print(f"Sincronizando usuario {email} en base de datos...")
+
+auth_router = create_auth_router(
+    auth=auth,
+    oidc_state_secret="secreto",
+    on_login_success=sync_user_in_db # Se ejecuta después del callback, antes de redirigir
+)
+```
+
+---
+
+##  Contrato Público API
+
+El contrato público exportado es estable y mantenido a través del `__init__.py`.
+
+- `AuthGuardian`: Clase principal y Facade de autenticación.
+- `create_auth_router`: Constructor automático de endpoints OIDC para FastAPI.
+- `extract_client_roles(payload, client_id)`: Función helper para extraer los roles.
+- `AuthConfig`, `AuthTokenValidator`, `AuthOIDCClient`: Accesibles para usos complejos o manuales.
+- Manejo de Errores: `KeycloakAuthError`, `TokenValidationError`, `KeycloakAPIError`.
+
+---
+
+## Desarrollo Local
+
+```bash
+pip install .[dev]
+pytest tests/
+ruff check src/ tests/
+mypy src/auth_guardian
+```

auth_guardian-0.0.1/README.md

@@ -0,0 +1,139 @@
+# Auth Guardian 
+
+**Auth Guardian** es un SDK extremadamente simple, *plug-and-play* y agnóstico, diseñado para proteger aplicaciones y microservicios en Python utilizando Keycloak (u otros proveedores OIDC compatibles).
+
+Ha sido diseñado para evitar configuraciones redundantes: con un par de variables de entorno, tu aplicación tendrá flujos de login, logout, callbacks y validación de roles y permisos automáticamente.
+
+---
+
+##  Instalación
+
+```bash
+pip install auth-guardian==0.0.1
+```
+
+---
+
+##  Configuración (Plug-and-Play)
+
+`AuthGuardian` es lo suficientemente inteligente como para configurarse por sí mismo. Solo necesitas definir las siguientes variables de entorno:
+
+```env
+AUTH_BASE_URL=https://auth.tu-dominio.com
+AUTH_REALM=tu-realm
+AUTH_CLIENT_ID=tu-cliente
+```
+
+> **Nota:** También soporta las variables legacy `KEYCLOAK_BASE_URL`, `KEYCLOAK_REALM` y `KEYCLOAK_CLIENT_ID` de forma automática.
+
+---
+
+##  Uso en FastAPI
+
+### 1. Inyectando Rutas Automáticas (Login, Logout, Callback)
+Para aplicaciones frontend/Fullstack, `AuthGuardian` puede inyectar los endpoints completos del flujo OIDC (`/login`, `/logout`, `/oidc/callback`) para que no tengas que escribirlos:
+
+```python
+from fastapi import FastAPI
+from auth_guardian import AuthGuardian, create_auth_router
+
+app = FastAPI()
+
+# 1. Instancia el guardián
+auth = AuthGuardian()
+
+# 2. Crea el router que manejará automáticamente login, callback y logout
+auth_router = create_auth_router(
+    auth=auth,
+    oidc_state_secret="tu_secreto_super_seguro_para_estado",
+    login_redirect_url="/dashboard", # Dónde enviar al usuario tras loguearse
+    logout_redirect_url="/login"     # Dónde enviar al usuario tras desloguearse
+)
+
+# 3. Registra el router en tu app
+app.include_router(auth_router)
+```
+
+**¡Eso es todo!** Automáticamente tienes:
+- `GET /login` -> Redirige al login de Keycloak.
+- `GET /oidc/callback` -> Maneja el intercambio de código, genera las cookies seguras e inicia la sesión local.
+- `GET /logout` -> Elimina cookies y redirige al cierre de sesión de Keycloak.
+
+### 2. Protegiendo tus Endpoints (Para Principiantes)
+En FastAPI, "proteger" una ruta significa que si alguien entra sin haber iniciado sesión, el sistema le bloqueará el acceso automáticamente.
+
+Para lograr esto, FastAPI usa algo llamado `Depends` (Dependencias). Si agregas `Depends(auth.get_current_user)` en tu función, AuthGuardian se encargará de verificar si el usuario tiene sesión activa antes de ejecutar el código.
+
+**Ejemplo 1: Bloquear acceso a usuarios no logueados**
+```python
+from fastapi import Depends
+
+@app.get("/recurso-seguro")
+async def get_seguro(user: dict = Depends(auth.get_current_user)):
+    # Si llega aquí, es porque el usuario SÍ está logueado.
+    # 'user' contendrá la información de su perfil.
+    return {
+        "mensaje": f"Hola {user.get('preferred_username')}",
+        "email": user.get('email')
+    }
+```
+
+**Ejemplo 2: Bloquear acceso según el Rol del usuario**
+Si tienes zonas exclusivas (como un panel de administrador), puedes usar `auth.require_role("nombre_del_rol")`.
+
+```python
+@app.get("/zona-admin")
+async def get_admin(user: dict = Depends(auth.require_role("admin"))):
+    # Solo entrarán usuarios que se hayan logueado y que tengan el rol "admin"
+    return {"mensaje": "¡Bienvenido, administrador!"}
+```
+
+---
+
+##  Opciones Avanzadas
+
+### Validación Manual de Tokens
+Si no usas FastAPI o necesitas validar un token manualmente, el SDK expone internamente el validador:
+
+```python
+payload = await auth.validator.decode_access_token("eyJhbGciOiJIUz...")
+print(payload)
+```
+
+### Hook Personalizado de Login
+Al usar `create_auth_router`, puedes inyectar un hook que se ejecute justo cuando el usuario hace login exitosamente (por ejemplo, para guardar/actualizar el usuario en tu base de datos):
+
+```python
+async def sync_user_in_db(payload: dict):
+    email = payload.get("email")
+    print(f"Sincronizando usuario {email} en base de datos...")
+
+auth_router = create_auth_router(
+    auth=auth,
+    oidc_state_secret="secreto",
+    on_login_success=sync_user_in_db # Se ejecuta después del callback, antes de redirigir
+)
+```
+
+---
+
+##  Contrato Público API
+
+El contrato público exportado es estable y mantenido a través del `__init__.py`.
+
+- `AuthGuardian`: Clase principal y Facade de autenticación.
+- `create_auth_router`: Constructor automático de endpoints OIDC para FastAPI.
+- `extract_client_roles(payload, client_id)`: Función helper para extraer los roles.
+- `AuthConfig`, `AuthTokenValidator`, `AuthOIDCClient`: Accesibles para usos complejos o manuales.
+- Manejo de Errores: `KeycloakAuthError`, `TokenValidationError`, `KeycloakAPIError`.
+
+---
+
+## Desarrollo Local
+
+```bash
+pip install .[dev]
+pytest tests/
+ruff check src/ tests/
+mypy src/auth_guardian
+```

auth_guardian-0.0.1/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "auth-guardian"
+version = "0.0.1"
+description = "Reusable Keycloak SDK for auth-service and microservices"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.28,<0.29",
+  "python-jose[cryptography]>=3.5,<4",
+]
+
+[project.optional-dependencies]
+fastapi = [
+  "fastapi>=0.118,<0.119",
+]
+dev = [
+  "build>=1.3,<2",
+  "mypy>=1.10,<2",
+  "pytest>=8.3,<9",
+  "pytest-asyncio>=1.2,<2",
+  "respx>=0.22,<0.23",
+  "ruff>=0.14,<0.15",
+  "twine>=6.2,<7",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/auth_guardian/fastapi.py" = ["B008"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_return_any = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+
+[[tool.mypy.overrides]]
+module = ["jose", "jose.*", "respx.*", "fastapi", "fastapi.*"]
+ignore_missing_imports = true

auth_guardian-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

auth_guardian-0.0.1/src/auth_guardian/__init__.py

@@ -0,0 +1,38 @@
+"""Public contract for auth-guardian.
+
+Keep this module intentionally small and stable to avoid breaking microservices.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from auth_guardian.config import AuthConfig
+from auth_guardian.core import AuthGuardian
+from auth_guardian.exceptions import KeycloakAPIError, KeycloakAuthError, TokenValidationError
+from auth_guardian.oidc_client import AuthOIDCClient
+from auth_guardian.roles import extract_client_roles
+from auth_guardian.router import create_auth_router
+from auth_guardian.state import generate_signed_state, verify_signed_state
+from auth_guardian.token_validator import AuthTokenValidator
+
+try:
+    __version__ = version("auth-guardian")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"
+
+__all__ = [
+    "__version__",
+    "AuthGuardian",
+    "AuthConfig",
+    "AuthTokenValidator",
+    "AuthOIDCClient",
+    "TokenValidationError",
+    "KeycloakAuthError",
+    "KeycloakAPIError",
+    "create_auth_router",
+    "extract_client_roles",
+    "generate_signed_state",
+    "verify_signed_state",
+]

auth_guardian-0.0.1/src/auth_guardian/config.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AuthConfig:
+    base_url: str
+    realm: str
+    client_id: str
+    client_secret: str | None = None
+    issuer: str | None = None
+    internal_url: str | None = None
+    state_secret: str | None = None
+    verify_tls: bool = True
+    request_timeout_seconds: float = 20.0
+    jwks_cache_ttl_seconds: int = 300
+
+    @property
+    def frontend_realm_url(self) -> str:
+        return f"{self.base_url.rstrip('/')}/realms/{self.realm}"
+
+    @property
+    def backend_realm_url(self) -> str:
+        base = (self.internal_url or self.base_url).rstrip("/")
+        return f"{base}/realms/{self.realm}"
+
+    @property
+    def admin_realm_url(self) -> str:
+        base = (self.internal_url or self.base_url).rstrip("/")
+        return f"{base}/admin/realms/{self.realm}"
+
+    @property
+    def expected_issuer(self) -> str:
+        return self.issuer or self.frontend_realm_url

auth_guardian-0.0.1/src/auth_guardian/core.py

@@ -0,0 +1,113 @@
+import os
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from fastapi import Depends, HTTPException, Request, Response, Security
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from auth_guardian.config import AuthConfig
+from auth_guardian.exceptions import KeycloakAPIError, TokenValidationError
+from auth_guardian.oidc_client import AuthOIDCClient
+from auth_guardian.roles import extract_client_roles
+from auth_guardian.token_validator import AuthTokenValidator
+
+security = HTTPBearer(auto_error=False)
+
+
+class AuthGuardian:
+    """
+    A simple facade to integrate authentication into FastAPI applications.
+    It automatically reads from environment variables if not explicitly provided.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        realm: str | None = None,
+        client_id: str | None = None,
+        state_secret: str | None = None,
+        **kwargs: Any,
+    ):
+        base_url = base_url or os.getenv("AUTH_BASE_URL") or os.getenv("KEYCLOAK_BASE_URL") or ""
+        realm = realm or os.getenv("AUTH_REALM") or os.getenv("KEYCLOAK_REALM") or ""
+        client_id = client_id or os.getenv("AUTH_CLIENT_ID") or os.getenv("KEYCLOAK_CLIENT_ID") or ""
+        state_secret = state_secret or os.getenv("AUTH_STATE_SECRET") or os.getenv("KEYCLOAK_STATE_SECRET")
+
+        self.config = AuthConfig(
+            base_url=base_url,
+            realm=realm,
+            client_id=client_id,
+            state_secret=state_secret,
+            **kwargs,
+        )
+        self.validator = AuthTokenValidator(self.config)
+        self.oidc_client = AuthOIDCClient(self.config)
+
+    async def get_current_user(
+        self,
+        request: Request,
+        response: Response,
+        credentials: HTTPAuthorizationCredentials | None = Security(security),
+    ) -> dict[str, Any]:
+        """
+        FastAPI dependency to get the authenticated user's token payload.
+        Handles silent token refreshing if the token is expired and a valid refresh token exists.
+        """
+        token = credentials.credentials if credentials else request.cookies.get("access_token")
+        cookie_name = "access_token"
+        if not token:
+            token = request.cookies.get("pfx_token")
+            if token:
+                cookie_name = "pfx_token"
+
+        if not token:
+            raise HTTPException(status_code=401, detail="Not authenticated")
+
+        try:
+            return await self.validator.decode_access_token(token)
+        except TokenValidationError as exc:
+            if "expirado" in exc.detail.lower() or "expired" in exc.detail.lower():
+                refresh_token = request.cookies.get("refresh_token")
+                if not refresh_token:
+                    refresh_token = request.cookies.get("pfx_refresh_token")
+
+                if refresh_token:
+                    try:
+                        token_data = await self.oidc_client.refresh_access_token(refresh_token)
+                        new_access_token = token_data["access_token"]
+                        new_refresh_token = token_data.get("refresh_token", refresh_token)
+                        
+                        # Set new cookies on the response object
+                        is_prod = os.getenv("IS_PROD", "false").lower() == "true"
+                        response.set_cookie(
+                            cookie_name,
+                            new_access_token,
+                            httponly=True,
+                            samesite="lax",
+                            secure=is_prod,
+                        )
+                        response.set_cookie(
+                            "refresh_token" if not request.cookies.get("pfx_refresh_token") else "pfx_refresh_token",
+                            new_refresh_token,
+                            httponly=True,
+                            samesite="lax",
+                            secure=is_prod,
+                        )
+                        
+                        return await self.validator.decode_access_token(new_access_token)
+                    except (KeycloakAPIError, TokenValidationError):
+                        pass
+
+            raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
+
+    def require_role(self, *required_roles: str) -> Callable[..., Awaitable[dict[str, Any]]]:
+        """
+        FastAPI dependency factory to require specific roles.
+        """
+        async def _role_guard(user: dict[str, Any] = Depends(self.get_current_user)) -> dict[str, Any]:
+            roles = set(extract_client_roles(user, self.config.client_id))
+            if not roles.intersection(required_roles):
+                raise HTTPException(status_code=403, detail="Insufficient permissions")
+            return user
+
+        return _role_guard

auth_guardian-0.0.1/src/auth_guardian/exceptions.py

@@ -0,0 +1,16 @@
+class KeycloakAuthError(Exception):
+    def __init__(self, detail: str, status_code: int = 401):
+        super().__init__(detail)
+        self.detail = detail
+        self.status_code = status_code
+
+
+class TokenValidationError(KeycloakAuthError):
+    pass
+
+
+class KeycloakAPIError(Exception):
+    def __init__(self, detail: str, status_code: int = 502):
+        super().__init__(detail)
+        self.detail = detail
+        self.status_code = status_code