This aims to be a step-by-step walkthrough showing you how to configure Azure Active Directory and ZendTo, so that Azure AD is used as a Single Sign-On (SSO) Identity Provider (IdP) for ZendTo (the SP).
I assume you are familiar with the Azure Portal and ZendTo.
You must have followed the first 3 overall steps in the main SAML instructions:
Note: throughout this, replace "your-zendto-site.example.com" with the name of your ZendTo site.
SimpleSAMLphp provides its own mini-website at https://your-zendto-site.example.com/saml to let you:
The SimpleSAMLphp configuration files are all in /opt/zendto/simplesamlphp/config. These files are:
The only setting used here is the 'key' which should be set to a long random string just the same way as the 'secretsalt' in config.php above.
It is a very good idea to sign all SAML requests sent by ZendTo (the SP), and to check the signature of all responses from Azure (the IdP). Azure will send us their signing key in a few steps time, but we need to generate the signing key for ZendTo. Run this command:
openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out /opt/zendto/simplesamlphp/cert/saml.crt -keyout /opt/zendto/simplesamlphp/cert/saml.pem
It does not matter much what answers you give to the questions. then set its permissions correctly:
chgrp -R www-data /opt/zendto/simplesamlphp/cert chmod g=r,o-rwx /opt/zendto/simplesamlphp/cert/saml.pem
chgrp -R apache /opt/zendto/simplesamlphp/cert chmod g=r,o-rwx /opt/zendto/simplesamlphp/cert/saml.pem
Once you have logged into portal.azure.com and selected "Azure Active Directory", you need to add a new Enterprise application:
The "Name" you enter here can be anything, it is purely a displayed name with Azure. The users never see it.
You must first assign some users (or a group of all your users) so that these users will be able to login to ZendTo when these steps are complete. Always add at least yourself!
Back in the application's "Overview" page, we now configure SAML single sign on:
To find the Application Entity ID we need to use the SimpleSAMLphp mini-site at https://your-zendto-site.example.com/saml. Go there and log in with the password that you have set in config.php as the 'auth.adminpassword':
Go to the "Federation" tab and copy the "Entity ID" which looks like a URL:
Back in the Azure Portal, there are 3 settings that are needed:
Do not test your setup yet, we haven't finished so it won't work.
If, at any time, you see the following warning box, then click the "Click here" link to fix the problem. This looks to be caused by a minor bug in the Azure Portal, which it flags up itself:
Further down the Azure Portal page, there is the "SAML Signing Certificate" section. The only thing you need here is the "App Federation Metadata Url", from which SimpleSAMLphp will read everything else it needs (including the certificate). Copy it.
Back on your ZendTo server edit config-metarefresh.php.
The next job is to test that your ZendTo server can fetch the IdP metadata, and then that it puts it in the right place.
Replacing 'IDP-METADATA-URL' with the App Federation Metadata Url you just copied from Azure, run this command:
/opt/zendto/simplesamlphp/modules/metarefresh/bin/metarefresh.php -s 'IDP-METADATA-URL'
It should print out a big PHP data structure with lots of keys, arrows and values. If it prints a load of errors, you have got the wrong URL.
Now to fetch it for real for the first time and check the output is in the right place. Run the command:
If that worked, you should now have at least 1 file in /var/zendto/saml-metadata/azure.
In future, the cron feature in SimpleSAMLphp will automatically re-fetch the IdP metadata every day to ensure it is kept up to date. There is no need to do this manually.
We can now get the value for the 'idp' setting.
We should now be ready to test your authentication configuration, and if that works we will be shown all the User Attributes needed for the 'samlAttributesMap' in ZendTo's preferences.php.
The "address book" feature in ZendTo uses their login username as the key for looking up their list of stored names and addresses, which is presented when they enter a recipient in the "new drop-off" or "request a drop-off" forms. Up until now, your users will have logged in as a simple username (no @ in it). Now using SAML, they will be logged in as an email address in the form "email@example.com".
The effect of this change will be that all your users will suddenly appear to have empty address books; no auto-complete suggestions will be shown.
The solution to this is a single SQL command that will append "@your-domain.com" onto the end of every username in the address book table within ZendTo's database. This SQL command is
UPDATE `addressbook` SET `username` = CONCAT(`username`, "@your-domain.com") WHERE `username` NOT LIKE "%@your-domain.com";
where you should change both occurrences of your-domain.com to be the correct domain name that your users enter when they login via SAML.
Check in your preferences.php file for the setting 'automationUsers'. If this has clearly been set for your local environment, then you are probably using this feature so that you can drive ZendTo in an entirely automated way, from scripts and other applications of your own.
If so, then check the preferences.php file for the setting 'samlAutomationAuthenticator'. SAML authentication is not very suitable for scripting or logging in to an application in an automated way. To fix this shortcoming, ZendTo's other authentication mechanisms are still available for any users listed in the 'automationUsers' setting. This 'samlAutomationAuthenticator' setting simply tells ZendTo which authenticator to use in this case. It would most likely be 'Local' or 'AD'.
If you are not using the "automation" feature, there is no reason to change this setting at all.
If you set up ZendTo using any other interesting SAML-based authentication systems such as, in particular, Yubikeys or other hardware tokens, please do write a few notes on how you did it and what configuration changes you had to make. Then share what you have learned by emailing me, so that I can help make it easier for the next person that wants to use the same system as you.Please also report all bugs, issues, suggestions and so on.