Skip to content

S
sigic_documentacion

Servicio de Autenticación y Autorización con Keycloak

Last edited by Helbert Marcel Picazo Cardona
Page history

Documentación Técnica

## 1. Objetivo

Diseñar e implementar un sistema de autenticación centralizado y seguro, alineado con estándares actuales, para controlar el acceso a los sistemas y recursos digitales de SIGIC, a través de Keycloak.

Este servicio debe:

  • Permitir la autenticación de usuarios humanos y sistemas automatizados.
  • Garantizar la confidencialidad, integridad y disponibilidad de las credenciales y tokens.
  • Ser extensible para soportar diferentes esquemas de identidad.

Funcionalidades de Keycloak:

  • Servidor OAuth 2.0 / OpenID Connect / SAML 2.0.
  • Administración de usuarios, roles, grupos, sesiones y MFA.
  • Panel de administración web y REST API para automatización.
  • Soporte de federación de identidades con LDAP, Active Directory y redes sociales.
  • Clúster horizontal para alta disponibilidad.
  • Exportación/importación de configuración en JSON.

2. Estándares y Protocolos Adoptados

2.1 OAuth 2.0 (RFC 6749)

OAuth 2.0 se utiliza como marco de autorización para delegar acceso de forma segura entre usuarios, aplicaciones y servicios. Se admiten los siguientes "grant types":

  • authorization_code (con PKCE): recomendado para aplicaciones públicas como SPA o móviles.
  • client_credentials: para comunicación entre servicios backend.
  • refresh_token: para renovación de tokens sin reautenticación.
  • implicit (limitado y solo si es estrictamente necesario, ya que se considera obsoleto).
  • resource_owner_password_credentials: uso restringido a sistemas legacy bajo revisión de seguridad.

2.2 OpenID Connect (OIDC)

Protocolo de autenticación federada basado en OAuth 2.0, que añade:

  • Provisión de un ID Token con información del usuario autenticado.
  • Punto de descubrimiento (.well-known/openid-configuration).
  • Endpoints estandarizados: token, userinfo, introspection, logout.

2.3 JSON Web Tokens (JWT - RFC 7519)

Tokens firmados digitalmente que contienen las credenciales de acceso:

  • Claims obligatorios: iss, sub, aud, exp, iat.
  • Firmas: RS256 por defecto, con clave pública disponible en endpoint JWKS.
  • Los JWT permiten validación local sin necesidad de llamadas adicionales.

2.4 HTTPS Obligatorio

Todo el tráfico entre los clientes y el servidor de autenticación debe realizarse exclusivamente mediante HTTPS (TLS 1.2 o superior). Cualquier intento de conexión insegura debe ser rechazado.

3. Gestión de Identidades y Acceso

3.1 Usuarios

  • Soporte para cuentas internas propias y externas federadas (por ejemplo desde ORCID, LlaveMX, kardex.digital, etc).
  • Atributos mínimos requeridos: email, nombre, apellido, username, roles.
  • Autenticación multifactor opcional (OTP vía app tercera, WebAuthn).

3.2 Roles y Permisos

  • Definición de roles por aplicación.
  • Asociación de roles a usuarios o grupos.
  • Políticas de autorización basadas en:
    • Roles (RBAC)
    • Atributos (ABAC)
    • Grupos

3.3 Grupos

  • Organización jerárquica de usuarios por función, departamento o contexto.
  • Permite herencia de roles o restricciones.

4. Tokens y Sesiones

4.1 Tipos de Tokens

Tipo Uso Tiempo de vida (recomendado)
Access Token Acceso a recursos protegidos 5-15 minutos
Refresh Token Renovación del Access Token 30 minutos - 1 hora
ID Token Información de la sesión y del usuario Igual que Access Token

4.2 Seguridad de los Tokens

  • Firmados con claves privadas del servidor de autenticación (RS256).
  • Validación mediante JWKS (/.well-known/jwks.json).
  • Uso de aud y iss para garantizar el destino y el emisor legítimo.
  • Tokens no deben almacenarse en almacenamiento no seguro (ej. localStorage sin protección).

4.3 Revocación e Introspección

  • Endpoint de introspección disponible para validar tokens en tiempo real.
  • Endpoint de revocación para forzar el cierre de sesiones o invalidación de refresh tokens.

5. Seguridad y Buenas Prácticas

  • Política de contraseñas configurables: longitud mínima, caracteres especiales, rotación.
  • Protección contra ataques de fuerza bruta mediante bloqueo temporal.
  • HSTS activado en todos los endpoints.
  • Verificación de origen (CORS), cabeceras de seguridad (X-Frame-Options, Content-Security-Policy, etc.).
  • MFA obligatorio para cuentas privilegiadas.

6. Auditoría y Monitoreo

  • Registro de eventos:
    • Inicio/cierre de sesión.
    • Cambios de credenciales.
    • Fallos de autenticación.
    • Creación y eliminación de usuarios.
  • Integración con sistemas SIEM y herramientas de monitoreo (Prometheus, Grafana, ELK).
  • Logs disponibles en formatos estructurados (JSON, syslog).

7. Integración

7.1 Aplicaciones Web

  • Uso de OpenID Connect authorization_code flow con PKCE.
  • Redirección a endpoint /authorize del servidor de autenticación.
  • Recepción y validación del token de forma segura.

7.2 Aplicaciones Móviles

  • Igual que aplicaciones web (con PKCE).
  • Se recomienda usar bibliotecas oficiales de OIDC como AppAuth.

7.3 APIs

  • Protección mediante bearer tokens (JWT).
  • Middleware/verificadores que validen firma, audiencia y expiración del token.
  • Acceso a roles del usuario vía claims del token.

8. Cumplimiento de Estándares

El sistema de autenticación cumple con los siguientes estándares y recomendaciones:

  • [RFC 6749] OAuth 2.0 Authorization Framework
  • [RFC 7636] Proof Key for Code Exchange (PKCE)
  • [RFC 7519] JSON Web Token (JWT)
  • [RFC 7591/7592] Dynamic Client Registration (opcional)
  • [NIST SP 800-63B] Digital Identity Guidelines (nivel 2-3)
  • OWASP Authentication Cheat Sheet
  • CIS Controls - Control 6: Access Control Management

9. Implementación con Keycloak

Todo lo anterior se implementa utilizando Keycloak, una plataforma de gestión de identidades y accesos (IAM) de código abierto que cumple con los estándares mencionados.

Funcionalidades de Keycloak:

  • Servidor OAuth 2.0 / OpenID Connect / SAML 2.0.
  • Administración de usuarios, roles, grupos, sesiones y MFA.
  • Panel de administración web y REST API para automatización.
  • Soporte de federación de identidades con LDAP, Active Directory y redes sociales.
  • Clúster horizontal para alta disponibilidad.
  • Exportación/importación de configuración en JSON.
  • Extensible mediante SPIs y políticas personalizadas.

10. Conclusiones

Este documento describe una solución de autenticación moderna, basada en estándares, segura y flexible. La implementación mediante Keycloak garantiza el cumplimiento de todos los requisitos funcionales, técnicos y de seguridad, y permite escalar el sistema en el tiempo conforme aumentan las necesidades de acceso y federación de identidades de la organización.