SAML

SAML connects Drupal to your organization's identity provider for single sign-on, with multiple connections, configurable account mapping, and private keys managed through Drupal's Key module.

Let staff, members, and partners sign in with their existing accounts. Keep authentication policies with your identity provider and manage the connection, user profiles, and Drupal access from your site.

Drupal 11.4+ · PHP 8.4+ · SAML 2.0 service provider

The stable 3.0.x release series is built with LightSAML and Key.

Features

Connect one or several identity providers

• Multiple connections: Configure independent identity providers, each with its own metadata, certificates, keys, and account policies.
• Flexible sign-in: Start authentication from Drupal's login form, or explicitly enable identity-provider-initiated login for a connection.
• Single logout: Initiate logout from Drupal and process signed logout requests and responses from the identity provider.
• Local accounts remain available: Add SAML sign-in alongside Drupal's existing account and login functionality.

Control how identities become Drupal accounts

• Optional account provisioning: Create Drupal accounts at first sign-in when provisioning is enabled for the connection.
• Field mapping: Map SAML attributes to supported user fields. Apply transformations, set fallback values, and choose whether a mapping applies only when an account is created.
• Mapping previews: Try sample attributes and inspect the results before applying changes to user accounts.
• Role synchronization: Map identity-provider groups to explicitly allowed Drupal roles while preserving unrelated roles.
• Explicit identity linking: Let authorized users link their own identities, or let administrators associate a known external identity with an existing account.

Configure and maintain connections in Drupal

• Metadata import: Upload an XML file, paste metadata, or fetch it from an HTTPS URL. Review the imported settings before saving them.
• Endpoint helpers: Find and copy the service provider's metadata, login, assertion consumer, and logout URLs from the settings page.
• Key integration: Select signing and decryption private keys managed by Key and configure their matching public certificates.
• Certificate rollover: Configure multiple trusted identity provider certificates during a planned certificate transition.

Authentication and trust

The authentication flow validates signatures, issuer, audience, destination, recipient, and validity periods before establishing a Drupal session. It includes replay protection, request correlation, and browser-session checks, and supports encrypted assertions. Supported SAML bindings are HTTP-Redirect and HTTP-POST.

Account provisioning, email-based account linking, and IdP-initiated login are disabled by default. Enable these policies deliberately for each connection. For private keys, choose a Key provider appropriate to your deployment, such as a file, environment variable, or external key store.

Requirements

• Drupal: 11.4 or newer within the Drupal 11 series.
• PHP: 8.4 or newer, with cURL, DOM/XML, mbstring, and OpenSSL.
• Required module: Key 1.22 or newer in the 1.x series.
• Required library: LightSAML 6.1 or newer in the 6.x series, installed through Composer.
• Identity provider: A SAML 2.0 provider that accepts HTTP-Redirect authentication requests and sends HTTP-POST responses.
• Production configuration: A canonical HTTPS site URL, synchronized server clocks, and valid signing certificates and private keys.

Installation and setup

Install the stable 3.0.x release series and its dependencies from your Drupal site's Composer project directory, then enable the module:

composer require 'drupal/saml:^3.0'
vendor/bin/drush en saml -y
vendor/bin/drush cr

1. Open Configuration → People → SAML Settings at /admin/config/people/saml and add a connection.
2. Give the connection a name and import your identity provider's metadata. Leave the connection disabled while configuring it.
3. Set the public site URL, select the required private keys in Key, and add the matching public certificates. Configure a decryption key when accepting encrypted assertions.
4. Give the service provider metadata URL to your identity provider and configure which users may access the application.
5. Review account provisioning, identity linking, field mappings, role rules, and Drupal permissions before enabling the connection.
6. Test sign-in and logout in a private browser window while keeping a local administrator session available.

Each connection publishes its endpoints beneath /saml/{connection}. The settings page provides the URLs for metadata, login, the assertion consumer service, and single logout.

Current scope and upgrades

Drupal acts as the service provider: an external identity provider authenticates the user, and Drupal establishes the local account and session. Running Drupal as an identity provider is planned for later work. Drupal 12 support is pending compatible dependencies and verification.

The 3.0.x release series introduces a new implementation. There is no automatic migration from earlier 2.x configuration. Plan upgrades on a staging site, recreate and verify connections and account links, and retain a tested rollback path.

For developers and contributors

Extend attribute processing and the account lifecycle through documented events and Drupal hooks. Connections use configuration entities; identity links and session correlations use Drupal content entities. Runtime hooks and public controller routes use PHP attributes.

Development includes unit and kernel tests, a 100% runtime PHP line-coverage gate, JavaScript coverage checks, Drupal coding standards, PHPStan, and Drupal GitLab CI. A Docker development environment includes an optional Keycloak identity provider for testing complete sign-in flows.

Read the setup and development guide, explore the extension API, and review the contribution and testing standards.

Similar projects

• SAML Authentication provides service provider authentication using the OneLogin PHP SAML toolkit. SAML uses LightSAML, requires Key for private-key management, and includes multiple connection configurations.
• simpleSAMLphp Authentication integrates Drupal with a configured SimpleSAMLphp installation. SAML handles the service provider workflow within the Drupal module through LightSAML.

Support and maintenance

Maintained by nathandentzau. Contributions, reproducible bug reports, documentation improvements, and interoperability testing are welcome.

• Report a bug or request a feature.
• View releases.
• Read the changelog.

Report suspected vulnerabilities through Drupal's security issue reporting process. Keep private keys, assertions, session cookies, and personal data out of public issues. Drupal.org displays the project's current security advisory coverage status separately from this description.