SAML SSO - Service Provider
Enable SAML 2.0 Single Sign-On (SSO) for Drupal sites by allowing users to authenticate through external SAML 2.0 Identity Providers such as Azure AD, Okta, ADFS, Google Apps, and others.
miniorange_saml
Install
composer require 'drupal/miniorange_saml:^3.1'
Overview
The miniOrange SAML Service Provider module enables your Drupal site to act as a SAML 2.0 Service Provider (SP), allowing users to authenticate through external SAML 2.0 compliant Identity Providers (IdP). This provides secure Single Sign-On (SSO) functionality without requiring users to maintain separate credentials for your Drupal site.
The module supports a wide range of Identity Providers including Microsoft Azure AD, ADFS, Okta, Salesforce, Google Apps (Google Workspace), Shibboleth, SimpleSAMLphp, OpenAM, Centrify, PingOne, PingFederate, RSA, IBM, Oracle, OneLogin, Bitium, Auth0, and many others. It provides comprehensive configuration options for setting up the trust relationship between your Drupal site and the IdP.
Key SAML 2.0 features include metadata exchange (both upload and URL-based), X.509 certificate management, NameID format configuration, and ACS (Assertion Consumer Service) endpoint handling. The module automatically creates user accounts for new SSO users and can map IdP attributes to Drupal user fields.
Features
- SAML 2.0 compliant Service Provider implementation for Drupal
- Support for multiple Identity Providers including Azure AD, Okta, ADFS, Google Apps, Salesforce, Shibboleth, and more
- Automatic IdP metadata configuration via URL or XML file upload
- SP metadata generation and download in XML format
- Test Configuration feature to validate SSO setup before going live
- Display SAML Request and Response for debugging purposes
- Automatic user creation for first-time SSO users
- Role mapping to assign default Drupal roles to SSO users (basic in free version)
- Login link integration on standard Drupal login form and custom forms
- X.509 certificate management with character encoding support
- Customizable SP Entity ID and Base URL
- Request 7-day trial for premium features directly from admin UI
Use Cases
Enterprise Single Sign-On with Azure AD
Organizations using Microsoft 365 can enable their employees to log into the Drupal site using their existing Microsoft credentials. The module acts as a Service Provider connecting to Azure AD (Entra ID) as the Identity Provider. Users click 'Login using Azure AD' on the Drupal login page and are redirected to Microsoft for authentication. After successful login, they are automatically logged into Drupal with their user account created or updated based on SAML attributes.
Educational Institution SSO with Shibboleth
Universities and research institutions often use Shibboleth for federated identity management. This module allows the Drupal site to participate in the institution's SSO infrastructure, enabling students and faculty to access the site using their institutional credentials without creating separate accounts.
Multi-Tenant SaaS Application with Multiple IdPs
A Drupal-based SaaS platform serving multiple enterprise customers can use the premium version to configure different Identity Providers for each customer. Domain-based SSO routing directs users to their organization's IdP based on their email domain or the subdomain they access.
Intranet Portal with Forced Authentication
Internal company portals can enable forced authentication to require all users to log in via the corporate IdP. Anonymous access is blocked, and users are automatically redirected to the IdP when accessing any page. This ensures only authenticated employees can access company resources.
Customer Portal with Just-In-Time Provisioning
Customer-facing portals can allow customers to log in using their own identity providers (like Okta or OneLogin configured by the customer's IT department). The module automatically creates Drupal user accounts on first login, assigning appropriate roles based on SAML attributes from the IdP.
Testing SSO Configuration
Before enabling SSO for all users, administrators can use the Test Configuration feature to verify the integration works correctly. This opens a popup window that performs the complete SSO flow and displays the SAML response, including all attributes received from the IdP. The SAML Request and SAML Response buttons help troubleshoot configuration issues.
Tips
- Always use the Test Configuration button to verify your SSO setup before enabling it for all users
- Download the SP metadata XML file from the Service Provider Metadata tab and import it into your IdP for easier configuration
- Enable Character Encoding if you experience certificate validation issues, especially with certificates from non-standard IdPs
- Use the SAML Request and SAML Response buttons for detailed debugging - these show the exact XML being sent and received
- Configure a custom SP Entity ID if you plan to use the same IdP with multiple Drupal sites to ensure unique identification
- Keep a backup of your IdP's X.509 certificate and monitor for certificate rotation to avoid service disruptions
- For production environments, request a trial of premium features to evaluate advanced functionality like attribute mapping and role provisioning
- The /samllogin URL can be used directly in navigation menus or as a login button for a cleaner user experience
Technical Details
Admin Pages 8
/admin/config/people/miniorange_saml/idp_setup
Displays the Service Provider metadata that must be configured in your Identity Provider. This page shows all the values needed to set up the trust relationship from the IdP side, including the SP Entity ID, ACS URL, Audience URI, and downloadable XML metadata.
/admin/config/people/miniorange_saml/sp_setup
Configure your Identity Provider settings. This is where you enter the IdP metadata including Entity ID, Login URL, and X.509 certificate. Supports both manual configuration and automatic metadata import.
/admin/config/people/miniorange_saml/user_provisioning
Configure automated user provisioning and synchronization capabilities. This tab promotes the User Provisioning bundle plan which enables SCIM-based or API-based user synchronization with various Identity Providers.
/admin/config/people/miniorange_saml/Mapping
Configure how SAML attributes from the Identity Provider are mapped to Drupal user fields and roles. This includes basic role mapping (free) and advanced attribute/custom role mapping (premium).
/admin/config/people/miniorange_saml/signon_settings
Configure sign-in behavior including user lookup method, redirect URLs, auto-creation settings, forced authentication, and domain-based restrictions. Most features are premium.
/admin/config/people/miniorange_saml/AdvanceSettings
Import and export module configuration, and view promotional information about related miniOrange modules like User Provisioning (SCIM).
/admin/config/people/miniorange_saml/Licensing
View available licensing plans and premium features. Compare Standard, Premium, and Enterprise plans with their respective features and pricing.
/admin/config/people/miniorange_saml/MiniorageSupport
Submit support queries, feature requests, or demo requests to the miniOrange support team.
Permissions 1
Hooks 3
hook_form_alter
Adds SAML SSO login link to the standard Drupal login form (user_login_form), login block (user_login_block), and any custom forms configured in the module settings.
hook_help
Provides help documentation for the module accessible at admin/help/miniorange_saml, including configuration steps, setup guide links, and FAQ links.
hook_theme
Registers three Twig templates used by the module: mo-saml-request-trial for trial request forms, mo-saml-licensing-new for the licensing page, and mo-saml-send-ticket-info for support ticket confirmation.
Troubleshooting 7
The Audience URI configured in your Identity Provider does not match the SP Entity ID. Check the Service Provider Metadata tab for the correct Audience URI value and update your IdP configuration. The Audience URI should match the SP Entity ID exactly.
The IdP Entity ID configured in the module does not match what the IdP sends in the SAML response. Use the Test Configuration to see the expected Entity ID in the error message and update the 'IdP Entity ID or Issuer' field in Service Provider Setup.
The X.509 certificate configured in the module does not match the certificate used by the IdP to sign responses. Obtain the current certificate from your IdP and update the X.509 Certificate field. If your IdP rotates certificates, ensure you have the latest one.
Verify that 'Enable login with SAML' is checked in Service Provider Setup and that the IdP configuration is complete (IdP Name, Entity ID, and Login URL are all configured). Clear Drupal cache after making changes.
The user account in Drupal has been blocked. Go to People and unblock the user, or check if automated blocking rules are in place that may be affecting new SSO users.
Configure your Identity Provider to release the required attributes in the SAML assertion. At minimum, ensure NameID or the configured email/username attributes are being sent. Use the Test Configuration feature to view what attributes are being received.
Ensure all required fields are filled: Identity Provider Name, IdP Entity ID or Issuer, and SAML Login URL are mandatory. The Login URL must be a valid URL format. Check that the X.509 certificate is properly formatted with BEGIN/END CERTIFICATE markers.
Security Notes 8
- The module verifies SAML response signatures using the configured X.509 certificate to prevent tampering
- SAML assertions have a time-based validity window (2 minutes allowance) to prevent replay attacks
- Destination URL validation ensures SAML responses are only accepted for the correct Drupal site
- User passwords are automatically generated for SSO users and not exposed - authentication is handled by the IdP
- The X.509 certificate should be obtained securely from your IdP administrator, not from untrusted sources
- Consider enabling HTTPS for your Drupal site to protect SAML communications in transit
- Premium features include backdoor login option - use cautiously as it provides an alternate authentication path
- The module does not store or transmit user credentials - all authentication occurs at the Identity Provider