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

# SSO Metadata Setup Guide

> Step-by-step instructions for enabling SAML 2.0 SSO on your on-premise EK instance by registering your IdP and uploading its metadata.

<Note>
  This guide is written for IT and identity administrators managing an on-premise EK instance. Any reference to "your IdP," "your IdP administrator," or "your email domain" refers to your organization's own infrastructure — not anything managed by Odin AI.
</Note>

This guide walks a Super Admin through the two-part process of enabling SAML SSO for an email domain: sharing EK's SP metadata with your IdP, then uploading your IdP's metadata back to EK.

Not familiar with how EK's SAML SSO works under the hood? Start with the [SAML SSO Overview](/super-admin/sso/saml-sso-how-it-works) first.

## Prerequisites

Before you begin, confirm the following:

* Your **on-premise EK deployment** is running with both the backend (`<your-backend-host>`) and frontend (`<your-frontend-host>`) reachable from the user's browser. The IdP only needs to receive HTTP-POST SAML responses at `<your-backend-host>/user/generic/sso/saml/acs/admin` — it does **not** need direct outbound connectivity to your backend if you supply SP metadata as a downloaded file.
* You are signed in to EK as a **Super Admin**. The SSO Metadata tab and all its underlying endpoints are restricted to Super Admins.
* Your IdP is SAML 2.0 compliant and can either consume an SP metadata XML / URL, or be manually configured with an SP entity ID and ACS URL.
* Your IdP is configured to send the user's email address as the SAML `NameID`, using the format `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. EK uses the NameID to look up or provision user accounts.
* You know the **email domain** you want to enable SSO for (e.g. `acme.com`). SSO is keyed by domain, so all users sharing that domain — `alice@acme.com`, `bob@acme.com`, etc. — will be routed to the same IdP.
* You know which **frontend SSO mode** your deployment is running. This is controlled by the `VITE_ALLOW_ONLY_SSO_LOGIN` environment variable on the frontend:
  * `true` — single-click SSO. The domain is hard-coded via `VITE_SSO_ENTERPRISE_ID` and must exactly match the domain you upload metadata for.
  * `false` *(default)* — email-modal SSO. The domain is derived from the user's email at sign-in. Multiple domains can each have their own uploaded metadata.

## Part 1 — Provide SP Metadata to Your IdP

Your IdP administrator needs to register EK as a SAML application in your IdP before you can upload any IdP metadata. EK makes this straightforward by publishing its SP metadata through a public, well-known endpoint — no manual field copying required.

### The SP Metadata Endpoint

The EK backend publishes its SP metadata at:

```
https://<your-backend-host>/saml/well-known/sp-metadata
```

The response is a standards-compliant SAML 2.0 `EntityDescriptor` containing your instance's Entity ID, ACS URL, required NameID format, and SP signing certificate (when configured). The endpoint is unauthenticated by design so your IdP can fetch it directly.

<Tip>
  For the full reference — endpoint behavior, sample XML, guaranteed vs. optional components, and the backend environment variables (`CUSTOM_ENTITY_ID_FOR_GENERIC_SSO`, `SAML_SP_CERT_FILE`, `SAML_SP_KEY_FILE`) an on-premise operator can tune at deployment time — see [SP Metadata Endpoint](/super-admin/sso/sp-metadata-endpoint).
</Tip>

### How to Share the SP Metadata

<AccordionGroup>
  <Accordion title="Option A — Provide the URL">
    If your IdP can reach the EK backend host, send your IdP administrator the well-known URL directly:

    ```
    https://<your-backend-host>/saml/well-known/sp-metadata
    ```

    Most modern IdPs (Okta, Entra ID, Ping, OneLogin, Auth0, etc.) can import SP metadata from a URL and will auto-populate the SP configuration — Entity ID, ACS URL, NameID format, and signing certificate — from it.
  </Accordion>

  <Accordion title="Option B — Download and Hand Off the File">
    If your IdP cannot reach the backend host directly — common in segmented networks, air-gapped environments, or when your IdP is a SaaS outside your corporate perimeter — download the XML and pass it to your IdP administrator out of band:

    ```bash theme={null}
    curl -o ek_sp_metadata.xml https://<your-backend-host>/saml/well-known/sp-metadata
    ```

    Your IdP administrator uploads `ek_sp_metadata.xml` in the IdP's SAML application configuration screen. You only need to re-export and re-upload when the SP configuration changes — typically a backend hostname change, SP signing certificate rotation, or Entity ID override change.
  </Accordion>
</AccordionGroup>

