SAML Config - Humber-ITS/wiki-docs GitHub Wiki

SAML can be used with the Microsoft Azure environment.

First, install the SAML Authentication module and then proceed with the following sections.

Reverse Proxy Settings

Add the below reverse proxy settings to your settings.php file:

$settings['reverse_proxy'] = TRUE;
$settings['reverse_proxy_addresses'] = array($_SERVER['REMOTE_ADDR']);
$settings['reverse_proxy_trusted_headers'] = \Symfony\Component\HttpFoundation\Request::HEADER_X_FORWARDED_PROTO | \Symfony\Component\HttpFoundation\Request::HEADER_FORWARDED;

Note: This step is required when using a load balancer. This prevents the site from seeing it's actual IP and protocol and Drupal falsely thinks that it is using http instead of https protocol.

Generate Key and Cert Files

  1. Create a folder for your key and cert files. One option is to keep both files in a folder called saml_cert in your Drupal root directory.

  2. cd into the desired folder and run the below command and follow the directions in the prompts.

openssl req -new -x509 -days 3652 -nodes -out sp.crt -keyout sp.key

Note: The private key file should not be in your /web directory.

Configuring SAML Authentication

Once SAML Authentication has been installed, you can access the settings under Configuration -> People -> SAML authentication.

As the settings page contains multiple tabs and multiple sections within the tabs, I specified each tab and section for the below settings. For any settings not mentioned, leave the default value.

Configuration Tab

Login/Logout Section

  1. Under "Roles allowed to use Drupal login also when linked to a SAML login", checkmark any roles that should still be able to login without SAML. Admin is recommended as a SAML outage could cause the site to be inaccessible.

Service Provider Section

  1. Set an Entity ID. This can be https://your-site.io or whatever your URL is
  2. Under "Type of values to save for the key/certificate" select "File"
  3. Under "Private Key filename" and "X.509 Certificate Filename" enter the absolute paths for both files. This should look similar to /var/www/websites/site_name/saml_cert/sp.key & /var/www/websites/site_name/saml_cert/sp.crt

Important: After you have configured the Service Provider Section, your Project Manager should connect you with Digital Solutions. You will need to provide them with the below information, and they will provide you with a metadata URL you will need for the next section.

  1. App Name: Name of your app.
  2. Entity ID: The ID configured in the Service Provider Section.
  3. Reply URL: This is listed in the Service Provider Section beside "Assertion Consumer Service".
  4. Who needs access: Which department or individuals should have access to the site.

Identity Provider Section

SAML Authentication doesn't have any way of parsing the metadata URL, so at this time it is recommended to open this URL in the browser to view the xml, and ctrl + f the information you need.

  1. For "Entity ID", find the value in entityID=
  2. For "Single Sign On Service", find the value in <SingleSignOnService...
  3. For "Single Logout Service", find the value in <SingleLogoutService...
  4. For "Type of values to save for the certificate(s)" select Configuration
  5. For "Certificate", paste in the X.509 certificate from the metadata URL. This will start with

User Info and Syncing Section

  1. For "Unique ID attribute" paste http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name which is the Azure username attribute, and is used as the unique identifier for SSO. If this doesn't work, you can view the XML for all the available attributes. To enable name matching (read below for more information), checkmark "Enable matching on name" under "Attempt to link SAML data to existing local users".
  2. Ensure that you checkmark which names are eligible for matching to their SSO accounts.
  3. Enable "Synchronize email address on every login" for the email address to be updated automatically.
  4. For "User name attribute" enter http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  5. For "User email attribute" enter http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Name Matching & User Creation: Name matching allows Drupal to match an existing user with the SSO account when the user logs in. This requires creating the user first with their [email protected], and then logging in with the user. If you require new users to be created when they login by SSO for the first time, you must instead enable "Create users from SAML data".

SAML Message Construction

At the time of writing this guide, this section can be left unchanged.

SAML Message Validation Section

  1. Enable "Retrieve logout signature parameters from $_SERVER['REQUEST']"
  2. Disable "Require messages to be signed"

Debugging Section

There are no settings that need to be turned on in this section, but it provides useful tools for debugging. I recommend enabling "Show detailed errors to the user" while configuring SAML.

User Field Mapping Tab

This tab is for configuring attribute mapping, and these settings are optional. By default, Drupal users only have usernames. If you need user accounts to also sync names, you need to first create a new user field, and then configure attribute mapping in SAML Authentication.

Adding a User Field

  1. First, you need to add a name field in Account Settings. You can do this by going to Configuration -> People -> Account Settings -> Manage Fields.
  2. Click "Create a New Field". If you want to have the complete Display Name (first and last name combined) then simply create a "Display Name" field with the field type "Text (plain)". You can also configure the "Manage Form Display" and "Manage Display" sections to your liking.
  3. Once this is done, go back to the User Field Mapping tab under SAML Authentication settings.

Note: The Display Name attribute is the full name of the user, but it is also possible to get the givenname and surname of the user using different attributes from the Metadata URL. You can find the complete list by looking under fed:ClaimTypesOffered in the Metadata URL.

Configure Attribute Mapping

  1. Click "Add Mapping". For "SAML Attribute", you can add http://schemas.microsoft.com/identity/claims/displayname. For "User Field" you can select the field you created in the previous step.