Autenticación SAML
Habilita la autenticación de inicio de sesión único (SSO) SAML 2.0, permitiendo a los usuarios iniciar sesión en Drupal a través de proveedores de identidad SAML externos.
samlauth
Install
composer require 'drupal/samlauth:8.x-3.12'
Overview
El módulo SAML Authentication integra Drupal con proveedores de identidad (IdPs) SAML 2.0, habilitando la autenticación de inicio de sesión único (SSO) para tu sitio Drupal. Los usuarios pueden autenticarse contra sistemas externos de gestión de identidades como Azure AD, Okta, OneLogin, Google Workspace, SimpleSAMLphp o cualquier otro IdP compatible con SAML 2.0.
El módulo implementa el lado del proveedor de servicios (SP) del protocolo SAML utilizando OneLogin PHP SAML Toolkit. Gestiona el flujo completo de autenticación incluyendo redirecciones de inicio de sesión al IdP, procesamiento de aserciones SAML, creación/vinculación de cuentas de usuario, sincronización de atributos y funcionalidad de cierre de sesión.
Las capacidades clave incluyen estrategias configurables de vinculación de usuarios (por correo electrónico, nombre o atributos personalizados), creación automática de cuentas de usuario a partir de atributos SAML, control de acceso basado en roles para el inicio de sesión local de Drupal y opciones de seguridad integrales para firmar y cifrar mensajes SAML. El módulo admite la gestión de certificados X.509 a través de archivos, valores de configuración o el módulo Key para mayor seguridad.
Features
- Autenticación de inicio de sesión único (SSO) SAML 2.0 con proveedores de identidad externos
- Creación automática de cuentas de usuario a partir de atributos SAML (nombre, correo electrónico, campos personalizados)
- Vinculación flexible de cuentas de usuario por ID único, dirección de correo electrónico o nombre de usuario
- Restricciones basadas en roles para el inicio de sesión local de Drupal (bloquear a usuarios SAML de la autenticación local)
- Gestión de certificados X.509 y claves privadas mediante archivos, configuración o el módulo Key
- Generación de XML de metadatos SP para configuración del IdP
- Formatos de NameID configurables y requisitos de políticas
- Opciones de firma y cifrado de solicitudes/respuestas
- Soporte para múltiples certificados de IdP (para rotación de claves)
- Soporte de nuevo certificado para planificación de rotación de claves SP
- Soporte de servicio de cierre de sesión único (SLS)
- Eventos personalizados para hooks de vinculación y sincronización de usuarios
- Protección de control de saturación contra ataques de fuerza bruta
- Registro de depuración para mensajes SAML (entrantes/salientes)
- Integración opcional con Views para gestionar entradas de authmap
- Integración con el módulo External Auth para vinculación de cuentas
Use Cases
Integración de inicio de sesión único empresarial
Conecte su sitio Drupal a proveedores de identidad corporativos como Azure Active Directory, Okta o OneLogin. Los usuarios se autentican una vez con credenciales corporativas y obtienen acceso a Drupal sin contraseñas separadas. Configure la creación automática de usuarios y la asignación de roles basada en atributos SAML.
Autenticación para instituciones educativas
Integre con federaciones Shibboleth/InCommon para inicio de sesión único universitario. Mapee atributos eduPerson a campos de usuario de Drupal. Soporte múltiples proveedores de identidad para portales de colaboración en investigación.
Control de acceso a portales de clientes
Proporcione a socios externos o clientes acceso seguro a través del proveedor de identidad de su organización. Use la vinculación de usuarios para conectar inicios de sesión SAML a cuentas Drupal creadas previamente. Restrinja qué roles pueden usar el inicio de sesión local por seguridad.
Cumplimiento gubernamental/sanitario
Cumpla con los requisitos de seguridad utilizando proveedores de identidad aprobados por la organización. Habilite el cifrado para aserciones SAML y NameID. Asegure solicitudes/respuestas firmadas para pistas de auditoría. Configure validación estricta para entornos de producción.
Entorno de pruebas con múltiples IdP
Pruebe la integración SAML usando SimpleSAMLphp IdP basado en Docker localmente mientras producción usa el IdP corporativo. Use /saml/reauth para forzar la reautenticación durante las pruebas. Habilite el registro de depuración para inspeccionar mensajes SAML.
Tips
- Siempre habilite 'Strict validation' y las opciones de firma en entornos de producción por seguridad
- Use el módulo Key con proveedores de claves externos para almacenamiento seguro de certificados/claves en producción
- Establezca la validez de Metadata en 2 días (172800 segundos) y habilite el caché HTTP después de la configuración inicial
- Intercambie metadata con administradores del IdP vía la URL /saml/metadata en lugar de configuración manual
- Pruebe con /saml/reauth para forzar la reautenticación sin limpiar sesiones del navegador
- Habilite el registro de depuración temporalmente durante la configuración, luego desactívelo para producción
- Prepoblación de entradas authmap para usuarios conocidos en lugar de habilitar la vinculación automática para mejor seguridad
- Use el submódulo samlauth_user_roles para asignar roles automáticamente basado en membresía de grupos del IdP
- Configure 'Change password URL' para dirigir a los usuarios a la página de gestión de contraseñas de su IdP
- Respalde la configuración antes de la rotación de certificados; use el campo 'New certificate' para preparar al IdP para cambios de clave
Technical Details
Admin Pages 3
/admin/config/people/saml
Configura los ajustes de autenticación SAML relacionados con el usuario, incluyendo opciones de interfaz de usuario, fuente de ID único, comportamiento de vinculación de usuarios, creación de cuentas y redirección de inicio/cierre de sesión.
/admin/config/people/saml/saml
Configura los ajustes del protocolo SAML incluyendo la configuración del Service Provider, ajustes del Identity Provider, opciones de construcción/validación de mensajes y depuración.
/admin/config/people/saml/authmap/{uid}/delete
Formulario de confirmación para eliminar el vínculo entre un ID de inicio de sesión SAML y una cuenta de usuario de Drupal.
Permissions 2
Hooks 4
hook_form_user_form_alter
Modifica el formulario de edición de usuario para ocultar el campo de contraseña y bloquear el correo electrónico para usuarios exclusivos de SAML
hook_form_user_login_form_alter
Añade un enlace de inicio de sesión SAML al formulario de inicio de sesión y valida los usuarios exclusivos de SAML
hook_form_user_pass_alter
Valida el formulario de restablecimiento de contraseña para evitar que los usuarios exclusivos de SAML restablezcan su contraseña
hook_user_presave
Sincroniza los atributos SAML antes de guardar una nueva cuenta de usuario
Troubleshooting 7
Esto significa que la comunicación SAML funciona pero el atributo de ID único configurado no se encontró. Habilite 'Log incoming SAML messages' en las opciones de depuración, intente iniciar sesión, luego revise Recent log messages para ver el XML de respuesta SAML. Busque los nombres de atributos y actualice la configuración de 'Unique ID attribute' en consecuencia.
Esto típicamente ocurre detrás de un proxy inverso. Configure trusted_host_patterns y las configuraciones de reverse_proxy en settings.php como se documenta en drupal.org/docs/getting-started/installing-drupal/using-a-load-balancer-or-reverse-proxy
Habilite 'Retrieve logout signature parameters from $_SERVER[REQUEST]' en la configuración de SAML Message Validation. Esta opción corrige problemas de validación de firma con proveedores de identidad de Microsoft.
Instale el módulo flood_control para una interfaz administrativa que permita limpiar entradas de flood. Alternativamente, limpie las entradas directamente de la tabla de base de datos 'flood'. La protección contra flood se activa después de muchos intentos fallidos de inicio de sesión desde la misma IP.
Una vez que un usuario inicia sesión vía SAML, se le restringe el inicio de sesión local en Drupal a menos que tenga un rol listado en 'Roles allowed to use Drupal login'. Agregue los roles apropiados o use drush config:set samlauth.authentication drupal_login_roles '["authenticated"]' para permitir a todos los usuarios.
Esto ocurre cuando el Unique ID cambia o no es verdaderamente único. Asegúrese de que la fuente del Unique ID nunca cambie después de que los usuarios comiencen a iniciar sesión. Si existen duplicados, elimínelos manualmente y remueva las entradas incorrectas del authmap vía la vista /admin/people/authmap/samlauth.
Su IdP usa autenticación sin contraseña (como passkeys). Desactive la casilla 'Specify authentication context (as password)' en la configuración de SAML Message Construction.
Security Notes 9
- La vinculación de usuarios basada en atributos de email/nombre representa riesgos de seguridad si los usuarios pueden modificar estos valores en el IdP - los atacantes podrían tomar control de cuentas existentes
- Siempre use HTTPS para su sitio Drupal al implementar autenticación SAML
- Almacene las claves privadas fuera del directorio raíz de documentos web cuando use almacenamiento basado en archivos
- El permiso 'configure saml' solo debe otorgarse a administradores de alta confianza
- Habilite la firma de solicitudes/respuestas para prevenir la manipulación de mensajes SAML
- Considere habilitar el cifrado de aserciones para entornos sensibles
- Revise map_users_roles para restringir qué cuentas existentes pueden vincularse automáticamente
- El control de flood protege contra ataques de fuerza bruta pero usuarios legítimos pueden ser bloqueados después de problemas con el IdP
- Las restricciones de inicio de sesión local previenen que usuarios autenticados por SAML eludan las políticas de seguridad del IdP