### Manual Configuration (When the IdP Cannot Consume Metadata)

If your IdP requires fields to be entered manually, use the values from the SP metadata XML. The most commonly required fields are:

| Field                                        | Value                                                                                                                                                                                  |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entity ID / Audience**                     | The `entityID` attribute on `<md:EntityDescriptor>` in the SP metadata response. Defaults to the ACS URL; can be overridden at deployment time via `CUSTOM_ENTITY_ID_FOR_GENERIC_SSO`. |
| **ACS URL / Reply URL / Single Sign-On URL** | `https://<your-backend-host>/user/generic/sso/saml/acs/admin` — always the backend host, never the frontend.                                                                           |
| **Binding**                                  | HTTP-POST                                                                                                                                                                              |
| **NameID format**                            | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`                                                                                                                               |
| **Sign AuthnRequests**                       | `true` if your EK deployment has an SP certificate configured (advertised in the metadata as `AuthnRequestsSigned`); otherwise `false`.                                                |
| **Want Assertions Signed**                   | `true` — always. EK requires signed assertions.                                                                                                                                        |

<Warning>
  The IdP must send the user's email address as the SAML `NameID`. If the IdP sends an opaque internal ID instead, sign-in will either fail or create incorrectly-keyed accounts.
</Warning>

### What Your IdP Administrator Needs to Give Back

Once the SAML application is created in your IdP, ask your IdP administrator for the **IdP SAML metadata XML**. This is the file you will upload in Part 2.

Almost every IdP can produce this file. Common names for it in IdP UIs:

| IdP                                           | Where to Find It                                                          |
| --------------------------------------------- | ------------------------------------------------------------------------- |
| **Okta**                                      | *"Identity Provider metadata"* link on the application's *Sign On* tab    |
| **Entra ID / Azure AD**                       | *"Federation Metadata XML"* download under the SSO blade                  |
| **Ping / OneLogin / Auth0 / ADFS / Keycloak** | Typically labelled *"Metadata"* or *"SAML Metadata"*, downloadable as XML |

The XML must be a valid SAML 2.0 `EntityDescriptor` containing an `IDPSSODescriptor` with at least the IdP's `entityID`, a `SingleSignOnService` location and binding, and the IdP's signing certificate so EK can verify assertions.

## Part 2 — Upload the IdP Metadata

With the IdP metadata XML in hand, you can now register it against an email domain in your EK instance.

### Open the SSO Metadata Tab

<Steps>
  <Step title="Sign in to EK">
    Sign in to EK as a Super Admin.
  </Step>

  <Step title="Open the Super Admin Dashboard">
    Go to your account menu in the top right and click **Super Admin Dashboard**.
  </Step>

  <Step title="Go to the SSO Metadata tab">
    Switch to the **SSO Metadata** tab. You'll see a table of existing domain → metadata mappings with three columns:

    * **SSO Domain** — the email domain the metadata is registered against (e.g. `acme.com`).
    * **Updated** — the last time metadata for that domain was uploaded or replaced.
    * **Actions** — controls to download, update, or delete the stored metadata for that row.

    Use the search box at the top right to filter by domain. The table is sortable by **SSO Domain** or **Updated**.
  </Step>
</Steps>

### Add Metadata for a New Domain

<Steps>
  <Step title="Open the Add Metadata dialog">
    Click **Add Metadata** in the top right of the SSO Metadata tab. If no domains are configured yet, you can also click it from the empty-state card.<br /><img src="https://mintlify.s3.us-west-1.amazonaws.com/odinai/img/sa/sso/add-metadata-dialog.png" alt="Add Metadata Dialog" />
  </Step>

  <Step title="Enter the email domain">
    In the **SSO Team Email Domain** field, enter the domain SSO should apply to — for example `acme.com`. Use only the domain portion of the email address: no `@`, no path, no scheme. The value is normalized to lowercase on save.

    <Warning>
      If your deployment runs in single-click SSO mode (`VITE_ALLOW_ONLY_SSO_LOGIN=true`), this value must exactly match `VITE_SSO_ENTERPRISE_ID`. A mismatch means the SSO button will redirect users to a domain with no uploaded metadata, and authentication will fail at the backend.
    </Warning>
  </Step>

  <Step title="Choose your upload method and provide the XML">
    <Tabs>
      <Tab title="Upload File">
        Select the `.xml` file your IdP administrator provided. Only files with an `.xml` extension are accepted.
      </Tab>

      <Tab title="Paste XML Content">
        Paste the full IdP metadata XML directly into the textarea. The content must start with `<?xml ...?>` or `<EntityDescriptor ...>`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Submit">
    Click **Upload Metadata**. The dialog closes, a toast notification confirms the upload, and the new domain appears in the table.
  </Step>
</Steps>

<Note>
  Each domain can have at most one active IdP metadata document at a time. Re-uploading for the same domain replaces the existing metadata — see *Update Metadata for an Existing Domain* below.
</Note>

### Update Metadata for an Existing Domain

IdPs rotate signing certificates and occasionally change endpoints. When this happens, coordinate with your IdP administrator so the new XML is uploaded to EK **before** the IdP starts signing assertions with the new key.

<Steps>
  <Step title="Find the domain row">
    Locate the domain in the SSO Metadata table.
  </Step>

  <Step title="Click Update">
    Click **Update** in the row's Actions column.
  </Step>

  <Step title="Provide the new XML">
    The **Update SSO Metadata** dialog opens with the domain pre-filled and locked. You cannot change the domain on an update — if you need to repurpose the entry, delete it and re-add it. Choose your upload method and provide the new XML as you would for a new domain.
  </Step>

  <Step title="Submit">
    Click **Update Metadata**. The replacement takes effect immediately — the next SSO sign-in for that domain will use the new metadata.
  </Step>
</Steps>

### Download the Currently Stored Metadata

Click the **download icon** in the row's Actions column. The file is saved as `<domain>_saml_metadata.xml`.

Useful for:

* Confirming which IdP metadata is currently active on this EK instance.
* Providing a copy to your security or compliance team for audit.
* Taking a backup before performing an update.

### Delete Metadata for a Domain

<Steps>
  <Step title="Click Delete">
    Click **Delete** in the row's Actions column.
  </Step>

  <Step title="Confirm">
    In the confirmation dialog, read the warning, tick the acknowledgement checkbox — *"I understand this will disable SSO for all users in this domain"* — and click **Delete**.
  </Step>
</Steps>

<Danger>
  Deletion is irreversible. After deleting:

  * EK no longer has IdP metadata on file for that domain.
  * Any new SSO sign-in attempts from `@<domain>` users will fail.
  * Existing accounts — email/password, Google OAuth, or accounts provisioned by previous SSO sign-ins — are **not** deleted, but those users will no longer be able to sign in via SSO.

  To restore SSO for the domain, you will need to upload the IdP metadata XML again.
</Danger>

## End-to-End Checklist

Use this as a runbook when enabling SAML SSO for a new email domain on your on-premise EK instance.

<Steps>
  <Step title="Share EK SP metadata with your IdP administrator">
    Give your IdP administrator the SP metadata from your EK backend — not the frontend host.

    * If your IdP can reach the backend directly, point them at:
      ```
      https://<your-backend-host>/saml/well-known/sp-metadata
      ```
    * Otherwise, download the XML and pass it out of band:
      ```bash theme={null}
      curl -o ek_sp_metadata.xml https://<your-backend-host>/saml/well-known/sp-metadata
      ```
  </Step>

  <Step title="Your IdP administrator creates the SAML application">
    Once they have the SP metadata, your IdP administrator registers EK as a SAML application in your IdP. Confirm with them that:

    * The NameID is set to the user's email address.
    * Assertions are signed.
    * The audience / Entity ID matches the value in EK's SP metadata.
  </Step>

  <Step title="Receive the IdP metadata XML">
    Ask your IdP administrator for the IdP metadata XML once the application is created. This is the file you will upload in the next step.
  </Step>

  <Step title="Upload the IdP metadata to EK">
    Sign in to EK as a Super Admin, open **Super Admin Dashboard → SSO Metadata**, and click **Add Metadata**. Enter the email domain and upload the XML.
  </Step>

  <Step title="Test sign-in">
    Test with a real `@<domain>` user. If the user authenticates successfully but is denied access, check your SAML Access Controls configuration — see the [**SAML Access Controls**](/super-admin/sa-access-controls) guide.
  </Step>

  <Step title="Document the change">
    Record the following in your internal change-management system: the domain, the IdP type, the date of upload, and which Super Admin performed the upload.
  </Step>

  <Step title="Schedule a metadata refresh">
    Note when your IdP signing certificate is due to rotate and set a reminder to upload updated metadata before that date. Use the **Update** action in the SSO Metadata tab when new metadata is available.
  </Step>
</Steps>

***

Running into issues? See the [SSO Troubleshooting & Reference](/super-admin/sso/saml-sso-troubleshooting) guide.