Single sign-on: before you contact us

Updated

A checklist of what to check and gather when single sign-on isn't working, with fixes for the most common errors.

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 common or organizations as 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/metadata and ACS URL https://YOUR-HOST/api/ee/saml/acs.
  • The IdP sends an email address as the NameID (or an email / mail attribute).
  • 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 seeWhat 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 confirmedAn 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 emailGive each account its own address with Email… on Settings → Users.
A refusal for an administrator's accountAdministrators 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.
Locked out?

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.

Still need help?

Raise a request and we'll get back to you by email.

New request