SSO Troubleshooting & Reference

This article covers permissions, quick reference values, and solutions to common SSO issues. For setup instructions, see the 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.

Quick Reference

Backend Host

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

Frontend Host

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

SP Metadata URL

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

Share this with your IdP administrator to register EK as a SAML application.

ACS URL

https://<your-backend-host>/user/generic/sso/saml/acs/admin

Where your IdP POSTs SAML responses. Always the backend host — never the frontend.

SP-Initiated SSO Entry Point

https://<your-backend-host>/sso/login?enterprise_id=<email-domain>

The backend endpoint the frontend redirects to when a user initiates SSO.

Required NameID Format

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Your IdP must send the user's email address in this format.

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

"Please enter a valid domain" 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.

"File must be an XML file" 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.

"Content does not appear to be valid XML" 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.

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.

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 guide for details on Allow Any New Users vs Restrict to SAML Metadata and automated team/project assignment rules.

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.

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.

Single-click SSO button does nothing (or shows "Could not determine domain for SSO login")

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.

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

Email-modal SSO shows "Your organization is not configured for SSO login"

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.

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.