Simple OAuth (OAuth2) y OpenID Connect
Una implementación completa del Framework de Autorización OAuth 2.0 y OpenID Connect para Drupal, construida sobre la biblioteca League OAuth2 Server.
simple_oauth
Install
composer require 'drupal/simple_oauth:^6.1'
Overview
Simple OAuth proporciona una implementación completa del RFC del Framework de Autorización OAuth 2.0 para Drupal. Permite la autenticación segura de API utilizando tokens Bearer, permitiendo que aplicaciones de terceros accedan a los recursos de Drupal en nombre de los usuarios sin exponer credenciales.
El módulo está construido sobre The League of Extraordinary Packages OAuth2 Server, que es el estándar de facto para implementaciones modernas de OAuth en PHP. Soporta todos los principales tipos de concesión OAuth 2.0, incluyendo Authorization Code (con soporte PKCE), Password Credentials, Client Credentials, Implicit y Refresh Token.
El módulo también incluye soporte completo para OpenID Connect, proporcionando una capa de identidad estandarizada sobre OAuth 2.0, con tokens basados en JWT, endpoints de información de usuario y endpoints JSON Web Key Set (JWKS) para verificación de tokens.
Los scopes de OAuth2 se implementan como roles de Drupal, proporcionando un modelo de permisos flexible y familiar. Los tokens se almacenan como entidades de contenido y pueden gestionarse a través de la interfaz de administración o limpiarse automáticamente mediante cron.
Features
- Implementación del RFC del Framework de Autorización OAuth 2.0 con autenticación mediante token Bearer
- Capa de identidad OpenID Connect con claims de usuario personalizables (sub, name, email, preferred_username, locale, profile, updated_at, zoneinfo)
- Seis tipos de concesión OAuth2: Authorization Code, Password Credentials, Client Credentials, Implicit, Refresh Token y Code
- Soporte PKCE (Proof Key for Code Exchange) para aplicaciones nativas y de página única seguras
- Tokens de acceso basados en JWT con cifrado RSA para validación segura de tokens
- Scopes OAuth2 basados en roles de Drupal para control de permisos granular
- Expiración automática de tokens y limpieza mediante cron con tamaño de lote configurable
- Gestión de consumidores/clientes a través del módulo Consumers con campos personalizados (secreto, URI de redirección, usuario predeterminado, indicador confidencial)
- Endpoint de depuración para inspeccionar información y permisos de tokens
- Endpoint JSON Web Key Set (JWKS) para verificación de tokens por terceros
- Endpoint User Info para recuperación de atributos de usuario de OpenID Connect
- Herramienta integrada de generación de claves para crear pares de claves RSA pública/privada
- Proveedor de autenticación global que se integra con todos los recursos REST de Drupal
- Revocación de tokens cuando se actualizan cuentas de usuario o aplicaciones cliente
Use Cases
Autenticación de Aplicación Móvil
Use la concesión Authorization Code con PKCE para aplicaciones móviles. Configure un cliente no confidencial (confidential=false, pkce=true) con un esquema de URI de redirección personalizado. La aplicación móvil inicia el flujo OAuth, el usuario se autentica en un navegador web, y la aplicación recibe un código de autorización a través de la URI de redirección que intercambia por tokens.
Autenticación de Aplicación de Página Única (SPA)
Use la concesión Authorization Code con PKCE para SPAs. Cree un cliente no confidencial con el origen de su SPA como URI de redirección. La SPA usa los parámetros code_challenge y code_verifier para obtener tokens de forma segura sin exponer un secreto de cliente en el navegador.
Comunicación Servidor a Servidor
Use la concesión Client Credentials para servicios backend que necesitan acceder a la API de Drupal. Cree un cliente confidencial con un secreto fuerte, y asigne roles que definan a qué puede acceder el servicio. El servicio se autentica con client_id y client_secret para recibir un token de acceso.
Aplicación de Primera Parte con Inicio de Sesión de Usuario
Use la concesión Password para aplicaciones de primera parte confiables donde usted controla tanto el cliente como el servidor. El usuario ingresa sus credenciales de Drupal en su aplicación, que las intercambia por tokens. Solo use esto para aplicaciones en las que confía completamente.
Sesiones de Larga Duración
Configure una expiración corta del token de acceso (5 minutos) con una expiración larga del refresh token (14 días). Los clientes usan la concesión Refresh Token para obtener nuevos tokens de acceso sin re-autenticarse, proporcionando seguridad mientras mantienen las sesiones de usuario.
Proveedor de Identidad OpenID Connect
Use Simple OAuth como proveedor de OpenID Connect para otras aplicaciones. Las aplicaciones de terceros pueden autenticar usuarios a través de su sitio Drupal y recibir claims de usuario estandarizados (nombre, email, etc.) a través del endpoint /oauth/userinfo.
Arquitectura Drupal Desacoplada
Use Simple OAuth para asegurar el acceso API para instalaciones Drupal headless/desacopladas. Las aplicaciones frontend (React, Vue, Angular) autentican usuarios y realizan solicitudes API autorizadas a Drupal usando tokens Bearer.
Integración con API Gateway
Configure gateways de API externos para validar tokens JWT emitidos por Drupal usando el endpoint /oauth/jwks. El gateway puede verificar tokens sin contactar a Drupal para cada solicitud, mejorando el rendimiento y reduciendo la carga.
Tips
- Siempre use HTTPS en producción para proteger los tokens en tránsito
- Almacene las claves RSA fuera del webroot y restrinja los permisos de archivo (600 o 400)
- Use tiempos de vida cortos para tokens de acceso (5-10 minutos) y tiempos más largos para refresh tokens por seguridad
- Cree roles específicos para scopes OAuth2 en lugar de usar roles de administrador existentes
- Habilite PKCE para todos los clientes públicos (aplicaciones móviles, SPAs) incluso si no es requerido
- Use la concesión Authorization Code en lugar de Implicit siempre que sea posible
- Monitoree el tamaño de la tabla oauth2_token y configure tamaños de lote de cron apropiados
- Pruebe su implementación OAuth con herramientas como Postman o OAuth 2.0 Playground
- Revise los tokens periódicamente usando la interfaz de administración en /admin/config/people/simple_oauth/oauth2_token
- Use el endpoint de depuración (/oauth/debug) durante el desarrollo para verificar los permisos del token
Technical Details
Admin Pages 5
/admin/config/people/simple_oauth
Configurar tiempos de expiración de tokens OAuth2, rutas de claves RSA y configuración general del comportamiento OAuth2. Esta es la página principal de configuración del módulo Simple OAuth.
/admin/config/people/simple_oauth/openid-connect
Configurar ajustes de OpenID Connect y ver los claims disponibles. Los claims se gestionan a través del contenedor de servicios.
/admin/config/people/simple_oauth/oauth2_token
Ver y gestionar todos los tokens OAuth2 almacenados en el sistema. Lista tokens de acceso, códigos de autorización y refresh tokens.
/admin/config/people/simple_oauth/oauth2_token/{oauth2_token}
Ver detalles de un token OAuth2 específico incluyendo su tipo, usuario asociado, cliente y expiración.
/admin/config/people/simple_oauth/oauth2_token/{oauth2_token}/delete
Confirmar la eliminación de un token OAuth2 específico. Esto revocará el token inmediatamente.
Permissions 7
Hooks 2
hook_simple_oauth_private_claims_alter
Modificar los claims privados incluidos en tokens de acceso JWT antes de la conversión.
hook_simple_oauth_oidc_claims_alter
Permitir inyectar claims personalizados en respuestas de OpenID Connect. Use esto para añadir atributos de usuario específicos del sitio a los claims.
Drush Commands 1
drush simple-oauth:generate-keys
Generar par de claves RSA pública y privada para cifrado de tokens OAuth2. Crea tanto private.key como public.key en el directorio especificado.
Troubleshooting 8
La biblioteca OAuth upstream verifica los permisos de la clave privada por defecto. En entornos containerizados con secretos inyectados, esto puede causar falsos positivos. Añada $settings['simple_oauth.key_permissions_check'] = FALSE; en settings.php para desactivar la verificación.
Verifique que la hora del servidor sea correcta y esté sincronizada. La expiración del token se basa en la hora del servidor. También verifique que su configuración access_token_expiration sea apropiada (predeterminado 300 segundos).
Simple OAuth requiere que al menos un rol esté disponible como scope. Cree un rol de Drupal personalizado (no anónimo, autenticado o admin) para usar como scope OAuth2 antes de crear clientes.
Verifique que el client_id coincida con el UUID de una entidad Consumer. Si usa un cliente confidencial, asegúrese de que el client_secret sea correcto. Compruebe si el cliente está configurado para validar secretos (confidential=true).
Los códigos de autorización son de un solo uso. Una vez intercambiados por tokens, no pueden reutilizarse. Si está probando, solicite un nuevo código de autorización para cada intercambio de token.
Asegúrese de que cron esté ejecutándose. Verifique la configuración token_cron_batch_size - si está establecida a 0, todos los tokens expirados deberían eliminarse. Establezca un tamaño de lote específico para sitios grandes para prevenir problemas de tiempo de espera.
Compruebe si disable_openid_connect está establecido a true en su configuración. Los endpoints /oauth/userinfo y /oauth/jwks están deshabilitados cuando OpenID Connect está desactivado.
Asegúrese de que su code_challenge se generó correctamente usando S256 (hash SHA256 del code_verifier, codificado en base64url). El code_verifier debe ser el mismo valor usado para generar el code_challenge.
Security Notes 8
- Nunca almacene secretos de cliente en código del lado del cliente (JavaScript, aplicaciones móviles). Use PKCE en su lugar.
- La concesión Implicit está deshabilitada por defecto debido a preocupaciones de seguridad. Solo habilítela si entiende los riesgos.
- Los tokens actúan como contraseñas - protéjalos en consecuencia. Nunca registre o exponga tokens en URLs.
- Los secretos de cliente deben ser valores fuertes y aleatorios. Se almacenan hasheados en la base de datos.
- Considere la revocación de tokens al cambiar la contraseña del usuario o el estado de la cuenta (manejado automáticamente por el módulo).
- La concesión Password solo debe usarse con aplicaciones de primera parte completamente confiables.
- Rote regularmente las claves RSA y los secretos de cliente en entornos de producción.
- Restrinja el permiso 'debug simple_oauth tokens' solo a administradores.