Implementing Single Sign-On for Drupal with SAML
Single sign-on (SSO) lets people access a Drupal website through an identity provider they already use, such as Microsoft Entra ID, Okta, Google Workspace, or an organisation’s central university directory. Security Assertion Markup Language (SAML) connects Drupal to that provider so users can authenticate without maintaining a separate Drupal password.
For Australian organisations, this approach is useful when a website serves staff, members, students, contractors, or public-sector teams across several systems. A Drupal intranet in Sydney, a council portal in Brisbane, or a higher education site in Melbourne can use the same identity controls as the organisation’s other applications, including multi-factor authentication and staff offboarding.
Why SAML Suits Drupal Websites
SAML uses a trust relationship between two systems. Drupal acts as the service provider (SP), while the identity provider (IdP) authenticates the user and sends Drupal a signed assertion. The assertion usually contains an identifier such as an email address, along with optional attributes for a display name, department, or group membership.
When an unauthenticated visitor opens a protected Drupal page, Drupal redirects them to the IdP. After a successful sign-in, the IdP posts a SAML response to Drupal’s Assertion Consumer Service (ACS) endpoint. Drupal validates the digital signature, checks the response conditions, and creates a local session.
This arrangement moves password policy and multi-factor authentication away from Drupal. An organisation can enforce Microsoft Authenticator, hardware security keys, conditional access, or geographic restrictions in one place. If an employee leaves a Perth office or a contractor’s access ends, disabling the central account can prevent further access to connected websites.
SAML is especially appropriate when the website must integrate with an established enterprise directory. It may be more infrastructure than needed for a small public blog, where anonymous access and a few local administrator accounts are sufficient. For larger teams, however, centralised identity management usually reduces account duplication and support requests.
Select The Drupal SAML Module
Start by checking the Drupal core version, PHP version, hosting restrictions, and the current maintenance status of candidate modules. Common approaches include the SAML Authentication module, an integration based on SimpleSAMLphp, and commercial Drupal SAML connectors. The correct choice depends on whether the site needs a straightforward login flow, complex attribute mapping, multiple identity providers, or vendor support.
A module that uses the OneLogin PHP SAML toolkit can be practical for a single service provider configuration. SimpleSAMLphp offers a broader identity federation platform and can be useful when several applications share the same authentication layer, though it introduces additional server configuration. Commercial modules often provide guided configuration, support for advanced mappings, and administrative interfaces that reduce manual XML editing.
Install the selected module with Composer rather than copying files into the modules directory. A typical process resembles:
composer require drupal/samlauth
drush en samlauth -y
drush cr
The package name and compatibility can change, so verify the module’s Drupal.org release information before running the command. Test the module in a non-production environment first, particularly if the site runs on managed hosting or a platform such as Acquia.
Create a break-glass administrator account before enabling mandatory SAML login. Store its credentials securely and restrict its use. This account is important if the identity provider becomes unavailable, metadata expires, or an incorrect role mapping locks out normal administrators.
Prepare The Identity Provider
In the identity provider, create a SAML enterprise application for the Drupal site. The labels vary between products, but you will normally enter an Entity ID, an ACS URL, and sometimes a Single Logout URL. The Entity ID identifies Drupal as a trusted service provider; it is not necessarily the public website URL.
The ACS URL must match Drupal’s configured endpoint exactly, including the protocol, hostname, path, and trailing slash behaviour. For example, a module might use a URL similar to:
https://portal.example.com/saml/acs
Use HTTPS everywhere, including staging environments with realistic test accounts. Australian organisations handling personal information should treat the SAML response as sensitive because it can contain identity data. Align the design with the Privacy Act 1988, internal privacy policies, and any contractual obligations relating to customer or member information.
Download the IdP metadata XML when possible instead of manually copying every setting. Metadata typically contains the issuer, login endpoint, logout endpoint, and signing certificate. If the provider requires Drupal metadata, export it from the Drupal module and upload it to the IdP. Keep a record of the metadata source, certificate expiry date, and the person responsible for renewing it.
Choose a stable identifier for account matching. An immutable directory ID is safer than an email address because email domains and addresses can change. If the module only supports email matching, ensure the IdP sends a consistent, verified email claim and document the consequences of an address change.
Configure Assertions And Account Mapping
SAML attributes are the bridge between the identity provider and Drupal. A basic assertion might include NameID, mail, givenName, sn, and groups. Drupal can use these values to create an account, update a name, assign a role, or decide whether a person is allowed to sign in.
Map only the attributes the site needs. A community website may need an email address and display name, while an internal knowledge base might also require a department or employment status. Avoid importing a complete directory profile into Drupal when a small set of claims will do.
Role mapping requires particular care. A directory group such as Drupal-Editors can map to Drupal’s Content editor role, while Drupal-Administrators maps to a tightly controlled administrative role. Do not map broad groups such as “All Employees” to permissions that allow content publishing, configuration changes, or user administration.
Decide how Drupal handles users who are removed from a group. Some integrations update roles at login but do not automatically delete accounts. That is usually preferable because it preserves authorship and audit history, but it means access control must be tested carefully. A user who remains in Drupal may still be able to access content if the module does not remove the relevant role.
Disable automatic account creation if every account requires approval. If just-in-time provisioning is enabled, restrict it to a verified email domain or an explicit IdP group. For a Drupal site used by a local government team in Adelaide, for example, allowing any person with a matching public email domain could create an unintended access path.
Test The Full Authentication Flow
Test SAML with separate accounts for an administrator, editor, ordinary authenticated user, unauthorised user, and a person whose directory group has recently changed. Use a private browser window for each test so existing cookies do not hide errors. Confirm that the login link redirects to the intended IdP tenant and that Drupal returns the user to the original protected page.
Inspect the SAML response when troubleshooting, but do so safely. Browser tools such as SAML-tracer can show whether the issuer, audience, recipient, timestamps, and attributes are correct. Never paste production assertions, private keys, or personal information into public debugging tools. Redact email addresses and identifiers in support tickets.
Common failures include an incorrect ACS URL, a mismatched Entity ID, an expired signing certificate, and a clock difference between Drupal’s server and the IdP. SAML conditions are time-sensitive, so configure reliable NTP synchronisation and use only a small clock-skew allowance. A five-minute tolerance may help with minor drift, but it should not conceal a badly configured server clock.
Test logout separately from login. Single Logout is inconsistently implemented across providers and applications, and ending the Drupal session may not end the IdP session. Tell users what logout means in the selected configuration. Also test reverse proxies, CDN caching, HTTP-to-HTTPS redirects, and multiple domains, since these can alter the URL Drupal presents to the identity provider.
Compare Common Integration Approaches
The best option depends on the site’s operational model rather than on the SAML protocol alone. A small Drupal installation with one identity provider may benefit from a focused module, while a group managing several applications may prefer a shared SimpleSAMLphp service. A commercial connector can be worthwhile when the organisation needs vendor assistance or complex enterprise features.
| Approach | Suitable For | Strengths | Considerations |
|---|---|---|---|
| Drupal SAML Authentication module | One Drupal site and one main IdP | Direct Drupal integration, familiar administration, lower infrastructure overhead | Check current Drupal and PHP compatibility; advanced federation may require extra work |
| SimpleSAMLphp integration | Several applications or complex federation | Mature platform, flexible provider configuration, reusable identity layer | More server maintenance, separate configuration, and greater operational complexity |
| Commercial Drupal SAML connector | Organisations needing guided setup or support | Wizard-based configuration, attribute mapping, vendor assistance, enterprise options | Licence cost and dependence on vendor release timing |
| Custom SAML integration | Specialist platforms with unusual requirements | Maximum control over claims and workflows | Higher security and maintenance burden; requires strong PHP and SAML expertise |
| OAuth or OpenID Connect | Newer cloud identity platforms and modern application stacks | Often simpler APIs, strong support for mobile and modern applications | Not a direct SAML implementation; provider and Drupal module capabilities must be checked |
SAML metadata and certificates should be treated as production dependencies. Set calendar reminders well before certificate expiry and keep a tested rotation procedure. Entra ID and other providers may support overlapping certificates during a transition, which allows the Drupal side to be updated without an abrupt outage.
Monitor authentication failures in Drupal, the identity provider, and the reverse proxy. Record useful event details without storing full assertions or sensitive tokens. For an organisation operating across Brisbane, Melbourne, and Perth, agree on the support window and time zone used in alerts; a certificate warning arriving during an east-coast public holiday can otherwise become an avoidable outage.
Operate SSO Securely In Drupal
- Keep a tested local break-glass administrator account, protect it with a strong unique credential, and monitor every use.
- Restrict SAML role mappings to dedicated identity-provider groups with clear ownership and regular membership reviews.
- Verify metadata, signing certificates, ACS URLs, and clock synchronisation after every Drupal, proxy, or identity-provider change.
- Apply Drupal security updates, module updates, and PHP updates through a staging workflow before production deployment.
- Document login, logout, account linking, certificate rotation, and emergency rollback procedures for the support team.
A successful Drupal SSO deployment is more than a working redirect. It is a controlled identity boundary with explicit claims, limited permissions, reliable monitoring, and a recovery path when the external provider is unavailable. With those safeguards in place, SAML can give Australian Drupal teams a consistent sign-in experience while keeping authentication aligned with the organisation’s existing security practices.