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.

1. Log into your Azure account
2. Locate the Azure Active Directory (AAD) service
3. Scroll down to Enterprise application
4. Click on Enterprise Application and create a new Enterprise App and pick a useful name (i.e. Zentral AAD)
5. Next choose the SAML Single sign-on method

Create new Enterprise application

We will use SAML as SSO 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
https://zentral.example.com/saml2/login/

Setup URLs with your own FQDN

2. User Attributes & Claims

Next in the user claims we need to change only a single attribute. look out for the Unique User Identifier .

1. For editing you can click on the “nameidentifier”entry (highlighted in the screenshot)
2. The default Source attribute assignment here is set to user.userprincipalname, we want to change this to user.mail
   (scroll down the Source attributes)
3. Now apply the change, click the Save button

With other settings we’ll stick to the defaults provided by Azure.

Change Unique User Identifier value

Manage and change the user claim

should look like this after change

3. SAML Signing Certificate

Here we’ll need to download a Metadata file and ensure we’ll copy it over to the Zentral server.

1. Click on the Federation Metadata XML download link
2. 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.

1. Click the Users and Groups section
2. Add your user(s)
3. 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

1. Connect via Terminal to your Zentral instance
   (via ssh or tools like awscli, gcloud etc.)
2. Copy the content of the local Federation Metadata .xml file into your pasteboard (yes this is one previously downloaded from Azure)
3. 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

We must make Zentral aware of the new IDP Metadata.xml file next. For that we’ll add two new ENV entries into the zentral_web_app systemd service file:

• Environment=ZENTRAL_SAML2_IDP_NAME
• Environment=ZENTRAL_SAML2_IDP_METADATA_FILE

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):

Environment=ZENTRAL_SAML2_IDP_NAME=Azure-AD
Environment=ZENTRAL_SAML2_IDP_METADATA_FILE=/home/zentral/conf/AzureAD_zentral.example.com.xml

After the edit it should look like this

Note: Any if you want to set a name with spaces make use of quotation marks as shown here:"Environment="ZENTRAL_SAML2_IDP_NAME=Azure AD"

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

Voilà, just a few seconds later we’ll see a new SSO button appear in the Zentral login window and now can run SingleSignOn with AzureAD.

Back in Azure you will see an overview of sign-in events in an and could peek into details more from there.

Wrap up

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;).