Drupal SimpleSAMLphp and Shibboleth federation integration

How Drupal joins a federation through simpleSAMLphp

A university or research team running Drupal usually has to accept logins from a federation's identity providers, so staff and students sign in with their home institution accounts instead of a separate Drupal password. The simpleSAMLphp Authentication module is the Drupal side of that arrangement. It connects Drupal to a SimpleSAMLphp installation, which in turn talks to SAML or Shibboleth identity providers. Drupal does not speak federation protocols directly, so the architecture has two moving parts you must plan, host and maintain: the SimpleSAMLphp service and the Drupal module that trusts it. The module's project page is the starting point for confirming which release fits your Drupal version.

The module's 4.1.0 release supports Drupal ^10 or ^11.3, so the Drupal version you run or plan to run decides whether this path is available without a workaround. Confirm the exact compatibility line on the project page before you commit to a Drupal version, and check it again when you plan a Drupal 12 move, since Drupal 12 is scheduled for the week of December 7, 2026 according to the core release schedule. Also confirm that your federation accepts the SimpleSAMLphp version you will host, because federation operators often publish their own requirements for metadata format and signing.

Licensing does not add a cost line for Drupal itself. Drupal and contributed files on Drupal.org that are derivative works of Drupal are licensed under GPL-2.0-or-later, and there is no paid edition of Drupal. Your recurring costs therefore sit in the work around the platform: hosting the SimpleSAMLphp service, maintaining federation metadata, testing attribute release and keeping both components patched. When you ask a partner for a quote, ask who owns the SimpleSAMLphp host, how metadata renewals are handled and what happens when the federation changes its certificates.

What the Drupal and federation setup needs before work starts

A federation integration depends on several things lining up before any module is configured: a supported Drupal and PHP baseline, a working SimpleSAMLphp host, and an agreement with your federation. Settle these early, because each one can block the others.

Drupal and PHP version

Drupal 10 requires PHP 8.1 or later and Drupal 11 requires PHP 8.3 or later, so the PHP runtime on the web servers sets the upper limit on which Drupal line you can run. The simpleSAMLphp Authentication module 4.1.0 supports Drupal ^10 or ^11.3, so check that the module version you pick matches the Drupal core you plan to install. Confirm which Drupal line your site is on before you pick a module release.

Web server and database

Drupal runs on Apache, Nginx and other web servers, with MariaDB, MySQL, PostgreSQL or SQLite as the database. Pick the combination your operations team already supports and can patch, back up and monitor. The SAML session and user data live in this stack, so the same team that runs the Drupal site should own it.

A working SimpleSAMLphp host

Drupal does not handle SAML itself. The simpleSAMLphp Authentication module hands the login to a SimpleSAMLphp instance that you run, so that host needs its own installation, configuration, patching and backups. Decide whether it runs on the same network as Drupal or in a separate trust zone, and confirm which SimpleSAMLphp version your federation operator expects before you build.

Federation membership and metadata agreements

Joining a campus or research federation usually requires that your institution is a member and that your SAML entity is registered with the federation operator. Expect to sign or accept federation policy, supply your entity metadata and attribute requirements, and agree on which attributes you will release. Ask the operator for their current membership rules and metadata process before scheduling any build work.

TLS certificates and signing keys

The SimpleSAMLphp host and the Drupal site each need TLS certificates that identity providers and browsers trust, and SAML signing and encryption keys that must be published in your metadata. Plan who owns certificate issuance, how renewal is scheduled and what happens when a key rotates, because an expired signing certificate can stop all logins at once.

Network access to identity provider metadata

SimpleSAMLphp must reach the federation or identity provider metadata over the network, and the metadata must be refreshed on a schedule. Confirm which outbound addresses and ports your firewalls or proxies must allow, and whether your security policy permits outbound fetches from the SimpleSAMLphp host. Test this from the production network early, since a blocked metadata fetch often looks like a broken login.

Configuration sequence from SimpleSAMLphp to Drupal login

This sequence takes a Drupal site from an empty SimpleSAMLphp installation to a tested single sign-on flow in which federation members can log in and receive the accounts and roles the institution intends.

