> ## 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 Troubleshooting & Reference

> Permissions, quick reference URLs, and troubleshooting guidance for SAML SSO on your on-premise EK instance.

This article covers permissions, quick reference values, and solutions to common SSO issues. For setup instructions, see the [SSO Metadata Setup Guide](/super-admin/sso/saml-sso-metadata-setup-guide).

## Permissions

All SSO metadata management actions are restricted to Super Admins, with one exception: a team admin can upload IdP metadata via file for their own team's domain.

| Action                                                                       | Required Role                                                                       |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| View the SSO Metadata tab                                                    | Super Admin                                                                         |
| Upload IdP metadata via file (`POST /admin/saml-metadata/upload`)            | Super Admin, or a team admin whose `sso_domain` matches their team's `email_domain` |
| Upload IdP metadata via pasted XML (`POST /admin/saml-metadata/upload-text`) | Super Admin only                                                                    |
| Download stored metadata (`GET /admin/saml-metadata/download`)               | Super Admin                                                                         |
| Delete stored metadata (`DELETE /admin/saml-metadata/delete`)                | Super Admin                                                                         |

<Note>
  The SP metadata endpoint at `/saml/well-known/sp-metadata` is public by design. It contains no secrets — only the SP entity ID, ACS URL, NameID format, and public signing certificate.
</Note>

## Quick Reference

<CardGroup cols={2}>
  <Card title="Backend Host" icon="server">
    `<your-backend-host>` (e.g. `ek-api.corp.acme.com`)

    Handles all SAML traffic — SP metadata, SSO initiation, and the ACS endpoint. **This is the only host your IdP needs to know about.**
  </Card>

  <Card title="Frontend Host" icon="globe">
    `<your-frontend-host>` (e.g. `ek.corp.acme.com`)

    The web UI your users open. Configured on the backend via `FRONTEND_ROOT_URL`. **Never appears in IdP configuration.**
  </Card>

  <Card title="SP Metadata URL" icon="link">
    ```
    https://<your-backend-host>/saml/well-known/sp-metadata
    ```

    Share this with your IdP administrator to register EK as a SAML application.
  </Card>

  <Card title="ACS URL" icon="arrow-right-to-bracket">
    ```
    https://<your-backend-host>/user/generic/sso/saml/acs/admin
    ```

    Where your IdP POSTs SAML responses. Always the backend host — never the frontend.
  </Card>

  <Card title="SP-Initiated SSO Entry Point" icon="right-to-bracket">
    ```
    https://<your-backend-host>/sso/login?enterprise_id=<email-domain>
    ```

    The backend endpoint the frontend redirects to when a user initiates SSO.
  </Card>

  <Card title="Required NameID Format" icon="id-card">
    ```
    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    ```

    Your IdP must send the user's email address in this format.
  </Card>
</CardGroup>

### Frontend SSO Mode Environment Variables

| Variable                    | Description                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| `VITE_ALLOW_ONLY_SSO_LOGIN` | `true` for single-click SSO, `false` (default) for email-modal SSO.                                 |
| `VITE_SSO_ENTERPRISE_ID`    | Single-click mode only. Must match a domain that has IdP metadata uploaded in the SSO Metadata tab. |

