Azure AD SSO to Drupal

We had previously made use of the free Azure AD included with our clients Office 365 (E3) subscription and installed Azure AD Sync from out on premise AD to Azure.

Out of the box, Azure AD supports applications and it is capable of support SSO to non-microsoft app’s.

The most simple way is password SSO where an administrator or the user enters their credentials for a 3rd party app which are then stored securely by Microsoft.
These credentials are then pushed into the credential fields of the website when the user connects.
For me, there were two problems with this approach:

• it apparently requires a browser extension to fetch the credentials but I found precious little documentaiton of that extension
  
• it seems to require an Azure AD premium subscription.
  
  

An alternative is to install and use SAML authentication.

1. Install SimpleSAMLPHP

   Do not change the default install directory of /var/simplesamlphp, doing so makes the process unnecessarily more complex as multiple file edits are required.

2. Configure it

   Need to configure SimpleSAMLPHP as a Service Provider, the details are here
   That said, use this post{:target=”_blank”} (pdf of original¹) by Lewis Roberts instead, follow the instructions exactly.

   Note: I chose to change the default baseurlpath to /saml. To test simplesamlphp, go to, e.g., https://drupal-sso.example.org.uk/saml

   Note: Lewis Roberts uses the default Service Provider name of ‘default-sp’ in his post. I chose to change this to ‘azuread’. Adjust your commands accordingly.

   Note: Must configure session to use something other than phpsession. I used sql and the connection details for Drupal database.

   Must be working against Azure AD before proceeding - the authorisation check must succeed (login and out).

3. Create and configure your app in Azure AD

   In the Configure section pay particular attention to:

   • Sign-On URL
     Should end in /saml_login, e.g. https://drupal-sso.example.org.uk/saml_login

   • App ID URI
     Can be left as the base URL, e.g. https://drupal-sso.example.org.uk

   • Reply URI
     This is critical, it must be changed to something similar to this:
     https://drpual-sso.example.org.uk/saml/module.php/saml/sp/saml2-acs.php/azuread
     If you following the setup instructions from Lewis Roberts then a URL with that query string should work.

4. Install simplesamlphp_auth module

   Follow the usual druapl module installation instructions.

5. Configure simplesamlphp_auth module

   Basic settings:
   Installation directory: /var/simplesamlphp
   Authenticaton source for this SP: azuread
   the name used to define entry in simplesamlphp config file
   Federated Log In Link Display Name: Azure AD
   this name will appear in Drupal Login page
   Login path: saml_login
   appended to the Drupal URL, also used as part of sign-on URL in Azure AD, no leading slash.
   Turn on debugging messages: off
   can be useful to have this on during initial setup, writes to Drupal log.
   User provisioning: off
   we do not want this as drupal users are pre-created
   turning this off does mean that users have to be manually created in authmap table.

   Drupal Authentication
   Allow authentication to local Drupal accounts: on
   but only for certain users
   Allow SAML users to set Drupal passwords: off
   we have disabled local Drupal password change
   Which ROLES should be allowed to login with local accounts:
   we allow Administrators to login using local credentials
   Which users should be allowed to login with local accounts: none, leave blank
   Specify a URL for users to go to after logging out: none, leave blank.
   if a user logs out then they will be logged out of all Azure AD which is not really what we want.
   users should not log out of Drupal, just close the tab.

   User info and syncing
   (can get this information from the simplesamlphp authentication test
   Which attribute from simpleSAMLphp should be used as user’s name: http://schemas.microsoft.com/identity/claims/displayname
   Which attribute from simpleSAMLphp should be used as unique identifier for the user: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
   Which attribute from simpleSAMLphp should be used as user mail address: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
   Automatic role population from simpleSAMLphp attributes: leave blank
   I’ve found that Drupal role assignments are honoured once user has been logged in.
   This could be used however to map AD roles to Drupal should the need arise
   Reevaluate roles every time the user logs in.: Leave unchecked.
   Automatically enable SAML authentication for existing users upon successful login: leave unchecked.

   Against each Drupal user record there is also this field:
   Enable this user to leverage SAML authentication: leave unchecked.

6. Create authmap entries

   This setup requires manual creation of entries in the Drupal authmap table.

   mysql> describe authmap;
   +----------+------------------+------+-----+---------+----------------+
   | Field    | Type             | Null | Key | Default | Extra          |
   +----------+------------------+------+-----+---------+----------------+
   | aid      | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
   | uid      | int(11)          | NO   | MUL | 0       |                |
   | authname | varchar(128)     | NO   | UNI |         |                |
   | module   | varchar(128)     | NO   |     |         |                |
   +----------+------------------+------+-----+---------+----------------+
   4 rows in set (0.00 sec)

7. Activate the simplesamlphp_auth module

   SAMLlogin/out must be working before the simplesamlphp_auth module is activated.
   If it is not working correctly then it is highly likely that you will not be able to login as Drupal after the module is activated.

authmap notes

| uid | Drupal user ID that the AD user should map to |
| authname | the AD username, usually their email address. This should also match the email address in the Drupal user record. |
| module | must be set to ‘simplesamlphp_auth’ |

An authmap row can be created by executing an insert similar to:

insert into authmap (uid,authname,module) values (1,'alan.jeskins-powell@example.org.uk','simplesamlphp_auth');

It is also possible bulk insert entries into authmap but need to exclude any users with non-AD email addresses or people that already exist in authmap, e.g.

insert into authmap (uid,authname,module)
select u.uid,u.mail,'simplesamlphp_auth'
from users u
where u.status=1 /* not blocked */
and not exists (
  /* doesnt already exist in authmap */
  select 1
  from authmap
  where uid=u.uid
)
/* only users with an AD email address */
and u.mail like '%example.org%' ;

Troubleshooting.

Assuming you can login to Drupal -
Enable debug in simplesamlphp_auth module, test sign in and check Drupal log.

Exception: Error in simplesamlphp_auth.module: no valid unique id attribute set. in _simplesamlphp_auth_get_authname() ...
Means that the user unique ID identifier is incorrect, the default values will not work with Azure AD.
See:
Configure simplesamlphp_auth module ->
User info and syncing ->
Which attribute from simpleSAMLphp should be used as unique identifier for the user

On successful login the user is always taken to their users ohme page.
This is a known issue documented in https://www.drupal.org/project/simplesamlphp_auth, e.g.

 *  ISSUE: User is always dropped on user page after login, instead of where
 *         they were when they clicked "Federated Log In". Because of this, deep
 *         linking to access controlled content does not work. Usability would
 *         be considerably increased if this were resolved.