Install and configure SimpleSAMLphp as the service provider
The platform team installs SimpleSAMLphp on a host the institution controls, sets the base URL, administrator and secret values, and configures it to act as the service provider that Drupal will talk to through the simplesamlphp_auth module. The Drupal site itself does not hold the SAML protocol logic; SimpleSAMLphp does. Done means the SimpleSAMLphp status and metadata pages load over HTTPS from the address Drupal will use, and the administrative interface is restricted to named staff. Confirm the supported PHP and SimpleSAMLphp versions against the module documentation before installing, because the Drupal side depends on them.
Register the Drupal service provider metadata with the federation
Using the SimpleSAMLphp configuration, the team generates the service provider metadata for the Drupal site, including its entity ID, assertion consumer service endpoint and signing and encryption certificates. The institution's federation operator or identity coordinator then reviews and registers that metadata according to the federation's own process. Ask the federation operator which attributes, assurance levels and certificate formats it requires, since these rules are set by the federation and not by DeployOpen or the module. Done means the federation accepts the registration and the entity appears in its published metadata set.
Load identity provider metadata into SimpleSAMLphp
The team configures SimpleSAMLphp to trust the identity providers the institution needs, typically by loading the federation's aggregate metadata or by adding individual identity provider entries. They confirm the signing certificates, the single sign-on endpoints and the entity IDs match the federation's published values. Metadata validation is the check: the team validates the aggregate file's signature where the federation provides one, and confirms each expected identity provider appears in the SimpleSAMLphp metadata listing. A missing or expired certificate at this point is a common reason for later login failures.
Install simplesamlphp_auth with Composer
A developer adds the simplesamlphp_auth module to the Drupal codebase with Composer so that the version, its dependencies and the SimpleSAMLphp library are recorded in the lock file and deployed through the same release process as the rest of the site. The module's current release notes list which Drupal versions it supports, so the team checks compatibility with the Drupal core version in use before adding it. Done means the module enables cleanly on a non-production copy of the site and the composer lock file is committed to version control.
Configure the SimpleSAMLphp connection in Drupal
In the module settings, the administrator points Drupal at the local SimpleSAMLphp installation, identifies the authentication source to use, and sets the login and logout routes. The team then decides how the Drupal login route behaves: whether SAML login is offered alongside local accounts, whether it is the only path for non-administrators, and which local administrator accounts keep password login as a break-glass option. Document these choices, because they determine who can still sign in if the federation is unavailable. Done means the Drupal login link redirects to the federation login page and returns to the site after authentication.
Set attribute mapping and account creation rules
The team maps the attributes the institution receives from the identity provider, such as the stable unique identifier, username, email address and affiliation, to Drupal user fields. They decide whether accounts are created automatically on first sign-in, whether existing accounts are matched by email or by identifier, and which roles, if any, are assigned from attributes. Restrict role assignment to what the institution has approved, and avoid granting administrator roles from federation attributes. Attribute release and what the identity provider actually sends should be confirmed with the institution's identity team. Done means a test user's Drupal profile shows the expected values and roles after sign-in.
Test login with a non-administrator account
The team signs in with at least one ordinary test account from each relevant affiliation, not an administrator, and confirms that the user lands on the expected page with the expected fields and roles. They also test a failed login, a logout, a session timeout and access to a restricted page, and confirm that the break-glass administrator path still works. Keep the test results and the SimpleSAMLphp and Drupal logs as evidence. Done means every test case passes in a staging environment with the production federation configuration before any change goes to production.

When to use simplesamlphp_auth and when samlauth is simpler

Choose the simpleSAMLphp Authentication module when your organization already runs SimpleSAMLphp as its identity broker, or when a campus or research federation requires that Drupal connect through it. In this model, Drupal talks to a SimpleSAMLphp instance, and that instance handles the SAML or Shibboleth exchange with the identity providers and federation metadata. The module is the integration point, so the identity broker's configuration, certificates and attribute release rules remain the responsibility of the team that operates it.

Shared broker: Drupal joins a broker that other applications already use, so one set of federation agreements serves several systems.
Federation metadata: Metadata refresh, trust anchors and signing certificates are managed on the SimpleSAMLphp side and must stay current.
Attribute release: Attributes such as eduPersonAffiliation reach Drupal only if the broker releases them, so role mapping depends on that configuration.
Operator rules: Federation operators may specify protocols, bindings and attributes that must be confirmed before design starts.
Module support: The 4.1.0 release supports Drupal ^10 or ^11.3, which should be checked against your planned core version.

