Skip to main content
Skip table of contents

Drupal SAML Integration

This document explains how to implement Monosign with Drupal application. It covers Single Sign-On. Before you continue, starting with Drupal’s Single Sign-On page is better on this page.

This configuration is done with Drupal 10.3.0. If your Drupal version is different please check Drupal documentation.

Based on the documentation and the modules, the SAML integration module works with all versions of the Drupal application.

Monofor has no responsibility to do Drupal configurations. If you need support please contact Drupal Support Services.

📑 Instructions

This documentation contains 4 main steps for integration.

  1. Creating an application on Monosign

  2. Configuration Single Sign-On for Drupal

  3. Assign a user to the Drupal application

  4. Sign In Test

1- Creating an Application on Monosign

Create your application on Monosign and configure your access policy. Once you create, click “Keys” and add a new Access Key for SAML Key for access.

We will need this information while we configure the Drupal application.

Creating Access Key.png

Creating Access Key in Monosign Drupal Application

Creating Access Key SAML.png

Deciding Access Key as SAML and Expiration Date

Property

Value

Options

Key Type

SAML

Rest API, OAuth 2.0, JWT, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server

Expiration

Lifetime

Lifetime or Specific Date/Time - By Default Lifetime is Enabled.

Configuration details for the Drupal application are provided as follows:

SAML Key Details.png

SAML Access Key Details

The third step will use information in the “SAML Access Key Details“ section to configure the Drupal SAML settings.

SAMLConfigurationOnMonosign.png

SAML Configuration on Monosign

ACS (Assertion Consumer Url), Entity Id, Logout URL and Extra Attributes will be configured later while configuring the Configuration Single Sign-On for Drupal step.

Property

Value

Description

UserName Format

Monosign UserName

Defines the UserName format such as Monosign UserName, sAMAccountName, UserprincipalName, Email etc.

Assertion Consumer Url

https://<DRUPAL_IP_OR_FQDN>/saml/metadata

The URL where the SAML assertion is sent by the IdP. Replace <DRUPAL_IP_OR_FQDN> with the actual IP address or fully qualified domain name of your Drupal site.

Entity Id

drupal

A unique identifier for the Drupal service provider. This is used to identify Drupal to the IdP.

Name Id

UserName

Specifies the attribute used as the NameID in the SAML assertion, which is the unique identifier for the user. Here, it is set to "UserName".

Logout URL

https://<DRUPAL_IP_OR_FQDN>/saml/sls

The URL for the Single Logout Service (SLS) endpoint. This is where the user is redirected for logging out.

Extra Attribute

Attribute: UserName

Value: {{UserName}}

Attribute: Email

Value: {{Email}}

Attribute: eduPersonTargetedID

Value: {{Email}}

Additional attributes that are sent in the SAML assertion.

Signing Algorithm

System Default (SHA 256)

The algorithm used to sign the SAML assertions. Here, it is set to the system default, which is SHA 256.

Enable Group Mapping

YES

Indicates whether group mapping is enabled. When enabled, user groups in the IdP can be mapped to Drupal user roles.

Group Mapping Attribute

Groups

The attribute used for group mapping. This specifies which attribute in the SAML assertion contains the group information.

To ensure that the application has access to user groups, follow these steps:

  1. If the application hasn't been configured yet, click the “Edit” option for the application.

  2. In the application settings, navigate to the “Source, Provider, and Profile” tab.

  3. Configure the “User Access Type“ and “User Group Access Type” as “Only Assigned Users.”

Configuring this setting will allow the application to be accessed by user groups when users sign in.

ApplicationAccess.png

Application Access Configuration

Property

Description

Options

User Access Type

Defines which Users will access this application.

Only Assigned Users
All Users

User Group Access Type

Defines the application’s user group access

Only Assigned Users
Assigned Users and Defined Sources
All Users

Profile Access Type

Defines the Application’s user’s profile access

Restricted - Only restricted user profile attributes
All - All user profile attributes

2- Configuration Single Sign-On for Drupal

As highlighted at the beginning of the document, please check out Drupal’s SAML SSO configuration page first.

Drupal configuration contains below steps:

  1. Install SAML Authentication module

  2. Configure Login / Logout step

  3. Configure Service Provider step

  4. Configure Identity Provider step

  5. Configure User Info and Syncing step

  6. Configure SAML Message Construction step

  7. Configure SAML Message Validation step

a. Install SAML Authentication Module

