lib-keycloak-se

@salud-electronica/keycloak-se

Librería de integración con Keycloak para el ecosistema de Salud Electrónica.

Instalación

npm install @salud-electronica/keycloak-se

Configuración

import { KeycloakSE, KeycloakSEConfig } from '@salud-electronica/keycloak-se';

const config: KeycloakSEConfig = {
  authServerUrl: 'https://ssokeycloack.saludelectronica.com.co',
  realm: 'salud-electronica-dev',
  adminUsername: 'sre-admin',
  adminClientId: 'admin-cli',
  adminPassword: 'contraseña',
  clientConfig: {
    clientId: 'tu-aplicacion',
    appRole: 'rol-aplicacion',
    publicClient: false
  }
};

const keycloak = new KeycloakSE(config);

Funcionalidades Principales

1. Autenticación

// Login
const response = await keycloak.login(username, password, otpCode);

// Logout
const result = await keycloak.logout(tokenSession);

// Verificar sesión
const isValid = await keycloak.checkSessionStatus(tokenSession);

2. Gestión de Usuarios

// Crear/Asignar usuario
const result = await keycloak.createOrAssignUserWithAppRole({
  username,
  email,
  password,
  firstName,
  lastName
});

// Editar usuario
const result = await keycloak.editUser(userId, {
  firstName,
  lastName,
  email,
  enabled
});

// Eliminar usuario
const result = await keycloak.deleteUser(userId);

// Buscar por email
const result = await keycloak.getUserIdByEmail(email);

3. Gestión de Roles

// Asignar rol
const result = await keycloak.assignRoleToUser(userId, roleName);

// Obtener roles
const result = await keycloak.getUserRoles(userId);

// Eliminar rol
const result = await keycloak.removeRoleFromUser(userId, roleName);

4. Autenticación de Dos Factores

// Verificar estado 2FA
const status = await keycloak.getOtpStatus(tokenSession);

// Activar/Desactivar 2FA
const result = await keycloak.toggleTwoFactor({ tokenSession, enable });

Manejo de Errores

La librería maneja los errores de forma consistente. Todas las operaciones retornan objetos con la siguiente estructura:

interface Response {
  message: string;
  error?: boolean;
  // Campos adicionales específicos de cada operación
}

Consideraciones de Seguridad

2. Validación de Entrada:

   • Validar todos los datos de entrada
   • Sanitizar emails y nombres de usuario
   • Implementar límites de longitud

3. Logging:

   • Registrar intentos de login fallidos
   • Mantener registro de cambios de contraseña
   • Monitorear actividad sospechosa

Requisitos

• Node.js >= 14
• TypeScript >= 4.5
• Acceso a un servidor Keycloak configurado

Documentación Adicional

Para más detalles sobre la configuración de Keycloak y mejores prácticas, consulta el Manual de Implementación.

Licencia

Este proyecto es propiedad de Salud Electrónica y su uso está restringido a los términos de la licencia.