Setting Up Azure AD for EK SSO

This guide walks through configuring Azure Active Directory (Entra ID) as the Identity Provider (IdP) for SAML SSO on your on-premise EK instance. It covers the SAML settings to enter in Azure AD, how to retrieve your federation metadata, and how to register the domain in EK to complete the integration.

note

EK's generic SAML flow works with Azure AD / Entra ID out of the box. If you haven't already, read the SAML SSO Overview to understand how the integration works before you begin.

Prerequisites

• You have admin access to your Azure AD / Entra ID tenant.
• You have Super Admin access to your on-premise EK instance.
• You know the fully qualified domain name (FQDN) of your EK backend host (e.g. ek-api.corp.acme.com).
• You know the email domain you want to enable SSO for (e.g. acme.com).

Part 1 — Configure Azure AD

Create a New Enterprise Application in Azure AD

1. Create a new enterprise application

   In the Azure portal, navigate to Azure Active Directory → Enterprise applications and click New application. Select Create your own application, give it a name (e.g. EK SSO), and choose Integrate any other application you don't find in the gallery (Non-gallery).

2. Open the SSO configuration

   Once the application is created, navigate to Manage → Single sign-on and select SAML as the sign-on method.

3. Enter the Basic SAML Configuration

   In the Basic SAML Configuration section, enter the following values:

   Field	Value
   Identifier (Entity ID)	https://<your-FQDN>/backend/user/generic/sso/saml/acs/admin
   Reply URL (ACS URL)	https://<your-FQDN>/backend/user/generic/sso/saml/acs/admin
   Sign-on URL	Leave empty
   Relay State	default
   Logout URL	Leave empty

4. Configure attributes and claims

   In the Attributes & Claims section, confirm or add the following mappings:

   Attributes	Value
   givenname	user.givenname
   surname	user.surname
   emailaddress	user.mail
   name	user.userprincipalname
   DisplayName	user.displayname
   email	user.mail
   Unique User Identifier (Name ID)	user.userprincipalname

Part 2 — Retrieve the Azure AD Metadata

Once the Azure AD application is configured, retrieve the federation metadata URL:

1. Go to the SAML Certificates section

   In your application, navigate to Manage → Single sign-on → SAML Certificates.

2. Copy the App Federation Metadata URL

   Find and copy the App Federation Metadata URL.

   The path is:

   Manage > Single sign-on > SAML Certificates > App Federation Metadata URL

   You will need this URL in Part 3.
   

Part 3 — Register the Domain in EK

Send a POST request to the domain registration endpoint:

curl -X POST "https://<your-backend-host>/backend/sso/add_new_configuration" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "enterprise_id": "acme.com",
    "provider": "azure",
    "metadata_url": "https://your-azure-federation-metadata-url",
    "backend_root_url": "<your-backend-host>/backend"
  }'

Required Fields

Field	Description
enterprise_id	The email domain of your users (e.g. acme.com).
provider	"azure"
metadata_url	The App Federation Metadata URL from Part 2.
backend_root_url	(Optional) Required only in proxy setups to ensure correct routing.

Authentication

The endpoint requires your EK API Key and Secret passed as X-API-KEY and X-API-SECRET headers.

On success, a record is created in the sso_providers table on the backend.

Part 4 — Configure the Frontend

Once the domain is registered, set the frontend environment variable and restart the frontend service.

1. Open the frontend environment file

   On your on-premise deployment server, open onprem-deployment/.env.web.

2. Add the environment variable

   Add the following line, replacing acme.com with your actual email domain:

   VITE_SSO_ENTERPRISE_ID=acme.com

3. Restart the frontend services

   docker compose -f docker-compose down
   docker compose -f docker-compose up -d

Test the Integration

Sign in to EK with a real @<domain> user to confirm the flow works end to end. If the user authenticates successfully but is denied access, check your SAML Access Controls configuration — see the EK SAML Access Controls and Automated Team/Project Assignment guide.