External Authentication
A helper module that provides services for authenticating users using external sites or services and storing identification details in an authmap table.
externalauth
Install
composer require 'drupal/externalauth:^2.0'
Overview
The External Authentication module provides a generic service for logging in and registering users that are authenticated against an external site or service and storing the authentication details. It serves as the Drupal 8+ equivalent of user_external_login_register() and related functions, as well as the authmap table that existed in Drupal 6 & 7 core.
This module is designed as a foundational API for other external authentication modules (such as SAML, LDAP, OAuth, etc.) to build upon. It provides a consistent API for storing and retrieving external authentication data, mapping external identities to Drupal user accounts.
The module stores authentication mappings in an 'authmap' database table, linking external authentication names (authnames) provided by authentication providers to Drupal user accounts. Each mapping can also store additional serialized data specific to the authentication provider.
Features
- Provides services for loading, logging in, registering, and linking Drupal users based on external authentication names
- Stores authentication mapping data (authname to Drupal user ID) in a dedicated authmap database table
- Supports storing additional serialized data with each authentication mapping for provider-specific information
- Fires events during login, registration, and authmap alteration for other modules to react to or modify behavior
- Includes an administrative Views-based interface to manage external authentication links between users and providers
- Automatically cleans up authmap entries when Drupal users are deleted
- Provides migrate plugins for upgrading authmap data from Drupal 6 and Drupal 7 installations
- Supports multiple authentication providers per user, allowing users to log in through different external services
Use Cases
SAML Single Sign-On Integration
When implementing SAML-based SSO using a module like samlauth, the externalauth module stores the mapping between SAML NameID (external identifier) and Drupal user accounts. The samlauth module calls externalauth.externalauth->loginRegister() to handle user authentication, automatically creating new Drupal accounts for first-time SAML users.
LDAP Authentication
For LDAP authentication, the externalauth module maps LDAP Distinguished Names (DN) or usernames to Drupal accounts. When a user authenticates via LDAP, the authentication module uses externalauth services to find or create the corresponding Drupal user and establish the login session.
OAuth/OpenID Connect Login
Social login implementations using OAuth or OpenID Connect can use externalauth to map external user identifiers (like Google or Facebook user IDs) to Drupal accounts. This enables 'Login with Google' type functionality while maintaining proper user account mapping.
Multi-Provider Authentication
Organizations allowing users to authenticate through multiple external systems (e.g., both SAML and LDAP) can use externalauth to manage mappings for each provider. A single Drupal user can have multiple authmap entries, one per provider, enabling flexible authentication options.
Site Migration from Drupal 6/7
When migrating from Drupal 6 or 7 sites that used external authentication, the migration templates (d6_authmap and d7_authmap) preserve existing authentication mappings, ensuring users can continue logging in with their external credentials after migration.
Custom Authentication Provider Development
Developers creating custom authentication modules can use externalauth as a foundation. By calling the provided services, custom modules can focus on the authentication logic specific to their provider while relying on externalauth for user registration, login finalization, and mapping storage.
Tips
- Use the ExternalAuthAuthmapAlterEvent to customize the Drupal username generated during registration, preventing default provider_authname format if needed
- The authmap view at /admin/people/authmap accepts contextual filters, so you can access provider-specific lists at /admin/people/authmap/{provider}
- Store provider-specific data in the authmap_data parameter when calling register() or linkExistingAccount() - this data is serialized and stored with the mapping
- Subscribe to externalauth.register event to perform additional user setup after external registration (e.g., assigning roles based on external attributes)
- The linkExistingAccount() method returns FALSE if the account is already linked with the same authname, allowing idempotent operations
- When multiple external auth providers are used, consider customizing the authmap view to show the provider column for clarity
Technical Details
Admin Pages 2
/admin/people/authmap
A Views-based administrative page that displays all external authentication name mappings registered by external authentication methods for each user. The page shows the Authentication Name (external identifier), Drupal User ID, Drupal User Name (with link to user profile), and a delete operation link. The list can be filtered by authentication name and Drupal user. Provider-specific views are available at /admin/people/authmap/{provider} (e.g., /admin/people/authmap/samlauth).
/admin/people/authmap/{provider}/{uid}/delete
Confirmation form for deleting a specific external authentication link between an authentication name and a Drupal user account. The form displays the authentication name and Drupal username being unlinked and requires confirmation before deletion.
Permissions 2
Hooks 1
hook_user_delete
Automatically deletes all authmap entries for a user when the user account is deleted, ensuring data integrity.
Troubleshooting 4
Check the authmap table to verify a mapping exists for the user's external authname and provider. Use the admin view at /admin/people/authmap to search for the authentication name. If no mapping exists, the user may need to be registered first or have their account linked.
This typically occurs when multiple authentication providers are active. Add the 'provider' field to the view configuration, or use provider-specific URLs like /admin/people/authmap/samlauth to filter by provider.
This exception is thrown when a user with the same Drupal username already exists. Either ensure unique usernames are generated (default is provider_authname) or handle the exception by linking to the existing account instead.
The module implements hook_user_delete to clean up authmap entries automatically. Ensure the module is enabled and working correctly. Manual cleanup can be done via the admin interface or directly in the database.
Security Notes 5
- External authentication modules should validate authnames and user data from external sources before passing to externalauth services
- The delete operation for authmap entries requires the 'delete authmap' permission - grant this only to trusted administrators
- Authnames are not exposed in delete form URLs to prevent leaking external identifiers in HTTP referrer logs
- The authmap table stores sensitive mapping data - ensure proper database access controls are in place
- When implementing custom authentication providers, validate that the external authentication response is legitimate before calling login/register services