Integrar una aplicación con LSSM ID

Despliegue y aprobación

La implementación ampliada de AuthOS y el registro de aplicaciones externas están en proceso de calificación en producción. Esta guía documenta el contrato de integración; publicarla no significa que tu aplicación esté aprobada ni que todos los proveedores y funciones estén activos. Confirma la disponibilidad con support@lssm.co antes de integrar en producción.

El registro dinámico anónimo de clientes está desactivado. Un operador debe aprobar la configuración y política de acceso de tu aplicación. Registrar una identidad no concede pertenencia a un producto.

Preparar el registro de la aplicación

Facilita nombre, propietario, URL HTTPS exactas de retorno y tras cerrar sesión, permisos de identidad y audiencias de recursos necesarias. Utiliza una URL como https://YOUR_HOST/api/auth/callback/lssm, sin comodines.
Acuerda con el operador la admisión pública de identidades verificadas o una política de invitaciones y derechos. Mantén pertenencias, roles y autorizaciones de negocio en la aplicación consumidora.
Tras la aprobación, el propietario rota el secreto para obtener su valor mostrado una sola vez. Guarda el ID de aplicación, ID de cliente y secreto en el gestor de secretos del servidor. Nunca expongas el secreto en un navegador, paquete móvil ni configuración pública.
La superficie de gestión prevista es /auth/applications en id.lssm.co. Durante el despliegue, consulta el proceso disponible con soporte; no presupongas que una ruta sin calificar está activa.

Configuración del protocolo

Obtén los puntos de autorización, token y JWKS del documento de descubrimiento canónico. Fija su emisor exactamente a https://id.lssm.co/api/auth, también tras reintentos. Rechaza un emisor descubierto diferente.

Las audiencias de recursos se revisan por separado. Los metadatos de registro no amplían la política de audiencias válidas del despliegue. La audiencia del token de identidad es el ID de cliente, no la audiencia de recurso.

Emisor: https://id.lssm.co/api/auth
Descubrimiento: https://id.lssm.co/.well-known/openid-configuration
Autenticación del cliente: Cliente servidor confidencial; client_secret_basic
Concesión: authorization_code con PKCE S256; refresh_token solo si se aprueba
Permisos de identidad: openid; profile y email según necesidad; offline_access solo con aprobación
Permiso de aplicación: https://lssm.co/scopes/YOUR_APPROVED_APPLICATION_ID
Audiencia del token de identidad: Tu ID de cliente aprobado
Audiencia de recurso: La audiencia de recurso exacta aprobada por el operador
Sujeto: sub pairwise vinculado al emisor; no el correo

Utilizar la configuración servidor verificada

Usa Better Auth 1.7.14 y el módulo de referencia completo enlazado abajo. Utiliza el plugin oficial Generic OAuth y verifica el emisor canónico al arrancar y tras reintentos. Aporta un adaptador compatible de base persistente, un secreto de sesión dedicado de al menos 32 caracteres y las credenciales de servidor aprobadas. Crear la base y migrarla siguen siendo pasos explícitos del despliegue.

Conserva el módulo de referencia completo: sus comprobaciones de compatibilidad del cliente confidencial forman parte de la configuración. Exige un token de identidad firmado, vinculado al nonce exacto generado por el servidor, y el emisor de la respuesta de autorización. Rechaza el uso exclusivo de userinfo y el acceso mediante un token de identidad enviado por el navegador. Userinfo solo puede complementar al sujeto verificado; un ID de perfil no sustituye esa prueba.

La configuración solicita solo openid, profile, email y el permiso exacto de aplicación. Añade offline_access únicamente tras aprobación si necesitas tokens de renovación. Estos fragmentos no crean permisos de producto ni provisionan la base de otro producto.

APP_ORIGIN debe ser el origen HTTPS exacto, como https://YOUR_HOST, sin ruta ni barra final. Utiliza un secreto de sesión de servidor independiente; no reutilices el secreto OAuth para la sesión.

Configuración del servidor de la aplicación

import { betterAuth } from 'better-auth';
import { externalIdentityOptions } from './lssm-id-auth';
import { database } from './database'; // Your persistent supported adapter.

