Sesiones de Express

@keenauth/node/bff añade el inicio de sesión a una aplicación Express 4 o 5. Su servidor es el cliente OAuth y conserva 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). El paquete no importa Express, así que no añade ninguna dependencia. Todavía no se ha publicado en npm.

Para proteger una API que recibe tokens de portador, consulte Protección de su API. Para llamar a la API de gestión, consulte el SDK de gestión para Node.js.

Antes de empezar

1. En el panel, cree una aplicación web en su entorno.
2. Elija la autenticación del cliente: un secreto de cliente (client_secret_basic) o private_key_jwt con un par de claves cuya clave pública registre en la aplicación. Se recomienda private_key_jwt, porque ningún secreto compartido sale de su servidor.
3. Añada el URI de redirección https://app.acme.example/auth/callback y el 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.

Configuración

import express from "express";
import { createBff, expressRequireAuth, expressSession } from "@keenauth/node/bff";

const bff = createBff({
  issuer: "https://acme.eu.keenauth.app", // your environment's issuer, exactly
  clientId: "app_01j9zzzzzzzzzzzzzzzzzzzz",
  clientAuth: { method: "client_secret_basic", clientSecret: process.env.KEENAUTH_CLIENT_SECRET! },
  appBaseUrl: "https://app.acme.example",
  secret: process.env.KEENAUTH_COOKIE_SECRET!,
});

const app = express();
app.use(expressSession(bff));

app.get("/orders", expressRequireAuth(bff), (req, res) => {
  const { session } = req.keenauth!;
  res.send(`Signed in as ${session!.user.email}`);
});

Con private_key_jwt, pase la clave privada en lugar del secreto. El SDK firma una nueva aserción de cliente para cada solicitud al endpoint de token y de PAR (aud es el emisor, jti es aleatorio, válido durante 120 segundos, kid es la huella RFC 7638 de la clave). El algoritmo depende de la clave: RS256 para RSA (o alg: "PS256"), ES256 para P-256 y EdDSA para Ed25519.

import { readFileSync } from "node:fs";

const bff = createBff({
  issuer: "https://acme.eu.keenauth.app",
  clientId: "app_01j9zzzzzzzzzzzzzzzzzzzz",
  clientAuth: { method: "private_key_jwt", privateKey: readFileSync("bff-key.pem", "utf8") },
  appBaseUrl: "https://app.acme.example",
  secret: process.env.KEENAUTH_COOKIE_SECRET!,
});

Si la clave está en un KMS o en un HSM, pase en su lugar clientAuth: { method: "private_key_jwt", assertion }, donde assertion() devuelve una nueva aserción de cliente firmada cada vez. Pase privateKey o assertion, pero no ambos.

appBaseUrl es la dirección pública de su aplicación. El SDK construye a partir de ella el URI de redirección y todas las redirecciones, nunca a partir de los encabezados Host o X-Forwarded-* de la solicitud, así que la configuración trust proxy no le afecta. El protocolo http simple solo se acepta para localhost.

Las opciones se validan cuando se ejecuta createBff, de modo que un error de configuración detiene la aplicación al iniciarla.

Rutas

expressSession sirve tres rutas y lee la sesión en todas las demás solicitudes:

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 admite. 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 y descarta la anterior.

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

Proteger rutas

expressRequireAuth(bff) deja pasar una solicitud solo si hay una sesión:

• una solicitud de página (GET o HEAD) sin sesión 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 procede 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 frente a la falsificación de solicitudes entre sitios, además de SameSite=Lax.

Usar la sesión y llamar a su API

req.keenauth contiene:

• session: null, o el usuario que ha iniciado sesión. session.user tiene las reclamaciones tipadas del token de ID, como subject, email, name, orgId y orgRoles; todas las reclamaciones están en session.user.claims. El objeto de sesión nunca contiene un token.
• accessToken: un token de acceso válido para llamadas del lado del servidor, o null.

app.get("/api/orders", expressRequireAuth(bff), async (req, res) => {
  const upstream = await fetch("https://api.acme.example/v1/orders", {
    headers: { Authorization: `Bearer ${req.keenauth!.accessToken}` },
  });
  res.status(upstream.status).json(await upstream.json());
});

En TypeScript, declare la propiedad una sola vez:

import type { SessionContext } from "@keenauth/node/bff";

declare module "express-serve-static-core" {
  interface Request {
    keenauth?: SessionContext | null;
  }
}

Cuando el token de acceso caduca en menos de 60 segundos, el SDK lo renueva antes de que se ejecute su controlador. Cada renovació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.

No envíe el token de acceso al navegador.

Cambiar de organización

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

Cerrar sesión

Envíe un POST a /auth/logout desde un formulario. El SDK:

1. elimina la cookie de sesión (y la sesión almacenada, si usa un almacén);
2. revoca el token de actualización;
3. 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 mediante un POST desde sus propias páginas.

Almacenamiento de sesiones

De forma predeterminada, la sesión completa 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 conservar los tokens en el servidor, pase un almacén:

import { createBff, type SessionStore } from "@keenauth/node/bff";

const store: SessionStore = {
  get: async (id) => JSON.parse((await redis.get(`sess:${id}`)) ?? "null"),
  set: async (id, session, ttl) => void (await redis.set(`sess:${id}`, JSON.stringify(session), { EX: ttl })),
  delete: async (id) => void (await redis.del(`sess:${id}`)),
};
const bff = createBff({ /* … */ store });

La cookie contiene entonces solo un identificador de sesión aleatorio y cifrado. Cada inicio de sesión crea un identificador nuevo y elimina el registro anterior. El almacén contiene tokens, así que restrinja su acceso. MemorySessionStore solo es para desarrollo y pruebas.

Una sesión dura como máximo 7 días (sessionMaxAge); renovarla no la prolonga. Para cambiar el secreto, pase una lista: secret: [newSecret, oldSecret]. Elimine el antiguo después de sessionMaxAge.

Límites actuales

• Los tokens vinculados a DPoP y el cierre de sesión de canal trasero todavía no se gestionan.
• Las renovaciones solo se comparten dentro de un mismo proceso del servidor. Con varias instancias, el ajuste de la aplicación refresh_reuse_interval_s (por defecto 5 segundos) permite que una renovación paralela se realice correctamente; si lo establece en 0, la segunda renovación termina la sesión.