OAuth2 Client
Provides OAuth2 client functionality allowing Drupal to act as an OAuth2 client to authenticate with external OAuth2 servers.
oauth2_client
Install
composer require 'drupal/oauth2_client:^4.1'
composer require 'drupal/oauth2_client:8.x-3.2'
Overview
The OAuth2 Client module enables Drupal sites to integrate with external services using the OAuth2 protocol. It provides a plugin-based architecture for creating OAuth2 clients, handling all backend functionality for token retrieval, refresh, and deletion.
The module leverages the widely-used League OAuth2 Client PHP library from The League of Extraordinary Packages, ensuring robust and standards-compliant OAuth2 implementation. Developers can create custom OAuth2 client plugins by extending the base class and configuring the necessary endpoints, grant types, and scopes.
Configuration entities are automatically created for each plugin, providing an administrative interface for managing credentials. The module supports secure credential storage either locally using Drupal's State API or through the Key module for enhanced security in production environments.
Features
- Plugin-based architecture for creating OAuth2 clients with minimal code
- Support for multiple OAuth2 grant types: Authorization Code, Client Credentials, and Resource Owner Password
- Automatic token refresh when tokens expire and refresh tokens are available
- Two token storage strategies: StateTokenStorage for shared tokens and TempStoreTokenStorage for per-user tokens
- Secure credential management with local storage or Key module integration
- Automatic configuration entity creation for each OAuth2 client plugin
- Custom redirect URI handling after authorization code capture
- Custom access control for authorization code capture routes
- Support for custom OAuth2 providers through the League OAuth2 Client library's provider ecosystem
- Configurable scopes, scope separators, and additional request options per client
- CSRF protection using state parameter validation during authorization code flow
Use Cases
Integrating with a third-party API
When your Drupal site needs to access data from an external service that uses OAuth2 for authentication (such as Google APIs, Microsoft Graph, or custom enterprise services), create an OAuth2 client plugin. Use the client_credentials grant type for server-to-server communication where no user context is needed.
User-authorized external service access
When your site needs to access external resources on behalf of individual users (like accessing a user's Dropbox files or posting to their social media), use the authorization_code grant type with TempStoreTokenStorage. Each user authorizes access and receives their own token stored in their private temp store.
Single Sign-On integration
While not a full SSO solution, the module can be combined with custom authentication code to enable OAuth2-based login flows. Use the authorization_code grant to authenticate users against an external OAuth2 provider and create or link Drupal accounts.
Microservices authentication
In a microservices architecture where Drupal needs to communicate with other services secured by OAuth2, use client_credentials grant type with StateTokenStorage to maintain a shared token for all server-side requests.
Legacy system integration with password grant
For trusted first-party applications or internal tools where direct username/password collection is acceptable, use the resource_owner grant type. Credentials are used only to obtain the token and are not stored.
Tips
- Always use Composer to install this module to ensure the League OAuth2 Client library is properly installed
- For production environments, use the Key module to store credentials outside the database, especially when using file storage in a location outside the web root
- Use StateTokenStorage trait when the external resource is shared by all site users; use TempStoreTokenStorage when each user needs individual authorization
- The redirect URI for authorization_code grants is automatically generated as /oauth2-client/{plugin_id}/code - register this URL with your OAuth2 provider
- Implement Oauth2ClientPluginAccessInterface to customize who can complete the authorization code flow
- Implement Oauth2ClientPluginRedirectInterface to redirect users to a custom page after successful authorization
- You can use dedicated third-party OAuth2 provider packages from the League ecosystem by overriding the getProvider() method
- The request_options plugin attribute allows you to add custom parameters to token requests for non-standard OAuth2 implementations
Technical Details
Admin Pages 3
/admin/config/system/oauth2-client
Lists all OAuth2 client configuration entities. Each client plugin automatically creates a corresponding configuration entity that can be edited to add credentials. From this page, administrators can enable/disable clients and navigate to the edit form for each client.
/admin/config/system/oauth2-client/{oauth2_client}/edit
Edit form for configuring an OAuth2 client's credentials and settings. The form dynamically shows fields based on the grant type and available credential providers.
/admin/config/system/oauth2-client/{oauth2_client}/disable
Confirmation form to disable an OAuth2 client. Disabled clients will not return tokens from the Oauth2ClientService.
Permissions 1
Hooks 1
hook_oauth2_client_info_alter
Alter OAuth2 Client plugin definitions before they are used. Allows modules to modify the configuration of OAuth2 client plugins registered on the system.
Troubleshooting 5
Use the 'Save and request token' button on the edit form to test your configuration. Check the error message returned. Verify that the client_id, client_secret, authorization_uri, and token_uri are correct. Ensure the redirect URI registered with the external service matches the one generated by the module (/oauth2-client/{plugin}/code).
Verify that the OAuth2 client configuration entity is enabled. Check that the state parameter matches by ensuring sessions are working correctly. Clear the Drupal cache and try again.
For authorization_code and resource_owner grants, tokens cannot be automatically renewed if they expire without a refresh token. You need to re-authenticate the user or obtain a new token through the original grant flow.
Ensure the Key module is installed and the key is of type 'oauth2_client'. The key value must be valid JSON with client_id and client_secret fields. Verify the credential_provider is set to 'key' in the OAuth2 client configuration.
Clear the Drupal cache to trigger plugin discovery. Ensure your plugin class has the correct namespace (Plugin/Oauth2Client), extends Oauth2ClientPluginBase, and has a valid #[Oauth2Client] attribute with all required parameters.
Security Notes 6
- Client secrets stored in local storage (State API) are stored in the database - use the Key module with file storage for better security in production
- Never commit Key module keys to version control when using the configuration storage option - this is for local development only
- The authorization code flow includes CSRF protection through state parameter validation
- The 'administer oauth2 clients' permission is marked as restricted access - grant only to trusted administrators
- For resource_owner grant type, usernames and passwords are used only to obtain tokens and are not persisted
- Implement custom access checking via Oauth2ClientPluginAccessInterface if the default permission-based access is not appropriate for your use case