export const auth = betterAuth(externalIdentityOptions({
  origin: process.env.APP_ORIGIN!,
  database,
  sessionSecret: process.env.APP_SESSION_SECRET!,
  clientId: process.env.LSSM_CLIENT_ID!,
  clientSecret: process.env.LSSM_CLIENT_SECRET!,
  applicationId: process.env.LSSM_APPLICATION_ID!,
}));

Gestor Next.js App Router

// app/api/auth/[...all]/route.ts
import { toNextJsHandler } from 'better-auth/next-js';
import { auth } from '@/lib/auth';

export const { GET, POST } = toNextJsHandler(auth);

Gestor de servidor genérico

// Mount on your HTTPS server; preserve the reviewed canonical origin.
import { auth } from './auth';
import { handleAuthorizedApplicationRequest } from './application';

export async function fetch(request: Request): Promise<Response> {
  if (new URL(request.url).pathname.startsWith('/api/auth/')) {
    return auth.handler(request);
  }
  const session = await auth.api.getSession({
    headers: request.headers,
    query: { disableCookieCache: true },
  });
  if (!session) return new Response('Sign in required', { status: 401 });
  // This application handler must check its own live memberships and grants.
  return handleAuthorizedApplicationRequest(request, session);
}

Cliente navegador en el origen de tu aplicación

import { createAuthClient } from 'better-auth/client';

const authClient = createAuthClient();
await authClient.signIn.social({ provider: 'lssm', callbackURL: '/account' });
// Product-local sign-out; central LSSM ID logout is a separate choice.
await authClient.signOut();

Descargar el módulo TypeScript completo de configuración verificada

Validar el retorno y la autoridad local

Vincula cada autorización del navegador a un estado de un solo uso, nonce, desafío y verificador S256 y retorno exacto registrado. Valida el emisor de la respuesta de autorización.
Verifica la firma del token de identidad con descubrimiento/JWKS de confianza, emisor exacto, audiencia de cliente, nonce y caducidad. Un token de acceso no es un token de identidad. Rechaza pruebas ausentes o inválidas.
Utiliza emisor y sujeto pairwise como identidad, no la coincidencia de correo. No fusiones una identidad local existente solo porque coincida su dirección.
Crea una sesión local únicamente después de una admisión central correcta. Recalcula pertenencias y permisos vivos tras el retorno y al cambiar de cuenta. Un rol administrador central no concede acceso al producto.
Utiliza HTTPS y cookies seguras propias de la aplicación. Separa su sesión y credenciales de la cookie Passport central, claves API y permisos de agentes. No confíes en cabeceras de host reenviadas arbitrarias para definir emisor o retorno.

Consentimiento, rotación y cierre de sesión

Los cambios de metadatos requieren nueva revisión del operador. Suspensión, revocación y rotación detienen las credenciales y permisos centrales correspondientes; una sesión local establecida sigue su política de revocación. Define esa política de forma explícita.

El módulo de referencia desactiva el cierre automático de sesión del proveedor. Cerrar sesión en tu producto termina su sesión local; salir de LSSM ID es una decisión separada. Prueba la selección de cuenta, ambas salidas y la autorización local después de cambiar.

Iniciar sesión no autoriza correo, repositorios, informes ni otros datos conectados. Las conexiones necesitan consentimiento, permisos y recursos separados. Sesiones de navegador, claves API y permisos de agentes son credenciales distintas.

Calificar antes de utilizar en producción

Registra la versión aprobada por el operador, fuentes exactas e identificadores del despliegue alojado.
Ejecuta un recorrido real de autorización → consentimiento → retorno → sesión local en el host HTTPS real. Prueba también consentimiento denegado y estado, nonce, emisor, audiencia, firma y caducidad inválidos.
Cuando esté aprobado, prueba renovación, rotación y revocación. Prueba selección de cuenta, denegación de pertenencia local y salida sin depender de autoridad en caché.
Un ejemplo fuente, cliente registrado o URL inicial no califican producción. La aplicación de referencia alojada por separado y cada consumidor del ecosistema necesitan su propio recorrido real.

Contacta con support@lssm.co para coordinar la integración y con security@lssm.co ante un posible problema de seguridad. Las páginas de privacidad y eliminación explican las solicitudes sobre datos personales.

Fuente de referencia

Versión fijada de Better Auth: 1.7.14
Commit fuente revisado: cd244e959faddc42ed30d6a6c5089618e37c1ab0

examples/lssm-id-external-app/src/auth.ts