Before you commit, confirm with your federation operator which protocols and profiles it requires, and whether your broker is already in place.

Mapping federation attributes to Drupal accounts and roles

This table compares common federation attributes with the Drupal field or decision each one drives, so you can see which values make a good account key and which should only inform roles. Confirm every attribute name against your federation's attribute specification and your identity provider's release policy before you configure the mapping in simplesamlphp_auth. The main takeaway is that the username should come from a stable, non-reassignable identifier, while affiliation-based roles should be reviewed and reassigned deliberately.

Attribute	Typical Drupal use	Watch for
eduPersonPrincipalName	Candidate Drupal username or unique account key	Scoped format (user@institution) and reassignment policies vary; confirm uniqueness rules with your federation
eduPersonUniqueId or other persistent identifier	Preferred stable key for matching existing accounts	Not always released by default; request it through attribute release if your institution provides it
mail	Drupal account email address	Can change or be shared; use it for notifications, not as the sole matching key
displayName or cn	Drupal display name on the user profile	Often optional or user-editable at the source; never use it for access decisions
eduPersonAffiliation	Role assignment, for example editor or member	Values such as student, faculty or staff need explicit mapping rules; unmapped values should grant no role
eduPersonScopedAffiliation	Role assignment where institution scope matters	Multi-campus or partner-institution scopes can grant unintended access if not checked
Attribute release agreement	Determines which attributes the IdP sends at all	Missing attributes after go-live usually trace to release policy, not Drupal configuration
Attribute name mapping in the module	Links IdP attribute names to Drupal fields	Names are case-sensitive; test with a real federated login from each user group

Securing federated sign-in on Drupal

Which certificates does a SimpleSAMLphp federation connection need?

Each side of a SAML connection uses certificates, and the Drupal site and the SimpleSAMLphp instance both need a signing key pair that the federation can trust. Encryption certificates are needed where assertions carry sensitive attributes. Store private keys outside the web root with restrictive file permissions, and record which certificate belongs to which entity and which environment. Confirm with your federation operator which algorithms and key lengths its metadata and policy expect, because the federation sets the rules, not the module. Plan a separate key pair for test and production so a test certificate never reaches a live metadata feed.

How often should federation metadata refresh and certificates rotate?

Metadata should refresh automatically from the federation's published feed on a schedule your federation agreement allows, and rotation should follow a documented calendar rather than an emergency process. Ask your federation operator how far ahead they publish new signing certificates and how long old ones remain valid, then set your overlap window to match. Test rotation in a staging environment with a test identity provider before the production change. Monitor certificate expiry dates and alert well before they lapse, because an expired signing certificate typically breaks sign-in for every user at once.

How do I limit attribute release to what each Drupal service needs?

Attribute release should follow a per-service list that names each attribute, the business reason for it, and the Drupal field it populates. Configure the identity provider to release only those attributes to the Drupal service provider entity, and map them in the simpleSAMLphp Authentication module to user fields. Avoid mapping broad identifiers such as national or student numbers into Drupal fields unless the site has a documented purpose for them. Review the list whenever a feature is added. Where a Drupal role depends on a group membership, release the group value only, not the full directory record.

Where do disclosure records and access controls matter for student data?

Where a Drupal site holds student records or identifiers, federation sign-in becomes part of the access chain that FERPA regulates. Under 34 CFR 99.31(a)(1)(ii), institutions must use reasonable methods such as technological access controls so that school officials see only the records in which they have a legitimate educational interest, which makes role mapping and attribute scope part of the compliance design. Under 34 CFR 99.32, institutions must keep a record of each disclosure of personally identifiable information, with the parties and their interests. Confirm with your compliance office which Drupal logs and retention periods satisfy this, and consult counsel on your obligations.

How should the SimpleSAMLphp admin interface be protected?

