OpenID Connect / OAuth client
A pluggable client implementation for the OpenID Connect protocol, enabling users to authenticate with external identity providers.
openid_connect
Install
composer require 'drupal/openid_connect:8.x-1.4'
Overview
The OpenID Connect module provides a comprehensive pluggable client implementation for the OpenID Connect protocol, which is a simple identity layer on top of OAuth 2.0. It allows Drupal sites to authenticate users using external OpenID Connect providers such as Google, Facebook, GitHub, LinkedIn, and Okta, as well as any custom provider through a generic client.
When users sign in with an OpenID Connect provider for the first time, a new Drupal user account is automatically created. The module supports synchronization of user profile information from identity providers to Drupal user fields through configurable claims mapping. Role mapping functionality allows automatic assignment of Drupal roles based on groups or claims provided by the identity provider.
The module provides flexible integration options including a login block, configurable display of login buttons on the standard user login form, and support for automatic login redirection when only one provider is configured. It also supports single logout (SLO) functionality where logging out from Drupal can also terminate the session at the identity provider.
Features
- Multiple built-in OpenID Connect client plugins for Google, Facebook, GitHub, LinkedIn, Okta, and a Generic client for custom providers
- Automatic user account creation upon first login with an external provider
- Claims mapping to synchronize user profile information from identity providers to Drupal user fields
- Experimental role mapping to automatically assign Drupal roles based on identity provider groups
- OpenID Connect Discovery support for automatic endpoint configuration via well-known URIs
- Single logout (SLO) support to terminate sessions at both Drupal and the identity provider
- Configurable login button display options: hidden, above, below, replace, or force replace the standard login form
- Auto-start login process option for automatic redirection to the identity provider
- Connected accounts management allowing users to link/unlink external provider accounts
- ISS-based SSO initiation support for identity provider-initiated login flows
- Session token management for ID tokens, access tokens, refresh tokens, and expiration tracking
- Extensible plugin architecture allowing developers to create custom client plugins
- State token validation for CSRF protection during OAuth flows
Use Cases
Enterprise SSO with Google Workspace
Organizations using Google Workspace can enable users to log in to their Drupal intranet using their corporate Google accounts. Enable the Google client, configure it with OAuth credentials from Google Cloud Console, and users can authenticate with their work email addresses.
Social Login for Community Sites
Community and membership sites can lower the barrier to registration by allowing users to sign up using their existing Facebook, GitHub, or LinkedIn accounts. This eliminates the need for users to create and remember yet another password.
Integration with Enterprise Identity Providers
Using the Generic or Okta client, enterprises can integrate Drupal with their existing identity management systems like Azure AD, Keycloak, Auth0, or any OpenID Connect-compliant provider. The auto-discovery feature simplifies configuration by automatically fetching endpoint URLs.
Centralized User Management
Organizations can manage user accounts centrally in their identity provider and have changes automatically synchronized to Drupal. Claims mapping ensures user profile fields are kept up-to-date, while role mapping can automatically assign permissions based on group membership.
Restricting Login to SSO Only
For high-security environments, administrators can configure the module to replace the standard login form entirely, forcing all users to authenticate through the corporate identity provider. The 'showcore' URL parameter provides an escape hatch for administrators if needed.
Developer Authentication for GitHub-based Teams
Development teams can use GitHub authentication to allow team members to log in using their GitHub accounts. This is particularly useful for open source projects where contributors already have GitHub accounts.
Tips
- Use the Generic client with auto-discovery for any OpenID Connect-compliant provider to minimize configuration
- Test OAuth configurations in a development environment before deploying to production
- When using the 'Replace' login form option, users can access the standard login form by adding ?showcore to the URL
- The module stores tokens in the user's session, which can be retrieved using the openid_connect.session service for API calls to the identity provider
- Custom client plugins can be created by extending OpenIDConnectClientBase and using the @OpenIDConnectClient annotation
- Use hook_openid_connect_pre_authorize to implement custom authorization logic, such as restricting login to users with specific claims
- Role mapping is experimental - test thoroughly before relying on it in production
- For security, only enable 'Automatically connect existing users' with trusted identity providers where email addresses are verified
Technical Details
Admin Pages 4
/admin/config/people/openid-connect
Lists all configured OpenID Connect client entities. Administrators can add new clients, edit existing configurations, enable/disable clients, and delete clients from this page.
/admin/config/people/openid-connect/add/{plugin_id}
Form to add a new OpenID Connect client. The available fields depend on the selected plugin type.
/admin/config/people/openid-connect/settings
Global settings for OpenID Connect login behavior, user claims mapping, and role mapping.
/user/{user}/connected-accounts
Allows users to view and manage their connected external identity provider accounts. Users can connect new providers or disconnect existing ones.
Permissions 4
Hooks 9
hook_openid_connect_claims_alter
Allows modules to modify the list of available OpenID Connect claims.
hook_openid_connect_client_info_alter
Allows modules to alter client plugin definitions, including adding new plugins or changing plugin classes.
hook_openid_connect_user_properties_ignore_alter
Allows modules to modify which user properties are excluded from claims mapping.
hook_openid_connect_userinfo_alter
Allows modules to alter user information fetched from the identity provider before authorization.
hook_openid_connect_pre_authorize
Runs before user authorization. Can deny access, override the user account, or perform additional checks.
hook_openid_connect_post_authorize
Runs after successful user authorization. Useful for storing tokens or additional processing.
hook_openid_connect_userinfo_claim_alter
Allows modules to alter individual claim values before they are mapped to user properties.
hook_openid_connect_userinfo_save
Runs after claims mapping but before user account save. Allows mapping additional complex claims.
hook_openid_connect_redirect_logout_alter
Allows modules to alter the redirect response when logging out.
Troubleshooting 7
Check that at least one OpenID Connect client is enabled at /admin/config/people/openid-connect. Verify the 'OpenID buttons display in user login form' setting is not set to 'Hidden' in the Settings tab. Alternatively, place the 'OpenID Connect login' block in a visible region.
The redirect URL configured in your identity provider must exactly match the URL shown when editing the client in Drupal. Ensure the URL includes the correct protocol (https), domain, and path. Check for trailing slashes.
By default, users connected to external providers cannot change their Drupal password. Grant the 'Set a password for local authentication' permission to the appropriate roles if you want users to be able to set a local password.
Auto-login only works when exactly one OpenID Connect client is enabled. If multiple clients are enabled, users must manually select their provider. Also verify the 'Autostart login process' setting is enabled.
Check the 'Save user claims on every login' setting. If disabled, claims are only saved when the account is first created. Also verify the claims mapping configuration on the Settings page.
When using auto-discovery, ensure the Issuer URL is correct and the provider supports the OpenID Connect Discovery specification. Try manually configuring the endpoints if auto-discovery fails.
Verify the 'Logout from identity provider' setting is enabled. Not all providers support end session endpoints - check if your provider supports this feature and if the endpoint is configured in the client settings.
Security Notes 6
- The 'Automatically connect existing users' setting has security implications. Only enable it with identity providers that verify email addresses, as it links accounts based on email match.
- Store Client Secrets securely. Never commit them to version control. Consider using environment variables or a secrets management system.
- All permissions in this module are marked as 'restrict access' due to their sensitivity. Grant them carefully.
- The module implements CSRF protection using state tokens in the OAuth flow.
- When configuring ISS-allowed domains, only list domains you trust to initiate SSO requests.
- Review and test hook implementations that modify authorization behavior (pre_authorize, post_authorize) to ensure they don't introduce security vulnerabilities.