> ## Documentation Index
> Fetch the complete documentation index at: https://learn.getodin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up Azure AD for EK SSO

> Configure Azure Active Directory (Entra ID) as a SAML 2.0 Identity Provider for your on-premise EK instance.

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](/super-admin/sso/saml-sso-how-it-works.mdx) to understand how the integration works before you begin.
</Note>

## 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

<Steps>
  <Step title="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)**.
  </Step>

  <Step title="Open the SSO configuration">
    Once the application is created, navigate to **Manage → Single sign-on** and select **SAML** as the sign-on method.
  </Step>

  <Step title="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                                                   |
  </Step>

  <Step title="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` |
  </Step>
</Steps>

## Part 2 — Retrieve the Azure AD Metadata

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

<Steps>
  <Step title="Go to the SAML Certificates section">
    In your application, navigate to **Manage → Single sign-on → SAML Certificates**.
  </Step>

  <Step title="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.<br /><img src="https://mintlify.s3.us-west-1.amazonaws.com/odinai/img/sa/sso/azure-federation-metadata-url.png" alt="Azure AD Metadata URL" />
  </Step>
</Steps>

## Part 3 — Register the Domain in EK

Send a `POST` request to the domain registration endpoint:

```bash theme={null}
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.

<Steps>
  <Step title="Open the frontend environment file">
    On your on-premise deployment server, open `onprem-deployment/.env.web`.
  </Step>

  <Step title="Add the environment variable">
    Add the following line, replacing `acme.com` with your actual email domain:

    ```bash theme={null}
    VITE_SSO_ENTERPRISE_ID=acme.com
    ```
  </Step>

  <Step title="Restart the frontend services">
    ```bash theme={null}
    docker compose -f docker-compose down
    docker compose -f docker-compose up -d
    ```
  </Step>
</Steps>

## 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.