The SimpleSAMLphp admin interface should never be reachable from the public internet. Restrict it to a management network or VPN, require strong authentication for administrators, and disable the admin pages entirely on hosts that do not need them. Set the admin password hash and secret salt through environment-managed secrets rather than in plain configuration files, and confirm the configuration key names against the version you run. Log administrative access and forward those logs to a central system. Include the admin path in your external scan scope so drift is caught.

Which session and cookie settings matter for SimpleSAMLphp and Drupal?

Three settings matter most: cookies should be marked Secure and HttpOnly, the session lifetime should match your institution's policy, and the SameSite behavior should be tested against the browsers your users run. SimpleSAMLphp keeps its session store and cookie settings in its own configuration, and Drupal keeps its session settings separately, so review both and confirm the exact keys for your installed versions. Session storage should be shared across web nodes if you run more than one, or users will be logged out unpredictably. Test single logout behavior, because a session that survives on one side only creates confusing access states.

How do we keep Drupal and contributed modules patched on time?

Subscribe to Drupal Security Team advisories, which carry CVE identifiers and risk scores, and plan a patch process around the Wednesday security release window. Core bugfix releases arrive on the first Wednesday of each month, and security releases on the third Wednesday, so a standing monthly routine covers most work. Include the simpleSAMLphp Authentication module and the SimpleSAMLphp library itself in that routine, since they are not updated by core releases. Keep a tested staging copy so updates can be verified before production. Confirm your internal patch deadlines with your security team, as they vary by policy.

Who owns federation security work, and what does a partner cover?

Ownership usually splits between the federation operator, which publishes metadata and policy, the identity team, which runs the identity provider and releases attributes, and the Drupal team, which owns the module, role mapping and updates. A DeployOpen engagement for this work is fixed-scope and agreed in writing, and it can cover certificate and metadata procedures, attribute review, admin hardening, session settings and a patch routine. It does not issue audit reports or certifications, so independent auditors remain responsible for any formal assessment. Ongoing patching and monitoring can be arranged as a retainer.

Student data rules that shape the design

If your institution receives US Department of Education funds, FERPA shapes who can see student records in a Drupal site that federated sign-in exposes. The cards below cover the decisions that follow from that rule, to bring to your compliance and legal advisers rather than treat as legal advice.

FERPA scope and institutional status

FERPA's regulations in 34 CFR Part 99 apply to educational agencies and institutions that receive funds under a program administered by the US Secretary of Education. Confirm with your registrar or counsel whether the Drupal site will hold education records at all, or only public content, event sign-ups and staff pages. That answer decides how much of the rest of this section applies to your build.

Contractors as school officials

A contractor such as DeployOpen may receive education records only as a school official, under the conditions in 34 CFR 99.31(a)(1)(i)(B). The work must be something the institution would otherwise assign to its own employees, the institution must keep direct control over the use and maintenance of the records, and redisclosure must follow the limits in 99.33(a). Put these conditions into the statement of work and the data processing terms before access is granted.

Limiting school officials to needed records

Institutions must use reasonable methods, such as physical or technological access controls, so that school officials see only the education records in which they have a legitimate educational interest (34 CFR 99.31(a)(1)(ii)). In a federated Drupal site, this means mapping federation attributes to roles that expose only the fields and views each person needs, and testing that a staff account cannot reach another department's records through views, search or the REST and JSON:API endpoints.

Disclosure logging for access requests

FERPA requires institutions to record each request for access to, and each disclosure of, personally identifiable information from a student's education records, including the parties involved and their legitimate interests, and to keep that record for as long as the records are kept (34 CFR 99.32). Decide early whether the Drupal site or the institution's systems will produce this log, and confirm that audit entries from the site, the SimpleSAMLphp logs and the web server can be retained and searched for that period.

Records access timelines and enforcement

An institution must comply with a parent's or eligible student's request to inspect education records within a reasonable period, and not more than 45 days after receiving it (34 CFR 99.10(b)). Non-compliance can lead the Secretary to withhold payments, issue a cease and desist order or end funding eligibility (34 CFR 99.67). Ask your compliance team how records held in Drupal will be located and produced within that window, and who owns that process.

Common federation login failures and their causes

This table lists the login failures we see most often when Drupal sits behind SimpleSAMLphp in a federation, with the likely cause and the first thing to check for each. Work down the rows in order, because metadata and entity ID problems are usually the cheapest to rule out before you inspect certificates or attribute release.

