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.
Select the 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
General
⚠️ 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)
andReply URL (Assertion Consumer Service URL)
required fields. Note that the URL must includehttps://
even for dummy values. - Keep the default settings for the
Attributes & Claims
section.
Attribute Statements
Use the attribute mappings provided below when configuring the Zentral realm with Azure AD for SSO.
Zentral realm - Attribute | Claim name | AzureAD Value |
---|---|---|
Username claim | name | user.userprincipalname |
Email claim | emailaddress | user.mail |
First name claim | givenname | user.givenname |
Last name claim | surname | user.surname |
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
Download the 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 SAML realm
.
Fill up the form:
- Pick a name for the Realm config
- Select
Enabled for login
if 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
- Leave
Full name claim
empty - 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:
AzureAD application | Zentral realm |
---|---|
Identifier (Entity ID) | 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.