Skip to main content
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.
ActionRequired Role
View the SSO Metadata tabSuper 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
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

VariableDescription
VITE_ALLOW_ONLY_SSO_LOGINtrue for single-click SSO, false (default) for email-modal SSO.
VITE_SSO_ENTERPRISE_IDSingle-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

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