SAML Authentication
Enables SAML 2.0 Single Sign-On (SSO) authentication, allowing users to log into Drupal through external SAML Identity Providers.
samlauth
Install
composer require 'drupal/samlauth:8.x-3.12'
Overview
The SAML Authentication module integrates Drupal with SAML 2.0 Identity Providers (IdPs), enabling Single Sign-On (SSO) authentication for your Drupal site. Users can authenticate against external identity management systems like Azure AD, Okta, OneLogin, Google Workspace, SimpleSAMLphp, or any other SAML 2.0 compliant IdP.
The module implements the Service Provider (SP) side of the SAML protocol using the OneLogin PHP SAML Toolkit. It handles the complete authentication flow including login redirects to the IdP, processing SAML assertions, user account creation/linking, attribute synchronization, and logout functionality.
Key capabilities include configurable user linking strategies (by email, name, or custom attributes), automatic user account creation from SAML attributes, role-based access control for local Drupal login, and comprehensive security options for signing and encrypting SAML messages. The module supports X.509 certificate management through files, configuration values, or the Key module for enhanced security.
Features
- SAML 2.0 Single Sign-On (SSO) authentication with external Identity Providers
- Automatic user account creation from SAML attributes (name, email, custom fields)
- Flexible user account linking by unique ID, email address, or username
- Role-based restrictions for local Drupal login (block SAML users from local authentication)
- X.509 certificate and private key management via files, configuration, or Key module
- SP Metadata XML generation for IdP configuration
- Configurable NameID formats and policy requirements
- Request/response signing and encryption options
- Support for multiple IdP certificates (for key rotation)
- New certificate support for SP key rotation planning
- Single Logout Service (SLS) support
- Custom events for user linking and synchronization hooks
- Flood control protection against brute force attacks
- Debug logging for SAML messages (incoming/outgoing)
- Optional Views integration for managing authmap entries
- Integration with External Auth module for account linking
Use Cases
Enterprise Single Sign-On Integration
Connect your Drupal site to corporate identity providers like Azure Active Directory, Okta, or OneLogin. Users authenticate once with corporate credentials and gain access to Drupal without separate passwords. Configure automatic user creation and role assignment based on SAML attributes.
Educational Institution Authentication
Integrate with Shibboleth/InCommon federations for university single sign-on. Map eduPerson attributes to Drupal user fields. Support multiple identity providers for research collaboration portals.
Customer Portal Access Control
Provide external partners or customers secure access via their organization's identity provider. Use user linking to connect SAML logins to pre-created Drupal accounts. Restrict which roles can use local login for security.
Government/Healthcare Compliance
Meet security requirements by using organization-approved identity providers. Enable encryption for SAML assertions and NameID. Ensure signed requests/responses for audit trails. Configure strict validation for production environments.
Multi-IdP Testing Environment
Test SAML integration using Docker-based SimpleSAMLphp IdP locally while production uses corporate IdP. Use /saml/reauth to force re-authentication during testing. Enable debug logging to inspect SAML messages.
Tips
- Always enable 'Strict validation' and signing options in production environments for security
- Use the Key module with external key providers for secure certificate/key storage in production
- Set Metadata validity to 2 days (172800 seconds) and enable HTTP caching after initial setup
- Exchange metadata with IdP administrators via the /saml/metadata URL rather than manual configuration
- Test with /saml/reauth to force re-authentication without clearing browser sessions
- Enable debug logging temporarily during setup, then disable for production
- Pre-populate authmap entries for known users instead of enabling automatic linking for better security
- Use samlauth_user_roles submodule to automatically assign roles based on IdP group membership
- Configure 'Change password URL' to direct users to their IdP's password management page
- Back up configuration before certificate rotation; use 'New certificate' field to prepare IdP for key changes
Technical Details
Admin Pages 3
/admin/config/people/saml
Configure user-related SAML authentication settings including user interface options, unique ID source, user linking behavior, account creation, and login/logout redirection.
/admin/config/people/saml/saml
Configure SAML protocol settings including Service Provider configuration, Identity Provider settings, message construction/validation options, and debugging.
/admin/config/people/saml/authmap/{uid}/delete
Confirmation form to delete the link between a SAML login ID and a Drupal user account.
Permissions 2
Hooks 4
hook_form_user_form_alter
Alters user edit form to hide password field and lock email for SAML-only users
hook_form_user_login_form_alter
Adds SAML login link to the login form and validates SAML-only users
hook_form_user_pass_alter
Validates password reset form to prevent SAML-only users from resetting password
hook_user_presave
Synchronizes SAML attributes before saving a new user account
Troubleshooting 7
This means SAML communication works but the configured unique ID attribute was not found. Enable 'Log incoming SAML messages' in debugging options, attempt login, then check Recent log messages for the SAML response XML. Look for the attribute names and update 'Unique ID attribute' configuration accordingly.
This typically happens behind a reverse proxy. Configure trusted_host_patterns and reverse_proxy settings in settings.php as documented at drupal.org/docs/getting-started/installing-drupal/using-a-load-balancer-or-reverse-proxy
Enable 'Retrieve logout signature parameters from $_SERVER[REQUEST]' in SAML Message Validation settings. This option fixes signature validation issues with Microsoft identity providers.
Install the flood_control module for administrative UI to clear flood entries. Alternatively, clear entries directly from the 'flood' database table. Flood protection triggers after many failed login attempts from the same IP.
Once a user logs in via SAML, they are restricted from local Drupal login unless they have a role listed in 'Roles allowed to use Drupal login'. Add appropriate roles or use drush config:set samlauth.authentication drupal_login_roles '["authenticated"]' to allow all users.
This occurs when the Unique ID changes or is not truly unique. Ensure Unique ID source never changes after users start logging in. If duplicates exist, manually delete them and remove incorrect authmap entries via /admin/people/authmap/samlauth view.
Your IdP uses non-password authentication (like passkeys). Disable 'Specify authentication context (as password)' checkbox in SAML Message Construction settings.
Security Notes 9
- User linking based on email/name attributes poses security risks if users can modify these values at the IdP - attackers could take over existing accounts
- Always use HTTPS for your Drupal site when implementing SAML authentication
- Store private keys outside the web document root when using file-based storage
- The 'configure saml' permission should only be granted to highly trusted administrators
- Enable request/response signing to prevent SAML message tampering
- Consider enabling assertion encryption for sensitive environments
- Review map_users_roles to restrict which existing accounts can be automatically linked
- Flood control protects against brute force attacks but legitimate users may be blocked after IdP issues
- Local login restrictions prevent SAML-authenticated users from bypassing IdP security policies