Sesiones de Django

keenauth.bff.django añade inicio de sesión a una aplicación de Django 4.2 o posterior. Su servidor es el cliente OAuth y mantiene todos los tokens en el servidor. El navegador solo recibe una cookie de sesión cifrada y HttpOnly, y nunca ve un token de acceso, de actualización ni de ID. Este es el patrón backend-for-frontend (BFF). Forma parte de keenauth-python, que todavía no se publica en PyPI.

Para proteger una API que recibe tokens bearer, consulte Proteger su API.

Instalar

pip install "keenauth-python[django]"

Antes de empezar

1. En el panel, cree una aplicación web en su entorno.
2. Elija la autenticación del cliente: private_key_jwt (recomendado, PrivateKeyJwt) o un secreto de cliente (ClientSecretBasic).
3. Añada la URI de redirección https://app.acme.example/auth/callback y la URI de redirección tras cerrar sesión https://app.acme.example/.
4. Genere un secreto para la cookie de al menos 32 caracteres, por ejemplo con openssl rand -base64 32. Guárdelo en su almacén de secretos, no en el repositorio.

Crear la instancia

import os
from keenauth.bff import BffOptions, ClientSecretBasic, KeenAuthBff

bff = KeenAuthBff(BffOptions(
    issuer="https://acme.eu.keenauth.app",  # your environment's issuer, exactly
    client_id="app_01j9zzzzzzzzzzzzzzzzzzzz",
    client_auth=ClientSecretBasic(os.environ["KEENAUTH_CLIENT_SECRET"]),
    app_base_url="https://app.acme.example",
    secret=os.environ["KEENAUTH_COOKIE_SECRET"],
))

app_base_url es la dirección pública de su aplicación. El SDK construye a partir de ella la URI de redirección y todas las redirecciones, nunca a partir de los encabezados Host o X-Forwarded-* de la solicitud. El http simple solo se acepta para localhost. Las opciones se validan al crear KeenAuthBff, de modo que un error de configuración detiene la aplicación durante el arranque.

Usar private_key_jwt

Con private_key_jwt, la aplicación no tiene ningún secreto compartido. Proporcione a PrivateKeyJwt su clave privada, y el SDK firma una nueva aserción de cliente (RFC 7523) para cada solicitud al endpoint de tokens:

from keenauth.bff import PrivateKeyJwt

client_auth = PrivateKeyJwt(key=os.environ["KEENAUTH_PRIVATE_KEY"])  # unencrypted PEM

• Claves admitidas: EC P-256 (ES256), EC P-384 (ES384), Ed25519 (EdDSA) y RSA de al menos 2048 bits (PS256 por defecto; pase algorithm="RS256" para RS256).
• Cada aserción tiene iss y sub con el ID de su cliente, aud con el emisor, un jti aleatorio y una vida útil de 60 segundos. Su kid es la huella RFC 7638 de la clave pública.
• Registre la clave pública en la aplicación. keenauth.m2m.load_private_key(pem).public_jwk() la devuelve como JWK.

Para firmar con su propio servicio de claves (un KMS o HSM), pase una función en su lugar: PrivateKeyJwt(assertion=sign). sign() debe devolver una nueva aserción firmada en cada llamada.

Añadir el middleware

# settings.py
KEENAUTH_BFF = "myproject.auth.bff"  # dotted path to the KeenAuthBff instance
MIDDLEWARE = [
    # ...
    "keenauth.bff.django.KeenAuthMiddleware",
]

El middleware sirve las rutas siguientes y lee la sesión en cada una de las demás solicitudes en request.keenauth.

# views.py
from django.http import HttpResponse
from keenauth.bff.django import require_auth

@require_auth()
def orders(request):
    return HttpResponse(f"Signed in as {request.keenauth.session.user.email}")

Rutas

El inicio de sesión usa el flujo de código de autorización con PKCE (S256). La solicitud se envía al servidor (PAR) cuando su entorno lo ofrece. En el callback, el SDK comprueba state, iss y el token de ID, incluido su nonce. Cada inicio de sesión correcto crea una sesión nueva; la anterior se descarta.