Failure	Likely cause	Check first
Metadata mismatch	The federation metadata or IdP metadata loaded by SimpleSAMLphp no longer matches what the other party published, often after a metadata refresh or a partner change.	Compare the copy of metadata in your SimpleSAMLphp configuration with the current federation feed and refresh it.
Expired certificate	A signing or encryption certificate in the SP or IdP metadata has passed its validity date, so assertions fail signature checks.	Check the validity dates on the certificates in both metadata sets and confirm which certificate each side is using.
Missing attributes in the assertion	The identity provider does not release an attribute the Drupal site maps to a username, email or role, usually because attribute release policy was never agreed for this service.	Review the attributes in the assertion and the attribute mapping in the simplesamlphp_auth settings, then confirm the release policy with the IdP operator.
Clock skew	The server clocks on the SP or IdP drift apart, so assertions look expired or not yet valid even when the certificates are correct.	Confirm that NTP synchronization is running on both the Drupal web servers and the SimpleSAMLphp host.
Wrong entity ID	The entity ID configured for the service provider differs from the one registered in the federation, so the IdP cannot match the request.	Compare the entity ID in the SimpleSAMLphp SP configuration and in the federation registration, character for character.
Duplicate accounts from changed usernames	The IdP now sends a different unique identifier or username for the same person, so Drupal creates a second account instead of linking to the existing one.	Confirm which attribute the site uses as the stable identifier and check for accounts that share an email address.
Redirect URL errors	The assertion consumer service URL or the return URL does not match the registered endpoint, often because the site moved to a new hostname or path, or sits behind a proxy that changes the scheme.	Compare the registered ACS and logout URLs with the public URLs Drupal generates, including https and the path prefix.

How to test federation login before go-live

Testing federation login before go-live means proving three things on the real Drupal site: that users from several member institutions can sign in, that users who should be refused are refused, and that an administrator can still get in if the federation path fails. Start by building a pilot group of test accounts from at least several affiliations in the federation, covering different identity providers, attribute sets and roles such as content editor and site administrator. Confirm with the federation operator whether it provides a test federation or operator test identity providers, and whether those accounts can be used against your entity ID before you request production metadata. Record which attributes each test account releases, because the Drupal side can only map what the identity provider sends.

Negative tests matter as much as positive ones. Create accounts that lack the attribute your site uses to grant access, such as a missing affiliation or entitlement value, and confirm that the simplesamlphp_auth login is denied or routed to a message you have approved, rather than creating an account with default roles. Repeat the check with an account whose attribute value is present but not on your allow list. Then test logout and session expiry: sign out from Drupal and confirm whether the IdP session also ends, open a second browser to confirm single logout behaves as your federation policy expects, and let an idle session expire to confirm the user is asked to authenticate again. Verify the results against your own session and cookie settings, since these depend on your configuration and the federation's guidance.

Plan the rollback before launch. Keep a local administrator account that does not depend on SAML, protected with multi-factor authentication where your environment supports it, and test that it works from the same network path your administrators will use. Document how to disable federation login, typically by turning off the SimpleSAMLphp authentication settings in Drupal or by restoring the previous login configuration from version control, and rehearse that step in staging. Confirm with your security team who is authorized to make the change and how it is logged. Vendor-specific details of these steps depend on the module release and your Drupal version, so verify them against the module documentation for the version you deploy.

Questions buyers ask about Drupal federation integration

What drives the effort of a SimpleSAMLphp federation integration in Drupal?

The main drivers are how many identity providers you connect, how complex the attribute release is, whether SimpleSAMLphp already runs in your environment, and whether the Drupal estate is a single site or a multisite. Each additional identity provider adds metadata exchange, attribute mapping and login testing. A Drupal site that already trusts a SimpleSAMLphp instance usually needs less setup than one starting from nothing. Multisite layouts multiply the configuration and the test matrix, because each site may need its own SP entity, login path and role rules. Ask any partner to break the estimate down by these four drivers before you compare quotes.

What does our university team need to supply before the work starts?