Drupal does not support authentication via SAML without a SAML Authentication module in the base. In this case, the Drupal Admin user needs to install the “SAML Authentication“ module for Drupal on the https://www.drupal.org/project/samlauth.

The module installation process can be different for every Drupal application and the installation process is the responsibility of the admin user.

The example module installation process is for Drupal with the composer.

After downloading “SAML Authentication“ module fromhttps://www.drupal.org/project/samlauthpage, you should go to the Admin page for the Drupal application.

Please navigate to the Manage → Extend page on the Admin UI and install the module as shown.

Install-SAMLAuthenticationModule-Drupal.png

Installing the SAML Authentication Module

After installing the module, please navigate to the “Configuration“ page and click the “SAML authentication“ module to configure the SAML settings as shown.

Configuration-SAML-Page.png

Navigating to the SAML Authentication Configuration Page

b. Configure Login / Logout

The section configures the login/logout process when users try to log in to Drupal through Monosign.

loginlogoutsection.png

Login/Logout Configuration

Property

Value

Description

Login menu item title (Mandatory)

Login with Monosign

The configuration changes the default login URL to the SAML URL so users can log in through Monosign.

The SAML Login URL: https://<domain>/saml/login

Logout menu item title (Mandatory)

Logout

The configuration changes the default logout URL to the SAML URL so users can log out through Monosign.

The SAML Logout URL: https://<domain>/saml/logout

Roles allowed to use Drupal login also when linked to a SAML login (Optional)

Authenticated user - Not checked

Content editor - Not Checked

Administrator - Checked

Users who have previously logged in through the SAML Identity Provider can only use the standard Drupal login method if they have one of the roles selected here. Drupal users who have never logged in through the IdP are not affected by this restriction.

It is best if you check the “Administrator“. In some cases, the admin account needs login to Drupal without Monosign.

Tell disallowed users they must log in using SAML (Optional)

Not checked

The users were forced to log in to Drupal through SAML. If not checked, we show the generic "Unrecognized username or password" message to users who cannot use the standard Drupal login method. This prevents disclosing information about whether the account name exists but is untrue / potentially confusing.

c. Configure Service Provider

This page configures the necessary details for enabling SAML authentication in Drupal, allowing it to interact with an IdP for single sign-on (SSO) purposes.

serviceprovidersection.png

Service Provider Configuration

Provide the below information. Entity ID, Assertion Consumer Service and Single Logout Service can be obtained from Drupal Application Keys on Monosign. This is explained in this step.

Property

Value

Description

Metadata URL

https://<DRUPAL_IP_OR_FQDN>/saml/metadata

Provides the URL where the SP's metadata is available. The URL will be used in Monosign.

Assertion Consumer Service

https://<DRUPAL_IP_OR_FQDN>/saml/acs

The endpoint where the IdP sends SAML responses. The URL will be used in Monosign.

Single Logout Service

https://<DRUPAL_IP_OR_FQDN>/saml/logout

The endpoint for handling logout requests. The URL will be used in Monosign.

Entity ID

<anything_related_to_drupal_or_monosign>

Example: drupal

The unique identifier for the SP.

The Entity ID information will be used in Monosign.

Type of values to save for the key/certificate

Configuration

Allows saving key and certificate information in the configuration.

Private Key

<private_key_of_the_certificate_used_in_drupal>

It contains the private key for signing SAML requests, which should be kept secure.

X.509 Certificate

<private_key_of_the_certificate_used_in_drupal>

The public certificate corresponding to the private key, is used by the IdP to verify SAML request signatures.

Please navigate to the Drupal application on the Monosign to set the configuration on the SAML Key settings. The SAML key is created in the first step.

d. Configure Identity Provider

This page configures the necessary details for the Identity Provider (IdP) in the SAML authentication setup, enabling the Drupal application to authenticate users via the specified IdP.

identityprovidersection.png

Identity Provider Configuration

Property

Value

Description

Entity ID

https://account.monofor.com/saml/91f1177b-2388-8851-69dd-4108bfdb4103

A unique identifier for the IdP. This URL is used by the service provider to identify the IdP.

Single Sign On Service

https://account.monofor.com/saml/91f1177b-2388-8851-69dd-4108bfdb4103/login

The URL where the service provider redirects users for Single Sign-On (SSO). This is the endpoint where users log in using SAML.

Single Logout Service

https://account.monofor.com/saml/91f1177b-2388-8851-69dd-4108bfdb4103/logout

The URL where the service provider redirects users for Single Logout (SLO). This is the endpoint where users log out using SAML.

Type of values to save for the certificate(s)