returnTo debe ser una ruta de su propia aplicación, como /orders?tab=open. Cualquier otro valor, como //evil.example o una URL completa, se ignora y el usuario llega a /.

Vistas protegidas

Decore una vista con @require_auth().

Sin una sesión:

• una solicitud de página (GET o HEAD) se redirige a /auth/login con returnTo;
• una solicitud a /api/…, o con otro método, recibe 401 con un documento de problema. Pase api=True para responder 401 en cualquier ruta.

Para POST, PUT, PATCH, DELETE y otros métodos no seguros, el navegador debe indicar que la solicitud proviene de su aplicación: Sec-Fetch-Site: same-origin, o un encabezado Origin igual al origen de su aplicación. Las demás solicitudes reciben 403. Esto protege contra la falsificación de solicitudes entre sitios, además de SameSite=Lax.

Usar la sesión y llamar a su API

El contexto de sesión tiene:

• session: None, o el usuario con sesión iniciada. session.user tiene las notificaciones tipadas del token de ID, como subject, email, name, org_id y org_roles; todas las notificaciones están en session.user.claims. El objeto de sesión nunca contiene un token.
• access_token: un token de acceso válido para llamadas del lado del servidor, o None. No lo envíe al navegador.

Cuando el token de acceso caduca en menos de 60 segundos, el SDK lo actualiza antes de que se ejecute su vista. Cada actualización rota el token de actualización y establece la nueva cookie de sesión en la respuesta. Si el servidor rechaza el token de actualización, la sesión termina. Un error temporal del servidor deja la sesión sin cambios. Las solicitudes concurrentes en un mismo proceso comparten una sola actualización.

Cambiar de organización

bff.switch_organization_path("org_01j9…", "/dashboard") devuelve un enlace a /auth/login que vuelve a iniciar sesión al usuario en esa organización. KeenAuth comprueba la pertenencia. Tras el inicio de sesión, session.user.org_id contiene la organización.

Cerrar sesión

Envíe un POST a /auth/logout desde un formulario. El SDK elimina la cookie de sesión (y la sesión almacenada, si usa un almacén), revoca el token de actualización y envía el navegador al endpoint de cierre de sesión de su entorno, que lo devuelve a su aplicación. Se rechaza una solicitud que el navegador marca como procedente de otro sitio. Los navegadores que no envían Sec-Fetch-Site solo pueden cerrar sesión con un POST desde sus propias páginas.

Almacenamiento de sesiones

Por defecto, toda la sesión está en la cookie, cifrada y autenticada con AES-256-GCM usando una clave derivada de secret. Una cookie modificada o copiada se rechaza. La cookie se llama __Host-keenauth_session.0 y se establece con Secure, HttpOnly, SameSite=Lax y Path=/. En http://localhost se omiten el prefijo __Host- y Secure. Las sesiones grandes se dividen en hasta tres cookies.

Para mantener los tokens en el servidor, pase store= con un objeto que tenga get(id), set(id, session, ttl_seconds) y delete(id), por ejemplo respaldado por Redis. La cookie contiene entonces solo un ID de sesión aleatorio y cifrado. Cada inicio de sesión crea un ID nuevo y elimina el registro anterior. El almacén contiene tokens, así que restrinja su acceso. MemorySessionStore es solo para desarrollo y pruebas.

Una sesión dura como máximo 7 días (session_max_age); actualizar no la extiende. Para cambiar el secreto, pase una lista: secret=[new_secret, old_secret]. Elimine el antiguo después de session_max_age.

Límites actuales

• Los tokens vinculados a DPoP y el cierre de sesión de canal trasero todavía no se gestionan.
• Las actualizaciones compartidas solo se dan dentro de un mismo proceso del servidor. Con varios procesos, el ajuste de la aplicación refresh_reuse_interval_s (por defecto 5 segundos) permite que una actualización en paralelo tenga éxito; si lo establece en 0, la segunda actualización termina la sesión.