SAML authentication with Microsoft Entra ID

Setup guide

Zenskar supports single sign-on (SSO) via SAML 2.0, allowing organizations to authenticate users through their existing identity provider. This how-to guide will help you set up SAML in Zenskar using Microsoft Entra ID as the identity provider.


Step 1: Domain verification
  1. In Zenskar, click on the drop-up menu at the bottom of the side panel > Settings > SAML tab.
  2. In the Connection section of the SAML tab, enter your domain (e.g., acme.com).
  3. Click on the GET TXT RECORDS button.
  4. Add the following TXT record to your DNS:
Host nameTXT value
zenskar-verify.acme.comzenskar-verify=sample-verification-string
  1. Under Identity Provider, select Microsoft Entra ID from the dropdown.
Step 2: Identity provider configuration
  1. Log in to the Azure portal.

  2. Go to Microsoft Entra ID > Applications > Enterprise Applications > + New Application.

  3. Select Create your own application.

  4. Name your application (e.g., "Zenskar SSO") and choose Integrate any other application you don't find in the gallery (non-gallery application).

  5. After the app is created, go to Single Sign-On, choose SAML.

  6. Copy values of the following fields from the Azure portal and paste into Zenskar:

SourceDestination
Azure portal > Microsoft Entra ID > App registrations > [Your App] > Overview > Directory (tenant) IDZenskar > click on the drop-up menu at the bottom of the side panel > Settings > click on the SAML tab > Identity Provider Configuration section > Microsoft Entra Identifier
Azure portal > Microsoft Entra ID > App registrations > [Your App] > Endpoints > OAuth 2.0 authorization endpoint (v2)Zenskar > click on the drop-up menu at the bottom of the side panel > Settings > click on the SAML tab > Identity Provider Configuration section > Login URL
Azure portal > Microsoft Entra ID > Enterprise applications > [Your App] > Single sign-on > SAML Certificates > Certificate (Base64) > DownloadZenskar > click on the drop-up menu at the bottom of the side panel > Settings > click on the SAML tab > Identity Provider Configuration section > Certificate

🚧

Note

Open the downloaded certificate file in a text editor. Copy the certificate, including the BEGIN CERTIFICATE header and the END CERTIFICATE footer.

  1. Assign users or groups who should have access.
Step 3: Attribute mapping

Map Microsoft Entra SAML claims to Zenskar's internal user fields:

Zenskar fieldMicrosoft Entra claim (common defaults)
User IDuser.objectid
Email addressuser.mail
First nameuser.givenname
Last nameuser.surname

🔐 Default SAML claims in Microsoft Entra ID

Claim nameNamespaceSource attributeDescription
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifierStandarduser.userprincipalname or user.objectidUnique identifier for the user (also used as NameID)
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameStandarduser.userprincipalnameUser's sign-in name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameStandarduser.givennameUser’s first name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameStandarduser.surnameUser’s last name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressStandarduser.mailUser's primary email address
http://schemas.microsoft.com/ws/2008/06/identity/claims/roleMicrosoft-specificDirectory roles or app rolesPopulated if role-based access is configured
http://schemas.microsoft.com/identity/claims/tenantidMicrosoft-specificTenant IDAzure AD tenant GUID
http://schemas.microsoft.com/identity/claims/objectidentifierMicrosoft-specificuser.objectidUnique object ID of the user in Azure AD

🛠️ You can customize or add more claims

To customize SAML claims for an enterprise application:

  1. Go to the Azure portal.
  2. Navigate to Microsoft Entra ID > Enterprise applications > [Your App] > Single sign-on > User Attributes & Claims.
  3. From this page, you can:
  • Edit existing claims
  • Add new claims (e.g., id, employeeid)
  • Use transformation functions such as:
    • Join – combine multiple values
    • RegexReplace – perform pattern-based replacements
    • ToLower/ToUpper – change casing
    • ExtractMailPrefix – get the part before @ in an email address

💡

Note

Custom claims are helpful when the service provider expects specific attribute names or formats that don't match Azure's defaults.

.

Step 4: Add Zenskar SAML configuration values to Microsoft Entra
  1. Copy values of the following fields from Zenskar and paste into the Azure portal:
SourceDestination
Zenskar > click on the drop-up menu at the bottom of the side panel > Settings > click on the SAML tab > Zenskar SAML Configuration Values section > Entity IDAzure portal > Microsoft Entra ID > Enterprise applications > [Your App] > Single sign-on > Basic SAML Configuration > click the Edit icon (🖉) in the top-right of the Basic SAML Configuration box > Identifier (Entity ID)
Zenskar > click on the drop-up menu at the bottom of the side panel > Settings > click on the SAML tab > Zenskar SAML Configuration Values section > ACS URLAzure portal > Microsoft Entra ID > Enterprise applications > [Your App] > Single sign-on > Basic SAML Configuration > click the Edit icon (🖉) in the top-right of the Basic SAML Configuration box > Reply URL (Assertion Consumer Service URL)
  1. Save the configuration.
Step 5: Test SSO login
  1. Ensure the user exists in both Entra and Zenskar.
  2. Go to Zenksar app.
  3. Select Sign-in using SSO.
  4. You’ll be redirected to your IdP login screen.
  5. On success, you’ll be redirected back to the Zenskar dashboard.

Please feel free to reach out to [email protected] for any additional questions while you are going through the setup process.