This document will guide you through the process of enabling Microsoft Entra (formerly Active Directory) as a sign in option in Zenlytic.
Outcome
You'll have a custom sign in page with an option to
Sign in with Microsoft Entra
.You'll be able to control access to Zenlytic via Microsoft Entra
Prerequisites
Please note that the Microsoft Entra Sign-On integration is exclusively available for workspaces on the Enterprise plan.
1. First Steps
To begin the process, reach out to your Zenlytic contact and let them know you'd like to use Microsoft Entra SSO.
You'll work with them to create a company specific login page on your custom Zenlytic subdomain (mycompany.zenlytic.com
)
After that conversation, they will provide you with these two important values for future use:
Identifier (Entity ID)
Reply URL (Assertion Consumer Service URL)
2. Creating an Entra Application for Zenlytic
Go to the Enterprise application
section in Microsoft Entra and click New Application
Click the Create your own application
button.
Here we'll give it a name, for example zenlytic-client-app
, then select the Non-gallery
option.
Then click the Create
button.
3. Configuring your Zenlytic Application
Before continuing, ensure that you have obtained these values from your Zenlytic contact:
Identifier (Entity ID)
Reply URL (Assertion Consumer Service URL)
Now let's go to our newly created application under the Enterprise applications
section. Go ahead and click the name to open it.
We'll select the Single sign-on
section, then choose SAML
as the single sign-on method
Click the Edit
button for Basic SAML Configuration
Choose Add identifier
for the Identifier (Entity ID)
section and enter the Entity ID
that the Zenlytic support team gave you.
Now under Reply URL (Assertion Consumer Service URL)
, enter the value the Zenlytic support gave you.
Your form should look similar to this:
Hit the Save
button and hit the X
button.
4. Manage Attributes and Claims
In this section, you'll configure what you send to Zenlytic when a user signs in.
We'll need to make a few adjustments to ensure Zenlytic is using the correct fields for a user.
Click the Edit
button for Attributes & Claims
.
Zenlytic requires these fields to be mapped:
emailaddress
givenname
name
surname
By default, your mappings will look something like this:
In the past we've some users have varying namespaces
for their claims.
So just in case, we'll clear those values out.
Click on each of the claims under Additional Claims
, and clear out the Namespace
value
Your claim section should now similar to this:
It's important to note that your company may be using non-default values to represent your users. Specifically, we've seen some customers not have a value for the user.mail
field.
If we hit issues later on in the process, we'd recommend reaching out to an admin on your Entra account about this, or reach out to Zenlytic and we'll walk you through which value to use there. Please check out the Debug
section of this article for additional notes.
Now click the X
button to return back to your Application
You may be taken back to the this screen, if so just go back to your application by clicking this section:
5. Providing Zenlytic your App Federation Metadata Url
Copy this Url and you'll need to send it to your Zenlytic contact.
Once we receive that url, we'll finish up the rest of the setup on our and let you know when you're all set!
6. Adding Users/Groups to Zenlytic
With your application selected, click the "Users and Groups" tab.
Now click the "Add user/group" button.
Assign whomever you'd like to have access to Zenlytic.
7. On Completion
Requirements: Make sure you've sent your Zenlytic contact the App Federation Metadata Url
for your application.
Your Zenlytic contact will let you know when your SSO onboarding is ready for use.
Once you hear from them, you'll now be able to use your company specific login page:
mycompany.zenlytic.com/login
Debug Steps
Feel free to reach out to your Zenlytic contact if you encounter issues during setup.
If you're attempting to sign in to Zenlytic using Entra, and you're seeing errors about permissions, ensure that your Entra user has the appropriate permissions in Entra.
You can adjust a user/group role by going to the Users tab and then assigning them a proper role.
If you're seeing an error saying that email
is a required value in the claim mapping, make sure your user has a valid email in the Contact Information
section for that user
If your company does not provide a value for that field, please make sure to map the field you do use in the Attributes and Claims
section.