Simple OAuth (OAuth2) & OpenID Connect
A comprehensive OAuth 2.0 Authorization Framework and OpenID Connect implementation for Drupal, built on the League OAuth2 Server library.
simple_oauth
Install
composer require 'drupal/simple_oauth:^6.1'
Overview
Simple OAuth provides a complete OAuth 2.0 Authorization Framework RFC implementation for Drupal. It enables secure API authentication using Bearer tokens, allowing third-party applications to access Drupal resources on behalf of users without exposing credentials.
The module is built on top of The League of Extraordinary Packages OAuth2 Server, which is the de-facto standard for modern PHP OAuth implementations. It supports all major OAuth 2.0 grant types including Authorization Code (with PKCE support), Password Credentials, Client Credentials, Implicit, and Refresh Token grants.
The module also includes full OpenID Connect support, providing standardized identity layer on top of OAuth 2.0, complete with JWT-based tokens, user info endpoints, and JSON Web Key Set (JWKS) endpoints for token verification.
OAuth2 scopes are implemented as Drupal roles, providing a flexible and familiar permission model. Tokens are stored as content entities and can be managed through the admin interface or cleaned up automatically via cron.
Features
- OAuth 2.0 Authorization Framework RFC implementation with Bearer token authentication
- OpenID Connect identity layer with customizable user claims (sub, name, email, preferred_username, locale, profile, updated_at, zoneinfo)
- Six OAuth2 grant types: Authorization Code, Password Credentials, Client Credentials, Implicit, Refresh Token, and Code
- PKCE (Proof Key for Code Exchange) support for secure native and single-page applications
- JWT-based access tokens with RSA encryption for secure token validation
- Drupal role-based OAuth2 scopes for fine-grained permission control
- Automatic token expiration and cleanup via cron with configurable batch size
- Consumer/Client management through the Consumers module with custom fields (secret, redirect URI, default user, confidential flag)
- Debug endpoint for inspecting token information and permissions
- JSON Web Key Set (JWKS) endpoint for third-party token verification
- User Info endpoint for OpenID Connect user attribute retrieval
- Built-in key generation tool for RSA public/private key pair creation
- Global authentication provider that integrates with all Drupal REST resources
- Token revocation when user accounts or client applications are updated
Use Cases
Mobile Application Authentication
Use the Authorization Code grant with PKCE for mobile applications. Configure a non-confidential client (confidential=false, pkce=true) with a custom redirect URI scheme. The mobile app initiates the OAuth flow, the user authenticates in a web browser, and the app receives an authorization code via the redirect URI which it exchanges for tokens.
Single Page Application (SPA) Authentication
Use the Authorization Code grant with PKCE for SPAs. Create a non-confidential client with your SPA's origin as the redirect URI. The SPA uses the code_challenge and code_verifier parameters to securely obtain tokens without exposing a client secret in the browser.
Server-to-Server Communication
Use the Client Credentials grant for backend services that need to access the Drupal API. Create a confidential client with a strong secret, and assign roles that define what the service can access. The service authenticates with client_id and client_secret to receive an access token.
First-Party Application with User Login
Use the Password grant for trusted first-party applications where you control both the client and server. The user enters their Drupal credentials in your application, which exchanges them for tokens. Only use this for applications you fully trust.
Long-Running Sessions
Configure short access token expiration (5 minutes) with long refresh token expiration (14 days). Clients use the Refresh Token grant to obtain new access tokens without re-authenticating, providing security while maintaining user sessions.
OpenID Connect Identity Provider
Use Simple OAuth as an OpenID Connect provider for other applications. Third-party applications can authenticate users through your Drupal site and receive standardized user claims (name, email, etc.) through the /oauth/userinfo endpoint.
Decoupled Drupal Architecture
Use Simple OAuth to secure API access for headless/decoupled Drupal installations. Frontend applications (React, Vue, Angular) authenticate users and make authorized API requests to Drupal using Bearer tokens.
API Gateway Integration
Configure external API gateways to validate Drupal-issued JWT tokens using the /oauth/jwks endpoint. The gateway can verify tokens without contacting Drupal for each request, improving performance and reducing load.
Tips
- Always use HTTPS in production to protect tokens in transit
- Store RSA keys outside the webroot and restrict file permissions (600 or 400)
- Use short access token lifetimes (5-10 minutes) and longer refresh token lifetimes for security
- Create specific roles for OAuth2 scopes rather than using existing admin roles
- Enable PKCE for all public clients (mobile apps, SPAs) even if not required
- Use the Authorization Code grant instead of Implicit whenever possible
- Monitor the oauth2_token table size and configure appropriate cron batch sizes
- Test your OAuth implementation with tools like Postman or OAuth 2.0 Playground
- Review tokens periodically using the admin interface at /admin/config/people/simple_oauth/oauth2_token
- Use the debug endpoint (/oauth/debug) during development to verify token permissions
Technical Details
Admin Pages 5
/admin/config/people/simple_oauth
Configure OAuth2 token expiration times, RSA key paths, and general OAuth2 behavior settings. This is the main configuration page for the Simple OAuth module.
/admin/config/people/simple_oauth/openid-connect
Configure OpenID Connect settings and view available claims. Claims are managed through the service container.
/admin/config/people/simple_oauth/oauth2_token
View and manage all OAuth2 tokens stored in the system. Lists access tokens, authorization codes, and refresh tokens.
/admin/config/people/simple_oauth/oauth2_token/{oauth2_token}
View details of a specific OAuth2 token including its type, associated user, client, and expiration.
/admin/config/people/simple_oauth/oauth2_token/{oauth2_token}/delete
Confirm deletion of a specific OAuth2 token. This will immediately revoke the token.
Permissions 7
Hooks 2
hook_simple_oauth_private_claims_alter
Alter the private claims included in JWT access tokens before conversion.
hook_simple_oauth_oidc_claims_alter
Allow injecting custom claims to OpenID Connect responses. Use this to add site-specific user attributes to the claims.
Drush Commands 1
drush simple-oauth:generate-keys
Generate RSA public and private key pair for OAuth2 token encryption. Creates both private.key and public.key in the specified directory.
Troubleshooting 8
The upstream OAuth library checks private key permissions by default. In containerized environments with injected secrets, this may cause false positives. Add $settings['simple_oauth.key_permissions_check'] = FALSE; in settings.php to disable the check.
Check your server time is correct and synchronized. Token expiration is based on server time. Also verify your access_token_expiration setting is appropriate (default 300 seconds).
Simple OAuth requires at least one role to be available as a scope. Create a custom Drupal role (not anonymous, authenticated, or admin) to use as an OAuth2 scope before creating clients.
Verify the client_id matches the UUID of a Consumer entity. If using a confidential client, ensure the client_secret is correct. Check if the client is set to validate secrets (confidential=true).
Authorization codes are single-use. Once exchanged for tokens, they cannot be reused. If testing, request a new authorization code for each token exchange.
Ensure cron is running. Check the token_cron_batch_size setting - if set to 0, all expired tokens should be deleted. Set a specific batch size for large sites to prevent timeout issues.
Check if disable_openid_connect is set to true in your configuration. The /oauth/userinfo and /oauth/jwks endpoints are disabled when OpenID Connect is disabled.
Ensure your code_challenge was generated correctly using S256 (SHA256 hash of code_verifier, base64url encoded). The code_verifier must be the same value used to generate the code_challenge.
Security Notes 8
- Never store client secrets in client-side code (JavaScript, mobile apps). Use PKCE instead.
- The Implicit grant is disabled by default due to security concerns. Only enable it if you understand the risks.
- Tokens act like passwords - protect them accordingly. Never log or expose tokens in URLs.
- Client secrets should be strong, random values. They are stored hashed in the database.
- Consider token revocation on user password change or account status change (handled automatically by the module).
- The Password grant should only be used with first-party, fully trusted applications.
- Regularly rotate RSA keys and client secrets in production environments.
- Restrict the 'debug simple_oauth tokens' permission to administrators only.