* **Where to upload IdP metadata?** Super Admin Dashboard → **SSO Metadata** tab → **Add Metadata** / **Update**
* **One document per domain.** Re-uploading replaces existing metadata. Deleting disables SSO for that domain.
* **Required role?** Super Admin for all actions, except team admins can upload via file for their own team's domain.

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Please enter a valid domain&#x22; error">
    The **SSO Team Email Domain** field expects a bare domain like `acme.com` or `eu.acme.co.uk`. Remove any leading `@`, `https://`, paths, or port numbers before submitting.
  </Accordion>

  <Accordion title="&#x22;File must be an XML file&#x22; error">
    The file uploader only accepts files with an `.xml` extension. If your IdP provided the metadata as a `.txt` file or without an extension, either rename it to `.xml` or switch to the **Paste XML Content** option instead.
  </Accordion>

  <Accordion title="&#x22;Content does not appear to be valid XML&#x22; error">
    When using **Paste XML Content**, the pasted content must start with `<?xml` or `<` after trimming whitespace. Make sure you copied the full metadata document and that no preamble or commentary was included.
  </Accordion>

  <Accordion title="Sign-in succeeds with the IdP but EK rejects the assertion">
    This is almost always caused by one of the following:

    * **Certificate mismatch** — the IdP signing certificate in the uploaded metadata no longer matches the certificate your IdP is actually using. This typically happens after an IdP certificate rotation. Get fresh metadata from your IdP administrator and use **Update**.
    * **Wrong NameID format** — the IdP is not sending the email address as the NameID. Confirm the format is set to `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` on the IdP side.
    * **Entity ID mismatch** — the audience or Entity ID configured in your IdP does not match your EK instance's Entity ID. Re-share the EK SP metadata XML and have your IdP administrator re-import it.
  </Accordion>

  <Accordion title="User signs in successfully but is denied access">
    This is controlled by **Super Admin → Access Controls**, not the SSO Metadata tab. See the [**SAML Access Controls**](/super-admin/sa-access-controls) guide for details on `Allow Any New Users` vs `Restrict to SAML Metadata` and [automated team/project assignment rules](/super-admin/sa-automated-management).
  </Accordion>

  <Accordion title="IdP-initiated SSO is not working">
    By default, EK only accepts SAML responses initiated from its own `/sso/login` endpoint — meaning SP-initiated SSO only. To enable IdP-initiated (unsolicited) SSO, the on-premise operator must set `ALLOW_IDP_INITIATED_SSO=true` on the EK backend and restart the service. This is a deployment-level setting, not something configurable in the SSO Metadata tab.
  </Accordion>

  <Accordion title="IdP configured with the frontend host instead of the backend host">
    If the IdP application was configured with the EK frontend hostname for the ACS URL or Entity ID, SAML responses will be sent to the wrong service and authentication will silently fail — usually showing a 404 or a generic error page after the IdP login screen.

    Ask your IdP administrator to confirm:

    * The **ACS URL** is `https://<your-backend-host>/user/generic/sso/saml/acs/admin`.
    * The **Entity ID / Audience** matches the `entityID` in `https://<your-backend-host>/saml/well-known/sp-metadata`.

    The frontend host should never appear in the IdP's SAML application configuration.
  </Accordion>

  <Accordion title="Single-click SSO button does nothing (or shows &#x22;Could not determine domain for SSO login&#x22;)">
    `VITE_SSO_ENTERPRISE_ID` is not set on the frontend. Set it to the email domain you have uploaded IdP metadata for, then redeploy or restart the frontend so the value takes effect.
  </Accordion>

  <Accordion title="Single-click SSO button redirects but SSO fails at the backend">
    `VITE_SSO_ENTERPRISE_ID` is set but does not match any domain with uploaded metadata in the SSO Metadata tab. Fix this by either:

    * Uploading IdP metadata for the domain currently in `VITE_SSO_ENTERPRISE_ID` — recommended, as it keeps your frontend configuration unchanged.
    * Updating `VITE_SSO_ENTERPRISE_ID` to match a domain that already has metadata uploaded, then redeploying or restarting the frontend.

    The two values must match exactly (case-insensitive).
  </Accordion>

  <Accordion title="Email-modal SSO shows &#x22;Your organization is not configured for SSO login&#x22;">
    The user's email domain has no IdP metadata uploaded in the SSO Metadata tab. Either upload metadata for that domain, or ask the user to sign in using email/password or OAuth instead.
  </Accordion>

  <Accordion title="Users complete SSO but land on the wrong page or get a redirect error">
    After a successful SAML response, EK redirects the user to the frontend URL defined by `FRONTEND_ROOT_URL` on the backend. If this variable is unset, points to the wrong host, or uses the wrong scheme or port, the user will appear to finish authentication but end up on a broken page.

    Have your on-premise operator confirm that `FRONTEND_ROOT_URL` matches `https://<your-frontend-host>` exactly — correct scheme, correct port, no trailing slash issues.
  </Accordion>
</AccordionGroup>