Configuration

Indicates that the type of data to be saved in the configuration is related to the certificates used for SAML assertions.

X.509 Certificate(s)

The certificate begins with -----BEGIN CERTIFICATE-----

end with

-----END CERTIFICATE-----

Specifies that the SAML assertions are signed using an X.509 certificate. The certificate must be in a specific format, starting with -----BEGIN CERTIFICATE----- and ending with -----END CERTIFICATE-----.

e. Configure User Info and Syncing

userinfoandsyncing.png

User Info and Syncing Configuration

Property

Value

Description

Unique ID attribute

(Mandatory)

eduPersonTargetedID

A SAML attribute whose value is unique per user and does not change over time. Its value is stored by Drupal and linked to the Drupal user that is logged in. (In principle, a non-transient NameID could also be used for this value; the SAML Authentication module does not support this yet.)
Example: eduPersonPrincipalName or eduPersonTargetedID

Attempt to link SAML data to existing local users

(Optional)

Enable matching on name: Checked

Enable matching on email: Checked

If enabled, whenever the unique ID in the SAML assertion is not already linked to a Drupal user but the assertion data can be matched with an existing non-linked user, that user will be linked and logged in. Matching is attempted in the order of below enabled checkboxes, until a user is found.

Warning: if the data used for matching can be changed by the IdP user, this has security implications; it enables a user to influence which Drupal user they take over.

Create users from SAML data

(Optional)

Checked

If data in the SAML assertion is not linked to a Drupal user, a new user is created using the name/email attributes from the response.

User name attribute

UserName

When users are linked/created, this field specifies which SAML attribute should be used for the Drupal user name.
Example: cn or eduPersonPrincipalName

The field only can be used if “Create users from SAML data“ option is enabled.

User email attribute

Email

When users are linked/created, this field specifies which SAML attribute should be used for the Drupal email address.
Example: mail

The field only can be used if “Create users from SAML data“ option is enabled.

In the User Info and Syncing section, please make sure all the configuration is configured according to your organization’s policy. Think wisely while configuring the section.

e. SAML Message Construction

samlmessageconstruction.png

SAML Message Construction Configuration

Property

Value

Description

Sign authentication requests

Checked

Requests sent to the Single Sign-On Service of the IdP will include a signature.*

Sign logout requests

Checked

Requests sent to the Single Logout Service of the IdP will include a signature.

Sign logout responses

Checked

Responses sent back to the IdP will include a signature.

Signature algorithm

SHA256

Algorithm used by the signing process.

Specify authentication context

Checked

Specify that only a subset of authentication methods available at the IdP should be used. (If checked, the "PasswordProtectedTransport" authentication method is specified, which is default behavior for the SAML Toolkit library. If other restrictions are needed, we should change the checkbox to a text input.)

Specify NameID policy

Checked

A NameIDPolicy element is added in authentication requests, mentioning the below format. This is default behavior for the SAML Toolkit library, but may be unneeded. If unchecked, the "Require NameID" checkbox may need to be unchecked too.

NameID Format

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

The format for the NameID attribute to request from the identity provider / to send in logout requests.*

f. SAML Message Validation

samlmessagevalidation.png

SAML Message Validation Configuration

Property

Value

Description

Require NameID

Checked

The authentication response from the IdP must contain a NameID attribute. (This is default behavior for the SAML Toolkit library, but the SAML Authentication module does not use NameID values, so it seems this can be unchecked safely.)

Strict validation of responses

Checked

Validation failures (partly based on the next options) will cause the SAML conversation to be terminated. In production environments, this must be set.

3- Assign a user to the Drupal Application

Please follow the below instructions on how to assign a user to the Drupal application. In this example john.smith will assign to the application access.

AssignUserToDrupal.png

Assign User to Drupal

4- Sign In Test

Now try to log in to Drupal using Monosign SSO.

Open a new browser and type Drupal web address. On the Drupal web address click the “Login with Monosign“ button.

LoginWithMonosignFromDrupal.png

Login to Drupal through Monosign SSO-1

SignInToDrupal.png

Login to Drupal through Monosign SSO-2

It can be login with Passwordless login(Monofor Identity), Passkey or Username and Password(Login with Password)

LoginWithPassword.png

Login to Drupal with UserName and Password

After clicking Sign in user will able to log in to Drupal.

LoggedIn.png

User Logged in through Monosign SSO

After completing the configuration on Drupal, it is better to clear all caches on the Configuration → Performance menu if the SAML SSO doesn’t work.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.