# 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](/docs/sdk/protect-api).

## Instalar

```sh
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

```python
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:

```python
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

```python
# 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`.

```python
# 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

| Ruta | Qué hace |
|---|---|
| `GET /auth/login` | Inicia el inicio de sesión. Parámetros de consulta opcionales: `returnTo` (a dónde llega el usuario) y `organization` (iniciar sesión en una organización). |
| `GET /auth/callback` | Completa el inicio de sesión y establece la cookie de sesión. |
| `GET` o `POST /auth/logout` | Cierra la sesión en KeenAuth y vuelve a su aplicación. |

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.