OAuth2 Client
Proporciona funcionalidad de cliente OAuth2 que permite a Drupal actuar como cliente OAuth2 para autenticarse con servidores OAuth2 externos.
oauth2_client
Instalar
composer require 'drupal/oauth2_client:^4.1'
composer require 'drupal/oauth2_client:8.x-3.2'
Overview
El módulo OAuth2 Client permite que los sitios Drupal se integren con servicios externos utilizando el protocolo OAuth2. Proporciona una arquitectura basada en plugins para crear clientes OAuth2, manejando toda la funcionalidad de backend para la obtención, actualización y eliminación de tokens.
El módulo aprovecha la ampliamente utilizada biblioteca PHP League OAuth2 Client de The League of Extraordinary Packages, asegurando una implementación robusta y conforme a los estándares OAuth2. Los desarrolladores pueden crear plugins de cliente OAuth2 personalizados extendiendo la clase base y configurando los endpoints, tipos de concesión y alcances necesarios.
Las entidades de configuración se crean automáticamente para cada plugin, proporcionando una interfaz administrativa para gestionar credenciales. El módulo admite almacenamiento seguro de credenciales ya sea localmente usando la State API de Drupal o a través del módulo Key para mayor seguridad en entornos de producción.
Features
- Arquitectura basada en plugins para crear clientes OAuth2 con código mínimo
- Soporte para múltiples tipos de concesión OAuth2: Authorization Code, Client Credentials y Resource Owner Password
- Actualización automática de tokens cuando expiran y hay tokens de actualización disponibles
- Dos estrategias de almacenamiento de tokens: StateTokenStorage para tokens compartidos y TempStoreTokenStorage para tokens por usuario
- Gestión segura de credenciales con almacenamiento local o integración con el módulo Key
- Creación automática de entidades de configuración para cada plugin de cliente OAuth2
- Manejo personalizado de URI de redirección después de capturar el código de autorización
- Control de acceso personalizado para rutas de captura de código de autorización
- Soporte para proveedores OAuth2 personalizados a través del ecosistema de proveedores de la biblioteca League OAuth2 Client
- Alcances configurables, separadores de alcance y opciones de solicitud adicionales por cliente
- Protección CSRF usando validación del parámetro state durante el flujo de código de autorización
Use Cases
Integración con una API de terceros
Cuando su sitio Drupal necesita acceder a datos de un servicio externo que usa OAuth2 para autenticación (como las APIs de Google, Microsoft Graph o servicios empresariales personalizados), cree un plugin de cliente OAuth2. Use el tipo de concesión client_credentials para comunicación servidor a servidor donde no se necesita contexto de usuario.
Acceso a servicio externo autorizado por usuario
Cuando su sitio necesita acceder a recursos externos en nombre de usuarios individuales (como acceder a los archivos de Dropbox de un usuario o publicar en sus redes sociales), use el tipo de concesión authorization_code con TempStoreTokenStorage. Cada usuario autoriza el acceso y recibe su propio token almacenado en su temp store privado.
Integración de inicio de sesión único
Aunque no es una solución SSO completa, el módulo puede combinarse con código de autenticación personalizado para habilitar flujos de inicio de sesión basados en OAuth2. Use la concesión authorization_code para autenticar usuarios contra un proveedor OAuth2 externo y crear o vincular cuentas de Drupal.
Autenticación de microservicios
En una arquitectura de microservicios donde Drupal necesita comunicarse con otros servicios protegidos por OAuth2, use el tipo de concesión client_credentials con StateTokenStorage para mantener un token compartido para todas las solicitudes del lado del servidor.
Integración con sistema heredado usando concesión de contraseña
Para aplicaciones de primera parte de confianza o herramientas internas donde la recopilación directa de nombre de usuario/contraseña es aceptable, use el tipo de concesión resource_owner. Las credenciales se usan solo para obtener el token y no se persisten.
Tips
- Siempre use Composer para instalar este módulo para asegurar que la biblioteca League OAuth2 Client esté correctamente instalada
- Para entornos de producción, use el módulo Key para almacenar credenciales fuera de la base de datos, especialmente cuando use almacenamiento de archivos en una ubicación fuera de la raíz web
- Use el trait StateTokenStorage cuando el recurso externo sea compartido por todos los usuarios del sitio; use TempStoreTokenStorage cuando cada usuario necesite autorización individual
- El URI de redirección para las concesiones authorization_code se genera automáticamente como /oauth2-client/{plugin_id}/code - registre esta URL con su proveedor OAuth2
- Implemente Oauth2ClientPluginAccessInterface para personalizar quién puede completar el flujo de código de autorización
- Implemente Oauth2ClientPluginRedirectInterface para redirigir usuarios a una página personalizada después de una autorización exitosa
- Puede usar paquetes de proveedores OAuth2 de terceros dedicados del ecosistema League sobrescribiendo el método getProvider()
- El atributo de plugin request_options le permite agregar parámetros personalizados a las solicitudes de token para implementaciones OAuth2 no estándar
Technical Details
Admin Pages 3
/admin/config/system/oauth2-client
Lista todas las entidades de configuración de clientes OAuth2. Cada plugin de cliente crea automáticamente una entidad de configuración correspondiente que puede editarse para agregar credenciales. Desde esta página, los administradores pueden habilitar/deshabilitar clientes y navegar al formulario de edición de cada cliente.
/admin/config/system/oauth2-client/{oauth2_client}/edit
Formulario de edición para configurar las credenciales y ajustes de un cliente OAuth2. El formulario muestra campos dinámicamente según el tipo de concesión y los proveedores de credenciales disponibles.
/admin/config/system/oauth2-client/{oauth2_client}/disable
Formulario de confirmación para deshabilitar un cliente OAuth2. Los clientes deshabilitados no devolverán tokens desde Oauth2ClientService.
Permisos 1
Hooks 1
hook_oauth2_client_info_alter
Altera las definiciones de plugins de OAuth2 Client antes de que se usen. Permite a los módulos modificar la configuración de los plugins de cliente OAuth2 registrados en el sistema.
Troubleshooting 5
Use el botón 'Guardar y solicitar token' en el formulario de edición para probar su configuración. Verifique el mensaje de error devuelto. Verifique que el client_id, client_secret, authorization_uri y token_uri sean correctos. Asegúrese de que el URI de redirección registrado con el servicio externo coincida con el generado por el módulo (/oauth2-client/{plugin}/code).
Verifique que la entidad de configuración del cliente OAuth2 esté habilitada. Compruebe que el parámetro state coincida asegurándose de que las sesiones funcionen correctamente. Limpie la caché de Drupal e intente nuevamente.
Para las concesiones authorization_code y resource_owner, los tokens no pueden renovarse automáticamente si expiran sin un token de actualización. Necesita reautenticar al usuario u obtener un nuevo token a través del flujo de concesión original.
Asegúrese de que el módulo Key esté instalado y que la clave sea de tipo 'oauth2_client'. El valor de la clave debe ser JSON válido con los campos client_id y client_secret. Verifique que el credential_provider esté configurado como 'key' en la configuración del cliente OAuth2.
Limpie la caché de Drupal para activar el descubrimiento de plugins. Asegúrese de que su clase de plugin tenga el namespace correcto (Plugin/Oauth2Client), extienda Oauth2ClientPluginBase y tenga un atributo #[Oauth2Client] válido con todos los parámetros requeridos.
Security Notes 6
- Los secretos de cliente almacenados en almacenamiento local (State API) se guardan en la base de datos - use el módulo Key con almacenamiento de archivos para mejor seguridad en producción
- Nunca incluya las claves del módulo Key en el control de versiones cuando use la opción de almacenamiento de configuración - esto es solo para desarrollo local
- El flujo de código de autorización incluye protección CSRF a través de la validación del parámetro state
- El permiso 'administer oauth2 clients' está marcado como acceso restringido - otórguelo solo a administradores de confianza
- Para el tipo de concesión resource_owner, los nombres de usuario y contraseñas se usan solo para obtener tokens y no se persisten
- Implemente verificación de acceso personalizada vía Oauth2ClientPluginAccessInterface si el acceso basado en permisos predeterminado no es apropiado para su caso de uso