@hemia/auth-sso

@hemia/auth-sso

Cliente de autenticación Single Sign-On (SSO) para entornos web multiaplicación. Este paquete permite validar sesiones, iniciar login usando PKCE, manejar el callback de autenticación, refrescar sesiones y cerrar sesión de forma centralizada.

Instalación

npm install @hemia/auth-sso

Uso básico

import { SSOClient } from '@hemia/auth-sso';

const sso = new SSOClient({
  clientId: 'sistema1',
  redirectUri: 'https://sistema1.com/callback',
  ssoAuthUrl: 'https://sso.miempresa.com/authorize',
  tokenEndpoint: 'https://sistema1.com/api/sso/token',
  sessionEndpoint: 'https://sistema1.com/api/sso/check-session',
  refreshEndpoint: 'https://sistema1.com/api/sso/refresh',
  logoutEndpoint: 'https://sistema1.com/api/sso/logout',
  logoutRedirectUrl: 'https://sistema1.com/',
  scopes: ['openid', 'profile'],
  apiKey: 'mi-api-key'
});

Métodos disponibles

validateSession(): Promise<SSOSession>

Valida si la sesión actual sigue activa, usando una caché de TTL de 1 minuto para evitar llamadas excesivas.

const session = await sso.validateSession();
if (!session.isAuthenticated) {
  sso.startLogin();
}

startLogin(auto?: boolean, skip?: boolean): Promise<void>

Redirige al usuario al flujo de autenticación del SSO usando PKCE.

sso.startLogin(); // auto y skip son opcionales

handleCallback(): Promise<{ success: boolean; message?: string, brokenSession?: boolean }>

Procesa el callback del servidor SSO después de la redirección e intercambia el código de autorización por un token de sesión.

const result = await sso.handleCallback();
if (!result.success) {
  console.error(result.message);
}

refreshToken(): Promise<boolean>

Renueva la sesión actual usando el token de sesión. Ideal para mantener sesiones activas sin necesidad de login constante.

const ok = await sso.refreshToken();

logout(): Promise<void>

Cierra la sesión actual tanto en el cliente como en el backend del sistema, y redirige al usuario.

await sso.logout();

Requisitos

• Backend del sistema debe implementar los endpoints para: token, sesión, refresh y logout.
• El flujo de autenticación usa PKCE (code_challenge y code_verifier).
• El cliente guarda datos temporales en localStorage.

Estructura esperada del objeto SSOConfig

interface SSOConfig {
  clientId: string;
  redirectUri: string;
  ssoAuthUrl: string;
  tokenEndpoint: string;
  sessionEndpoint: string;
  refreshEndpoint?: string;
  logoutEndpoint?: string;
  logoutRedirectUrl?: string;
  scopes: string[];
  apiKey?: string;
}

Licencia

MIT