Azure AD - SAML integration
This is a quick guide to help integrate Zentral with Azure AD using SAML for single sign-on.
In Zentral, identity providers (IdP) are configured using realms. There are three kinds of realm: SAML, OIDC, and LDAP. In this case, we will use a SAML realm.
We will start by setting up an Azure AD Enterprise Application with the Basic SAML Configuration. We will then configure a Zentral realm for this application. Finally, we will update the Azure AD application configuration.
Create an Azure AD application
Follow along the Azure documentation available here.
Create the app
Browse to Azure Active Directory
Enterprise Applications, select
Create your own application and opt for
Non-gallery application, this will take you to a newly created app.
Single Sign-On option in the tiles or in the menu to start the setup, select the
SAML option for editing the configuration.
Configure the SAML settings
⚠️ The Zentral URLs for the SAML integration are only available after the realm has been saved. In order to be able to save the realm, we need the metadata from the Azure AD Enterprise App. This is a chicken-egg kind of problem. That's why we suggest to first use temporary dummy values for some of the fields in AzureAD initially and update them later.
- set dummy values for the
Identifier (Entity ID)and
Reply URL (Assertion Consumer Service URL)required fields. Note that the URL must include
https://even for dummy values.
- Keep the default settings for the
Attributes & Claimssection.
Use the attribute mappings provided below when configuring the Zentral realm with Azure AD for SSO.
|Zentral realm - Attribute
|First name claim
|Last name claim
The default SAML claim mappings (see above) in Azure AD may not align with your organization's needs and could require adjustments.
Download the AzureAD Enterprise App metadata
Federation Metadata XML file from the
SAML Certificates section.
Create the Zentral realm
In Zentral, go to
Setup > Realms, click on
Create realm and select
Fill up the form:
- Pick a name for the Realm config
Enabled for loginif you want to use this realm as login realm
- Pick a login session expiry (can be left empty, see help text)
- Use the default claim mappings from the Azure AD SAML settings (see section above) for the claims
Full name claimempty
- Upload the metadata file you just saved (see previous section)
- If you want to allow logins initiated by the IDP, tick the box
Update the AzureAD application
We now have all the values required to finish configuring the AzureAD application.
In the Azure AD Enterprise app, update the SAML settings in the
Basic SAML Configuration tab:
|Identifier (Entity ID)
|Reply URL (Assertion Consumer Service URL)
|Assertion Consumer Service URL
You can check if everything is working using the 🕶 button in the Zentral realm detail page. It will trigger an authentication with the IdP and display the claims Zentral receives with their mappings.
Optional: Group mappings
You can map some Azure AD claim/value pairs to Zentral groups, see details here This allows you to manage the group memberships from Azure AD.
In the Zentral realm detail page, click on the
Create button under
Group mapping. Pick a claim, a value, and a group.
When users log in and their claim matches, they will be added to the group. If the claim does not match, they will be removed from the group.
The mappings can be tested with the 🕶 button.