Configure single sign-on (SSO) with Azure AD

Zefort supports SSO with Azure AD (and various other identity providers) using SAML 2.0.

With these instructions, you can set up basic single-sign-on, where users for particular domain name (e.g. yourcompany.com) are delegated to Azure AD for authentication instead of using Zefort’s built-in password authentication.

In this scenario, Zefort is the Service Provider (SP) and Azure AD is the Identity Provider (IdP).

A single Zefort account can be configured for SSO with multiple different domains (IdPs).   A single domain can also be configured to be used for multiple Zefort accounts.  Users who have access to multiple accounts will be able to choose which account to use at any time.

Prerequisites

You need:

  • A Zefort administrator user account with the ”can manage account settings” permission
  • Access to configure the DNS records for your domain
  • Administrative access to your Azure AD

Sidenote: as a best practice, organisations using Zefort often reserve some administrator user accounts for IT personnel, who only have access to configure account settings (and possibly manage user accounts), but no access to actual contracts or other content.

Overview

The steps to configure SAML integration with Azure AD are:

  1. Create a new SAML integration in Zefort’s Account settings
  2. Verify your domain name by entering a validation token in your domain’s DNS configuration
  3. Add a SAML application in your Azure AD tentant
  4. Copy IdP metadata URL from Azure AD to Zefort
  5. Finish configuration in Zefort

1. Create a SAML integration in Zefort

In this step, you create a new SAML integration object in Zefort for the domain you wish to use.

Sign in to Zefort with your administrator account, and browse to Account settingsIntegrations.

Select “Add another” or  “Install”  for SAML Single Sign-On.

Enter the domain name you wish to use for SSO (e.g. yourcompany.com) and click Save.

2. Verify domain name

In this section you verify that you control the domain name by entering a validation token in your DNS configuration.

In the DNS configuration for your domain, create a TXT record with the content provided on the integration’s configuration page.

When the TXT record is in place, click the “Check TXT record” button to verify.  You may need to wait for a while for the DNS changes to propagate, and return to the page later.

Once the domain is verified, you will see a green indicator in the Domain name section, and you can move to the next step.

SAML SSO domain validation completed

For security reasons, Zefort periodically re-checks the presence of the TXT record.  Do not remove the TXT record to ensure SSO with Zefort continues to work.

3. Add an application in your Azure AD tenant

In this step, you create the SAML application in your Azure AD tenant configuration.

Add Zefort as a “non-gallery” application in Azure AD.  Follow Microsoft’s instructions here.

You can use this image as a logo:

Zefort-logo-215.png

Configure SAML-based single sign-on for the app.  Copy the values for the Entity ID and ACS (Assertion Consumer Service) URL from Zefort.  You can use the value for ACS URL also for the Sign-On URL.

For the Unique User Identifier (or Name Identifier using SAML terminology), change the setting from UPN to a more stable identifier which will not change even if users’ email addresses or names change.  We recommend using user.objectid.

Define the following in User Attributes and Claims:

SAML attributeAzure AD attribute
givennameuser.givenname
surnameuser.surname
emailaddressuser.mail
Unique User Identifieruser.objectid

When the application is configured, find the IdP metadata URL for the application.  It is of the format https://login.microsoftonline.com/<Directory ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<Application ID>

4. Add IdP metadata to Zefort

Enter the IDP metadata URL in the integration configuration page under “Identity Provider (IdP)” and press Save.

You should now get green indicator for the Identity Provider (IdP) section, and the SAML integration is ready to be used.

SAML IdP metadata from Azure AD added in Zefort

5. Configure user provisioning

There are two alternatives for this: manually managing users in Zefort, or just-in-time provisioning of users as they sign in via SSO for the first time.

To manually manage users, choose ”Add users manually”.  Even if a user has access to the Zefort application on Azure AD, they will not be able to sign in to Zefort unless they are first manually added by an administrator user with the “Can manage users” permission.

To configure just-in-time provisioning, choose ”Add new users automatically upon login”.   Subject to limitations with number of user licenses on your Zefort account, users are automatically added when they sign in via SSO for the first time.

Enable and test signing in

Change the integration status from “Disabled” to  “Active” and press Save.  Try signing in on a different machine, a different browser, or an incognito window.  If there are problems, turn the integration status back to “Disabled” to avoid locking yourself out.