Single sign-on (SSO) is an Enterprise feature. Most SSO problems come down to a handful of settings, so work through this checklist first. If you still need us, you'll have everything we need to help quickly.
1. Check the basics
- You're on the Enterprise image and Settings → License shows the licence as Active.
- You know which identity provider (IdP) you use, for example Microsoft Entra ID, Okta, OneLogin, Google Workspace or ADFS.
- You know which protocol you set up: OIDC or SAML 2.0. Both are on Settings → Single sign-on, OIDC first and SAML in its own panel below.
- Allowed email domains lists your domains. Without them, new colleagues are asked for a password instead of going to SSO.
- You've tried Test sign-in on the settings page.
- Settings → Workspace → Sign-in page ends with How people sign in, which explains your setup in plain sentences. Does it match what you expect?
2. Using Microsoft Entra ID?
The fastest route is the one-click setup: on Settings → Single sign-on, choose Set up automatically with Microsoft and sign in at microsoft.com/devicelogin as a tenant admin (Global Administrator or Application Administrator). CompassDocs creates the app registration, redirect URI and a 24-month client secret for you.
- Has the client secret expired? The panel shows its expiry date.
- If you set it up by hand, is the redirect URI exactly
https://YOUR-HOST/api/ee/sso/callback? - Using
commonororganizationsas the tenant? Then you must set allowed email domains, or SSO isn't offered.
3. Using SAML?
- The IdP has the Entity ID
https://YOUR-HOST/api/ee/saml/metadataand ACS URLhttps://YOUR-HOST/api/ee/saml/acs. - The IdP sends an email address as the NameID (or an
email/mailattribute). - The IdP issuer and signing certificate in CompassDocs match your IdP. Pasting the IdP's metadata XML fills both in.
- Assertions are valid for 24 hours or less. Longer ones are refused.
- Sign-in starts from CompassDocs. Sign-ins started from the IdP's own app portal are refused.
4. Common messages
| What you see | What to do |
|---|---|
| "The sign-in attempt expired or was tampered with." (SAML) | Make sure CompassDocs is served over HTTPS and you're on a current Enterprise image. |
| A refusal saying the email isn't confirmed | An admin must confirm the address on Settings → Users with Email…, once you're sure it's that person's. |
| A refusal saying more than one account has the email | Give each account its own address with Email… on Settings → Users. |
| A refusal for an administrator's account | Administrators are never linked to SSO. Sign in with your username and Use a password instead. |
| "Your account is disabled." | An admin needs to re-enable the account on Settings → Users. |
| "This workspace signs in with single sign-on. Only its break-glass accounts can use a password." | SSO only is on. Use SSO, or a break-glass account at https://YOUR-HOST/login?local=1. |
If SSO only is on and your IdP is down, a break-glass account can sign in at https://YOUR-HOST/login?local=1. Bookmark it when you turn SSO only on.
5. What to send us
Raise a CompassDocs: Technical support (self-hosted) request at docs.felixazsolutions.com/support and choose the Sign-in, SSO, SCIM, Microsoft 365 area. Include:
- your CompassDocs version and that you're on Enterprise
- your IdP and protocol (OIDC or SAML)
- the exact error message and when it happened
- screenshots of Settings → Single sign-on and How people sign in
- app logs from
docker compose logs app, with client secrets, passwords and any tokens removed
Full details: Single sign-on.