Setup Azure AD based SSO for Zentral
In this post we’ll look how to enable the SingleSignOn (SSO) authentication for Zentral based on AzureAD/O365. So in case you happen to already use Azure as your SAML 2.0 provider we’ll show how quickly enable the Azure based sign-in for a Zentral instance.
Preparations in Azure
Before we start to activate SSO on the Zentral server side, we’ll need to setup the basics in Azure. For a common Azure based SSO setup you‘ll have to create a new Azure Enterprise App and activate it’s SAML 2.0 setting.
- Log into your Azure account
- Locate the Azure Active Directory (AAD) service
- Scroll down to Enterprise application
- Click on Enterprise Application and create a new Enterprise App and pick a useful name (i.e. Zentral AAD)
- Next choose the SAML Single sign-on method
1. Basic SAML Configuration
This configuration step is mandatory — we need to provide matching URLs for
Entity ID, ACS and the SignOn URL. Of course the FQDN used should be replaced with your own one.
Identifier (Entity ID) — (the metadata URL):
https://zentral.example.com/saml2/metadata/Reply URL (Assertion Consumer Service URL) (also known as ACS)
https://zentral.example.com/saml2/metadata/Sign on URL
2. User Attributes & Claims
Next in the user claims we need to change only a single attribute. look out for the Unique User Identifier .
- For editing you can click on the “nameidentifier”entry (highlighted in the screenshot)
- The default Source attribute assignment here is set to user.userprincipalname, we want to change this to user.mail
(scroll down the Source attributes)
- Now apply the change, click the Save button
With other settings we’ll stick to the defaults provided by Azure.
3. SAML Signing Certificate
Here we’ll need to download a Metadata file and ensure we’ll copy it over to the Zentral server.
- Click on the Federation Metadata XML download link
- Keep the downloaded .xml file around for later
(you‘ll need to copy/paste the content soon)
4. Users and groups
Users from Microsoft AzureAD (AAD) must be enabled for SSO in an Enterprise App, so next you’ll have to add the Users (or Groups) you’ll want to approve for login to Zentral via AzureAD.
- Click the Users and Groups section
- Add your user(s)
- Save your setting
Setup in Zentral
The final steps need to happen on the Zentral server side to SSO with Azure. For this we’ll have to copy the content of the downloaded Azure Federation Metadata XML file over to Zentral server, add it’s file path and a label to a systemd service and then restart a service afterwords.
2020 update — see the Realms tutorial for improved setup: https://youtu.be/04sIlLgryv0
Create your Metadata.xml
- Connect via Terminal to your Zentral instance
(via ssh or tools like awscli, gcloud etc.)
- Copy the content of the local Federation Metadata .xml file into your pasteboard (yes this is one previously downloaded from Azure)
- Next create a new file on the Zentral server, paste in the content copied from .xml file and then save the new file
sudo vim /home/zentral/conf/AzureAD_zentral.example.com.xml
Edit the systemd service
sudo vim /etc/systemd/system/zentral_web_app.service
Add two extra ENV variables into the
zentral_web_app.service file (see the final edit in the screenshot below):
Note: Any if you want to set a name with spaces make use of quotation marks as shown here:
Restart the services
Once the edits to the zentral_web_app.service file are saved, we need to reload the systemctl daemon:
sudo systemctl daemon-reload
The finally step is to restart the service “zentral_web_app” as well, so the new SSO button is shown in your browser.
sudo systemctl restart zentral_web_app
Back in Azure you will see an overview of sign-in events in an and could peek into details more from there.
We hope this guide is useful in case you’re using Azure and look out to run AzureAD for SAML 2.0. We’ve previously demonstrate similar instructions for an Okta based SSO setup — you can find the details here.
The setup is pretty much a standard and can be quickly adapted for most SingleSignOn providers (in fact we did use GSuite for SSO long before we’ve recently switched over to Azure).
Thanks and stay tuned for a next round of features to see in Zentral over next few weeks. You can reach out to us via Macadmins Slack or use the contact section on our Zentral Pro Services company site (yes, still german only site;).