Your team supplies three things: signed metadata or registration agreements with the federation operator, written attribute decisions, and test accounts on each identity provider. The attribute decisions cover which attributes Drupal may receive, which must be present for a login to succeed, and how each maps to a Drupal user field or role. Test accounts should include staff, students and any affiliate or guest population, so that edge cases are checked before launch. Missing or late attribute decisions are the most common reason integration timelines slip, so agree on them in the scope document.

Can our internal staff build the federation integration alone?

Yes, if you have an engineer who is comfortable with SAML concepts, PHP configuration and Drupal's user and role model, and if someone can work with the federation operator on metadata and attribute release. The work is not large in code, but it depends on accurate trust configuration and on understanding what the identity provider will release. Teams that build in-house often underestimate the testing of failed logins, attribute gaps and account linking for existing users. A partner is useful when the team lacks SAML experience, when several identity providers are involved, or when the go-live window is fixed.

How long does federation onboarding take with each federation operator?

The duration depends mainly on the federation operator's own process, not on the Drupal build. Operators differ in how they review applications, publish metadata, approve entity registration and schedule changes, so ask each operator for its current onboarding steps and typical turnaround in writing. Your institution's internal approvals for attribute release and data sharing can also be the longest step. Plan the Drupal work to run in parallel with these approvals, and confirm the timing with the federation operator before you commit to a launch date.

Which attributes should we release to Drupal, and who decides?

Release only the attributes Drupal needs to create accounts, assign roles and show the correct content. Typical choices include a stable unique identifier, an institutional email address and a membership or affiliation value, but the exact attribute names depend on your federation and identity provider. The decision should be made by your identity team with input from data protection and the owners of the Drupal site. Record each attribute, its purpose and its retention in the scope document. Confirm the attribute names and release rules with your identity provider and federation operator, because they control what is actually sent.

Does the work change if we already run SimpleSAMLphp for other applications?

It usually shortens the work. If SimpleSAMLphp already acts as your proxy or service provider hub, the Drupal side can often reuse existing metadata, authentication sources and attribute processing, and the new work focuses on the simpleSAMLphp Authentication module and Drupal role mapping. Check the version of SimpleSAMLphp you run against the module's supported requirements, and review any custom authentication modules that could conflict. Changing a shared SimpleSAMLphp configuration can affect other applications, so the Drupal change should be tested in a staging environment first.

Would the simpleSAMLphp_auth module or samlauth be the simpler choice?

If you already run SimpleSAMLphp and need Shibboleth or federation metadata handling, the simpleSAMLphp Authentication module is the natural choice. If you need Drupal to act directly as a SAML service provider without a SimpleSAMLphp layer, the SAML Authentication module (samlauth) is often simpler to operate. Compare the two against your federation requirements, your existing identity infrastructure and your team's skills, and confirm module support against the current Drupal version before you decide.

How DeployOpen scopes and supports federation integrations

DeployOpen plans, builds, documents and supports self-hosted Drupal sites inside the client's own infrastructure, including the SimpleSAMLphp connection to a campus or research federation. Engagements are fixed-scope, with the federation requirements, attribute rules and handover agreed in writing before the build starts.

How we scope

Written scope lists the federation, the Drupal version, the SimpleSAMLphp deployment and the sites that will sign in.
We record which attributes the identity provider must release, which Drupal fields they map to and who approves them.
Scope names the environments, the test identity provider and the sign-in paths that must work before go-live.

How we build

We configure simplesamlphp_auth against the agreed SimpleSAMLphp instance, metadata and certificates in your environment.
Account creation, role mapping and login redirects are built and tested with real federation test accounts and logged failures.
Custom code, where needed, is kept in a contained module so later Drupal upgrades stay straightforward to plan.

How we hand over

Deliverables include configuration records, metadata locations, attribute maps and a test script your team can rerun.
We document certificate renewal, metadata refresh and rollback steps so your administrators can operate the integration.
Knowledge transfer sessions cover the sign-in flow, the logs to check and the federation contacts to involve.

How we support

Ongoing support, module updates and periodic testing are available as a retainer after handover.
Retainers can cover Drupal core and module patching, including security releases your team needs to apply quickly.
Confirm with your federation operator and your own compliance owners which changes must be reviewed before they are applied.

Drupal with SimpleSAMLphp and Shibboleth federations