How to get SSAD

Fragment block

in decrypting you hard drive (you do use
Pieta, head
  Single Sign on with Active Directory in Drupal 8 Denial As in most open source communities, in the Drupal community there is a healthy distrust against closed source software like Windows. On the other hand, in many large organisations closed source applications are embraced because of the feeling that lives among decision makers that is good to have a large commercial partner that is responsible for maintaining and extending business critical applications. So, like it or not, there are situations where our open source application wil  have to connect to some closed source application and one of the situations I personal y encounter most often, is the situation where user accounts are stored in an Active Directory and the users must be able to login to the website using there Active Directory account. Anger Although anger certainly is a stage I have to go through in any software development project, I really think it is an emotion one should not spent to much energy on. If anger is something you are into, take a yoga class, or take a good long run. It helps. Bargaining So back to useful information. There are a number of things that must be taken care of before we can start to connect to Active Directory. First of al , you should be able to connect to the Active Directory server. This may seem like stating the obvious, but in almost al  projects I have done in which the website has to connect to Active Directory server (or any other external database system for that matter), there comes the moment at which you ask a sysadmin for the access details and the answer wil  be something like "No way an external developer like you gets any access to our internal data servers".  And, and this is free of any irony or sarcasm: of course she is absolutely right! Services likes this most of the time contain tons of personal data which you do not want to share with any external party, even in situations where this would be legal. So this real y is where the bargaining starts: you wil  have to have someway of connecting to the AD-server to realize the single sign on service, and so you have to be prepared to make some sacrifices and/or compromises like developing through a (more or less stable) VPN-connection, physical y be present at the clients office etc... When this is handled, we can start to do that in which we do excel: diving in to code and getting things to work. Forst step is to get SimpleSAML. The latest version can be downloaded from the SimpleSAML site, but in our Drupal 8 projects we use Composer to maintain modules and dependencies. So to include the simplesamlphp_auth-module in our project we use: > composer require drupal/simplesamlphp_auth This module has a dependency on the SimpleSAML library defined in its own composer.json:    "require": { "simplesamlphp/simplesamlphp": "~1.14.11" } The directory structure we are using is the following: Project root |- config (configuation directory) |- docroot (website directory) |- Documentation |- private_files |- settings |- utility |- vendor (Composer directory) Which means that the SimpleSAML library and the dependency SAML2 are downloaded to vendor/simplesamlphp  This of course only installs the default code and settings and the question is how do we configure SimpleSAML. We can not simply add or edit the config in vendor/simplesamlphp/simplesamlphp because that directory can be overwritten after a composer install or composer update (and, in our setup, is not even included in the git-repository) . The solution implemented by the SimpleSAML developers is using the vhost-config of the website to tel  SImpleSAML where the configuration is stored. So if the website on which we want to SimpleSAML is 'ad-example.org', edit the vhost, which on my system can be done with: > vim /etc/apache2/sites-available/ad-example.org.conf And in the vhost-configuration include the fol owing setting (this assumes the project root is located at /var/www/ad-example): SetEnv SIMPLESAMLPHP_CONFIG_DIR /var/www/ad-example/config/simplesamlphp And while we are at it, an alias to the SimpleSAML environment should also be included in the vhost-configuration: Alias /simplesaml /var/www/ad-example/vendor/simplesamlphp/simplesamlphp/www <Directory /var/www/ad-example/vendor/simplesamlphp/simplesamlphp/www> <IfModule !mod_authz_core.c> # For Apache 2.2: Order allow,deny Allow from all </IfModule> <IfModule mod_authz_core.c> # For Apache 2.4: Require all granted </IfModule> </Directory> Basicall y this says: the directory '/var/www/ad-example/vendor/simplesamlphp/simplesamlphp/www' is accessible from 'http://ad-example.org/simplesaml' Now SimpleSAML knows its configuration is located at /var/www/ad-example/config/simplesamlphp. This directory contains all  the config for the modules used in SimpleSAML, see the config template in the vendor directory: vendor/simplesamlphp/simplesamlphp/config-templates` Which contains the following files:
  • acl.php
  • authmemcookie.php
  • authsources.php
  • cas-ldap.php
  • config.php
  • config-login-auto.php
  • config-login-feide.php
  • ldap.php
  • ldapmulti.php
  • translation.php
Of these the config.php is the first file that requires our attention. Administrative settings First thing you should do is to change the administrator password for the current SImpleSAML set up. Open the config.php-file and search for the string 'auth.adminpassword'. In the config-template this wil  be set to '123', replace this with a strong password, for example one (on Linux) generated by >pwgen --secure 10 1 But you knew that one, didn't you? The next option you should immediately alter is the salt. Search for ' secretsalt' and replace it with a strong salt, for example one generated (on Linux) by  >tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo The other administration options that you should set, and which I assume to be self-explanatory, are :
  • 'technicalcontact_name'
  • 'technicalcontact_email'
  • 'timezone'
System settings There are a number of system-dependent option that you could (or in some case: should) set:  
  • 'baseurlpath' => path to the SimpleSAML pages
  • 'certdir' => directory in which SimpleSAML stores its certificates. For safety reasons it is advisable to locate this outside the website-docroot.
  • 'datadir' => directory in which SimpleSAML stores its other date. For safety reasons it is advisable to locate this outside the website-docroot.
  • 'loggingdir' => directory in which SImpleSAML stores it logs.
  • 'templatedir' => directory in which SimpleSAML stores the HTML-templates is uses for its own pages. We wil  get back to this later.
Make sure the above defined directories are writable for the Apache-user. Settings for Active Directory The setup for Active Directory requires a number of options to be set. It is important to realize that the Drupal-module can not use 'phpsession' as backing store. The easiest solution for this is to set the backing store to 'memcache'. To do so, open the `config.php-file in our config directory and search for the string 'store.type'. Change 'store.type' => 'phpsession' To 'store.type' => 'memcache' This assumes the memcache and memcached extensions are instal ed on your system and that the PHP memcache extension is also activated. You also could use the sql-store type, but this could lead to reduced performance because sql is a much resource hungry application than memcache. Next the standard SimpleSAML Identity Provider must be enabled with: 'enable.saml20-idp' => true With this alterations in place save the config.php-file. Now we are ready to configure the Active Directory settings. Open the file authsources.php (in our configuration directory). This file (in its original state) lists al  the authentication sources  for which SimpleSAML has plugins. The configuration for each plugin is an associative array with a structure like this: '<name>' => array( '<type>', 'option_1' => 'value, 'option_2' => 'value, etc... ) For now we are only interested in the LDAP-plugin, so search for the string 'ldap:LDAP' which will  lead you to the example configuration for the LDAP authentication source, an array starting with: 'example-ldap' => array( 'ldap:LDAP', Copy this array, making sure the start- and end-comment-markers (/* */) are not included and first of al  change the name ('example-ldap') to a logical name, which in our case would be something like, euh, wel , euh 'example-ldap'? Anyway, you probably understand what I'm trying to say here: make sure you use a logical name so that future developers wil  understand what you did here, and in future developers I do include you yourself somewhere in the future. In this array you can set the following options: dnpattern The dnpattern is basically what links a Drupal user to a user in the Active Directory. The exact value of this depends on the configuration of the Active Directory. A basic example would assume we want the users to use their AD principal name for the account name in Drupal. If we further assume a more or less flat structure for the AD, the setting would be something like: 'auth.ldap.dnpattern' => 'userPrincipalName=%username%,ou=userGroup,dc=example,dc=org', In this example %username% is replaced by the user name the user fil s in on the Drupal login form. If this leads to a valid Active Directory user, the user is logged in. hostname This is the complete URI that points to the AD-server and has the following form: 'ldaps://<hostname>:<port>, attributes As the comment in the config-template says: The attributes parameter is a list of attributes that should be retrieved. If the attributes parameter is set to nul , al  attributes wil  be retrieved. enable_tls To enable encryption when connecting to the AD-server set this variable to true. Check with the sysadmin if this is the case. Because most AD-server are only accessible from inside certain networks, this option wil  need to be set to 'false' more often then you would normally expect. search.enable Set this option to true if you want to enable searching in the AD for a given user. This option is mutually exclusive with the 'dnpattern'-option because you will either search for a user or find her directly. Beware however that the 'dnpattern' does not use wild cards and therefore is only applicable for AD's with a very flat structure. search.base Determine the start of the search. Only needed when 'auth.ldap.search.enable' is set to true. Example: 'search.base' => 'ou=example,dc=example,dc=org', search.attributes Array to determine in which attributes is searched. Beware not to add to many attributes here, that could cause the search to find too many users. search.username In most cases searching the Active Directory wil  not be al owed to any user (as you should remember from you earlier discussions with the sysadmin...). In this option you should define the user you want to use for searching the AD. This user, and her password (see below) should be provided to you by the sysadmin. search.password The password for the user in 'search.username'. Drupal specific settings After editing the SimpleSAML configuration files we are ready to adjust our settings on the Drupal side. To do so, login to the site with an administrator account and go to /admin/config/people/simplesamlphp_auth Basic settings Make sure you are on the tab 'Basic Settings' and then stop! Do not yet tick the box before the option Activate authentication via SimpleSAMLphp Because, as explained beneath the label, enabling this could completely lock you out of your Drupal environment. At the option Authentication source for this SP you wil  have to supply the logical name you entered when editing the authsources.php-file, which in our example is 'example-ldap'. The Drupal module adds a link to the default login form, at the option Federated Log In Link Display Name you can give the text used for this link. The last important option on this page is the option Register users (i.e., auto-provisioning) under USER PROVISIONING. This determines is a user account is created when a user logs in via the Active Directory (and, of course, the account does not yet exists) or that users must have pre-existing account in Drupal before they are al owed to log in via the Active Directory. This last case would be useful if users are created by hand or as a result of some import script.       Local authentification Next go to the tab 'Local authentication'. On this tab you can determine which roles (if any) are allowed to log in without checking their credentials in the Active Directory. I would recommend to at least include the 'Administrator'-role in this list because administrators (in my view) should always be allowed to login the site. But of course you can have your reason not to let them log in without the check in Active Directory. In that case make real y sure that you have a fully working Active Directory-setup before enabling 'Activate authentication via SimpleSAMLphp' on the 'Basic Settings'-tab. Anyways, it would be good idea to save the default 'simplesamlphp_auth.settings.yml' config file (at least in git) to make it possible to revert this setting in the case yo do get locked out. User info and syncing On this tab you determine how the Active Directory users are mapped on to Drupal users. SimpleSAMLphp attribute to be used as unique identifier for the user SimpleSAMLphp attribute to be used as email address for the user Synchronize user name on every login Synchronize email address on every login Automatic role population from simpleSAMLphp attributes Reevaluate roles every time the user logs in Automatically enable SAML authentication for existing users upon successful login Depression If you are anything like me, you now wil  be longing to get some actual results. So test your setup, direct your browser to your site and go to '/simplesaml', so in our example this would be the URL: http://example.org/simplesaml This, I hope, wil  trigger your first disappointment: should this kind of data real y be accessible for anyone? You will (hopefully) agree with me that it shouldn't. So to correct this, go to our config directory and edit the config.php-file. Search for the strings 'admin.protectindexpage' 'admin.protectmetadata' And set both to true. Depending on the settings of you webservice, reloading the /simplesaml page wil  now only show a login form. If not, restart the webserver and try again, making sure you have edited and saved the config.php-file as stated above. The password to use here is the (strong!) password you defined in the setting 'auth.adminpassword'. After taking this hurdle, let us proceed to the next one: Click on the tab 'Authentication' and then on the link 'Test configured authentication sources'. You wil  now get an overview of all configured authentication sources, among which our LDAP source which you gave the logical name when editing the authsources.php-file, but which in our example is 'example-ldap'. You wil  now be directed to the standard SimpleSAML login form, which wil  ask you for your username and password. This, of course, are the username and password of a valid user in the Active Directory which you bargained from the sysadmin. Entering these wil  most likely result in... an error like this one: Authentication error in source 'ldap'. The reason was: 'Library - LDAP bind(): Bind failed with DN \'hostname\'; cause: \'Can\'t contact LDAP server\' (0xffffffffffffffff)'. Which basical y means that you do not have access to the Active Directory server. To debug this a number of options are available (on Linux): dig: You can use 'dig <hostname>' to check if the domain name you supplied is valid.  nc: To check if the correct port is opened at the server nc -zv <hostname> <port>. For LDAP the deafult port is 389, but again check with your sysadmin.  Also check that the user name and password of the privileged user are correct. if the above commands made clear you can connect to the server and the above error is no longer shown, but you still  can not succesfully test the login, you can use the Linux command 'ldapsearch' to further debug the LDAP-query. An example search would be: ldapsearch -h example.org -W -x -y ./acces.data -D "cn=<search_user_name>, OU=group,DC=example,DC=org" -b "OU=group,DC=example,DC=org" "cn=<user_name>" In this example <search_user_name> the -D option defines the ful  path to the privileged user in the Active Directory who is al owed to search the Active Directory and whose password is stored in the file ./acces.data (because you never type sensitive data like passwords on the command prompt, do you?). After the '-h' option the name or ip-address of the Active Directory is given, the '-b' option defines the starting point of the search, you should start with using the path given in 'search.base'-option in the authsources.php-file, but also check less specific paths to rule out this setting as the one who make the search fail. Acceptance If (finally) the test login succeeds you are ready to go back to the setting for the Drupal module at /admin/config/people/simplesamlphp_auth and tick that checkbox next to 'Activate authentication via SimpleSAMLphp' and test the Drupal login with a valid Active Directory user. Now al  that remains is to deploy you code to your acceptance server and test is again there. Oh, you did discuss with the sysadmin that the acceptance and production server also must have access to the Active Directory server, didn' t you? Links and resources The structure of this blog was based on the Kübler-Ross model which describes the 5 stages of grieve. SimpleSAML is an open source library available at SimpleSAML.org. Although thedocumentation on the SimpleSAML site is extensive, it is also rather compact. This blog is  meant as an easy quick-start and by no means the official documentation should be discarded.    
Author
louis