OpenID Connect / Cliente OAuth
Una implementación de cliente conectable para el protocolo OpenID Connect, que permite a los usuarios autenticarse con proveedores de identidad externos.
openid_connect
Install
composer require 'drupal/openid_connect:8.x-1.4'
Overview
El módulo OpenID Connect proporciona una implementación completa de cliente conectable para el protocolo OpenID Connect, que es una capa de identidad simple sobre OAuth 2.0. Permite que los sitios Drupal autentiquen usuarios utilizando proveedores OpenID Connect externos como Google, Facebook, GitHub, LinkedIn y Okta, así como cualquier proveedor personalizado a través de un cliente genérico.
Cuando los usuarios inician sesión con un proveedor OpenID Connect por primera vez, se crea automáticamente una nueva cuenta de usuario en Drupal. El módulo admite la sincronización de información del perfil de usuario desde los proveedores de identidad hacia los campos de usuario de Drupal a través del mapeo configurable de claims. La funcionalidad de mapeo de roles permite la asignación automática de roles de Drupal basándose en grupos o claims proporcionados por el proveedor de identidad.
El módulo proporciona opciones de integración flexibles, incluyendo un bloque de inicio de sesión, visualización configurable de botones de inicio de sesión en el formulario estándar de inicio de sesión de usuario, y soporte para redirección automática de inicio de sesión cuando solo hay un proveedor configurado. También admite la funcionalidad de cierre de sesión único (SLO) donde cerrar sesión en Drupal también puede terminar la sesión en el proveedor de identidad.
Features
- Múltiples plugins de cliente OpenID Connect integrados para Google, Facebook, GitHub, LinkedIn, Okta, y un cliente genérico para proveedores personalizados
- Creación automática de cuenta de usuario en el primer inicio de sesión con un proveedor externo
- Mapeo de claims para sincronizar información del perfil de usuario desde proveedores de identidad hacia campos de usuario de Drupal
- Mapeo experimental de roles para asignar automáticamente roles de Drupal basándose en grupos del proveedor de identidad
- Soporte de OpenID Connect Discovery para configuración automática de endpoints mediante URIs conocidas
- Soporte de cierre de sesión único (SLO) para terminar sesiones tanto en Drupal como en el proveedor de identidad
- Opciones configurables de visualización de botones de inicio de sesión: oculto, arriba, abajo, reemplazar, o forzar reemplazo del formulario de inicio de sesión estándar
- Opción de auto-inicio del proceso de inicio de sesión para redirección automática al proveedor de identidad
- Gestión de cuentas conectadas permitiendo a los usuarios vincular/desvincular cuentas de proveedores externos
- Soporte de iniciación SSO basada en ISS para flujos de inicio de sesión iniciados por el proveedor de identidad
- Gestión de tokens de sesión para tokens de ID, tokens de acceso, tokens de actualización y seguimiento de expiración
- Arquitectura de plugins extensible que permite a los desarrolladores crear plugins de cliente personalizados
- Validación de tokens de estado para protección CSRF durante flujos OAuth
Use Cases
SSO Empresarial con Google Workspace
Las organizaciones que usan Google Workspace pueden permitir que los usuarios inicien sesión en su intranet Drupal usando sus cuentas corporativas de Google. Habilitar el cliente de Google, configurarlo con credenciales OAuth de Google Cloud Console, y los usuarios pueden autenticarse con sus direcciones de correo electrónico de trabajo.
Inicio de Sesión Social para Sitios de Comunidad
Los sitios de comunidad y membresía pueden reducir la barrera de registro permitiendo que los usuarios se registren usando sus cuentas existentes de Facebook, GitHub o LinkedIn. Esto elimina la necesidad de que los usuarios creen y recuerden otra contraseña más.
Integración con Proveedores de Identidad Empresariales
Usando el cliente Generic u Okta, las empresas pueden integrar Drupal con sus sistemas de gestión de identidad existentes como Azure AD, Keycloak, Auth0, o cualquier proveedor compatible con OpenID Connect. La función de auto-descubrimiento simplifica la configuración al obtener automáticamente las URLs de los endpoints.
Gestión Centralizada de Usuarios
Las organizaciones pueden gestionar cuentas de usuario centralmente en su proveedor de identidad y tener los cambios sincronizados automáticamente a Drupal. El mapeo de claims asegura que los campos del perfil de usuario se mantengan actualizados, mientras que el mapeo de roles puede asignar automáticamente permisos basándose en membresía de grupos.
Restringir el Inicio de Sesión Solo a SSO
Para entornos de alta seguridad, los administradores pueden configurar el módulo para reemplazar el formulario de inicio de sesión estándar por completo, forzando a todos los usuarios a autenticarse a través del proveedor de identidad corporativo. El parámetro URL 'showcore' proporciona una vía de escape para administradores si es necesario.
Autenticación de Desarrolladores para Equipos Basados en GitHub
Los equipos de desarrollo pueden usar la autenticación de GitHub para permitir que los miembros del equipo inicien sesión usando sus cuentas de GitHub. Esto es particularmente útil para proyectos de código abierto donde los contribuidores ya tienen cuentas de GitHub.
Tips
- Usar el cliente Generic con auto-descubrimiento para cualquier proveedor compatible con OpenID Connect para minimizar la configuración
- Probar las configuraciones OAuth en un entorno de desarrollo antes de desplegar a producción
- Cuando se usa la opción 'Reemplazar' formulario de inicio de sesión, los usuarios pueden acceder al formulario de inicio de sesión estándar agregando ?showcore a la URL
- El módulo almacena tokens en la sesión del usuario, que pueden recuperarse usando el servicio openid_connect.session para llamadas API al proveedor de identidad
- Se pueden crear plugins de cliente personalizados extendiendo OpenIDConnectClientBase y usando la anotación @OpenIDConnectClient
- Usar hook_openid_connect_pre_authorize para implementar lógica de autorización personalizada, como restringir el inicio de sesión a usuarios con claims específicos
- El mapeo de roles es experimental - probar exhaustivamente antes de depender de él en producción
- Por seguridad, solo habilitar 'Conectar automáticamente usuarios existentes' con proveedores de identidad de confianza donde las direcciones de correo electrónico estén verificadas
Technical Details
Admin Pages 4
/admin/config/people/openid-connect
Lista todas las entidades de cliente OpenID Connect configuradas. Los administradores pueden agregar nuevos clientes, editar configuraciones existentes, habilitar/deshabilitar clientes y eliminar clientes desde esta página.
/admin/config/people/openid-connect/add/{plugin_id}
Formulario para agregar un nuevo cliente OpenID Connect. Los campos disponibles dependen del tipo de plugin seleccionado.
/admin/config/people/openid-connect/settings
Configuración global para el comportamiento de inicio de sesión OpenID Connect, mapeo de claims de usuario y mapeo de roles.
/user/{user}/connected-accounts
Permite a los usuarios ver y gestionar sus cuentas de proveedores de identidad externos conectadas. Los usuarios pueden conectar nuevos proveedores o desconectar los existentes.
Permissions 4
Hooks 9
hook_openid_connect_claims_alter
Permite a los módulos modificar la lista de claims disponibles de OpenID Connect.
hook_openid_connect_client_info_alter
Permite a los módulos alterar las definiciones de plugins de cliente, incluyendo agregar nuevos plugins o cambiar clases de plugins.
hook_openid_connect_user_properties_ignore_alter
Permite a los módulos modificar qué propiedades de usuario están excluidas del mapeo de claims.
hook_openid_connect_userinfo_alter
Permite a los módulos alterar la información de usuario obtenida del proveedor de identidad antes de la autorización.
hook_openid_connect_pre_authorize
Se ejecuta antes de la autorización del usuario. Puede denegar acceso, anular la cuenta de usuario o realizar verificaciones adicionales.
hook_openid_connect_post_authorize
Se ejecuta después de la autorización exitosa del usuario. Útil para almacenar tokens o procesamiento adicional.
hook_openid_connect_userinfo_claim_alter
Permite a los módulos alterar valores individuales de claims antes de que se mapeen a propiedades de usuario.
hook_openid_connect_userinfo_save
Se ejecuta después del mapeo de claims pero antes de guardar la cuenta de usuario. Permite mapear claims complejos adicionales.
hook_openid_connect_redirect_logout_alter
Permite a los módulos alterar la respuesta de redirección al cerrar sesión.
Troubleshooting 7
Verificar que al menos un cliente OpenID Connect esté habilitado en /admin/config/people/openid-connect. Verificar que la configuración 'Visualización de botones OpenID en el formulario de inicio de sesión de usuario' no esté establecida en 'Oculto' en la pestaña Configuración. Alternativamente, colocar el bloque 'Inicio de sesión OpenID Connect' en una región visible.
La URL de redirección configurada en tu proveedor de identidad debe coincidir exactamente con la URL mostrada al editar el cliente en Drupal. Asegurar que la URL incluya el protocolo correcto (https), dominio y ruta. Verificar las barras diagonales finales.
Por defecto, los usuarios conectados a proveedores externos no pueden cambiar su contraseña de Drupal. Otorgar el permiso 'Establecer una contraseña para autenticación local' a los roles apropiados si deseas que los usuarios puedan establecer una contraseña local.
El auto-login solo funciona cuando exactamente un cliente OpenID Connect está habilitado. Si hay múltiples clientes habilitados, los usuarios deben seleccionar manualmente su proveedor. También verificar que la configuración 'Auto-iniciar proceso de inicio de sesión' esté habilitada.
Verificar la configuración 'Guardar claims de usuario en cada inicio de sesión'. Si está deshabilitada, los claims solo se guardan cuando la cuenta se crea por primera vez. También verificar la configuración de mapeo de claims en la página de Configuración.
Cuando se usa auto-descubrimiento, asegurar que la URL del Issuer sea correcta y que el proveedor soporte la especificación OpenID Connect Discovery. Intentar configurar manualmente los endpoints si el auto-descubrimiento falla.
Verificar que la configuración 'Cerrar sesión del proveedor de identidad' esté habilitada. No todos los proveedores soportan endpoints de finalización de sesión - verificar si tu proveedor soporta esta función y si el endpoint está configurado en los ajustes del cliente.
Security Notes 6
- La configuración 'Conectar automáticamente usuarios existentes' tiene implicaciones de seguridad. Solo habilitarla con proveedores de identidad que verifiquen las direcciones de correo electrónico, ya que vincula cuentas basándose en coincidencia de correo electrónico.
- Almacenar los Client Secrets de forma segura. Nunca comprometerlos en control de versiones. Considerar usar variables de entorno o un sistema de gestión de secretos.
- Todos los permisos en este módulo están marcados como 'acceso restringido' debido a su sensibilidad. Otorgarlos cuidadosamente.
- El módulo implementa protección CSRF usando tokens de estado en el flujo OAuth.
- Cuando se configuran dominios permitidos por ISS, solo listar dominios de confianza para iniciar solicitudes SSO.
- Revisar y probar las implementaciones de hooks que modifican el comportamiento de autorización (pre_authorize, post_authorize) para asegurar que no introduzcan vulnerabilidades de seguridad.