Single sign-on (SSO)

Choosing a provider

Since 0.97 the SSO panel has a vendor choice. Picking Google sets the sign-in authority for you; picking Microsoft (the default, and what every existing setup stays on) builds it from your tenant. Generic leaves the authority for you to enter. Nothing about an existing configuration changes.

Enterprise

SSO requires an Enterprise build and a license that includes the sso entitlement. On Community builds the settings page shows an overview only. The same sso entitlement covers both OIDC and SAML — there’s nothing extra to buy to use one or the other.

With SSO enabled, the login page gains a Sign in with… button. People authenticate with your identity provider; CompassDocs validates the response and signs them in — no separate password to manage. Accounts can be created automatically on first sign-in, and existing accounts are matched by email.

CompassDocs speaks two protocols, and you can run either or both at once (the login page shows a button for each configured method):

• OpenID Connect (OIDC) — first-class for Microsoft Entra ID, with a one-click setup, and works with any spec-compliant OIDC provider.
• SAML 2.0 — for Okta, OneLogin, Google Workspace, Active Directory Federation Services (ADFS), Entra SAML apps, and any other SAML IdP.

Not sure which to pick? If your IdP offers both, OIDC is a touch simpler to wire up. Otherwise use whichever your IdP supports — the end-user experience and the account model are identical.

---

OpenID Connect (Microsoft Entra ID & others)

The fast way — one click

On Settings → Single sign-on, click Set up automatically with Microsoft, then sign in at microsoft.com/devicelogin with the code shown, as a tenant admin (Global Administrator or Application Administrator). CompassDocs creates the app registration — with the redirect URI already set — plus a 24-month client secret and the service principal, and fills in and enables the configuration for you. The one-time sign-in token is discarded afterward; CompassDocs keeps no standing Microsoft permission.

The panel shows the secret’s expiry date — set a reminder to rotate it before then. Prefer to do it by hand (or your tenant blocks the device-code flow)? Follow the manual steps below.

1. Register an app in Entra (manual)

In the Microsoft Entra admin center → Identity → Applications → App registrations → New registration:

• Name: e.g. CompassDocs
• Supported account types: Accounts in this organizational directory only (single tenant)
• Redirect URI: choose Web and enter https://YOUR-COMPASSDOCS-HOST/api/ee/sso/callback

After creating it, note the Application (client) ID and Directory (tenant) ID from the Overview page.

Then under Certificates & secrets → New client secret, create a secret and copy its value immediately (it’s only shown once).

That’s all — sign-in uses plain OpenID Connect, so no API permissions or admin consent are required. (If you also use the Microsoft 365 directory sync, that’s a separate app registration with its own permissions.)

2. Configure CompassDocs

Under Settings → Single sign-on, enter the Tenant ID, Client ID, and Client secret (the secret is write-only — once saved, it’s never shown again). Then choose your policies:

• Create accounts on first sign-in — new people get an account automatically, with the role you pick (default viewer). Turn it off to allow only people you’ve already added.
• Allowed email domains — optionally restrict sign-in to your domains (e.g. acme.com, acme.co.uk). Leave blank to allow any account your IdP authenticates.
• Enable “Sign in with Microsoft” — turns the button on.
• SSO only — hides the username/password form entirely.

Use Test sign-in to run the flow yourself before rolling it out.

Other OIDC providers

Any spec-compliant OIDC provider works. Under Advanced, set the custom OIDC authority to your provider’s issuer (e.g. https://your-org.okta.com/oauth2/default) — CompassDocs reads everything else from the provider’s discovery document. The redirect URI to register with the provider is the same: https://YOUR-HOST/api/ee/sso/callback.

---

SAML 2.0 (Okta, OneLogin, Google Workspace, ADFS & others)

SAML lives in its own panel on Settings → Single sign-on, below the Microsoft/OIDC one. It adds a second button to the login page (labelled Single sign-on (SAML) by default — you can rename it).

CompassDocs is the service provider (SP); your IdP is the identity provider. Setup is a two-way exchange: you give the IdP a couple of URLs, and the IdP gives you its sign-on URL, issuer, and signing certificate.

1. Give your IdP the SP details

The panel shows two values, generated from your CompassDocs domain — copy them into your IdP when you create the app:

IdP field asks for…	Use this value
Entity ID / Audience URI	https://YOUR-HOST/api/ee/saml/metadata
ACS URL / Reply / SSO URL	https://YOUR-HOST/api/ee/saml/acs

CompassDocs also publishes standard SP metadata XML at https://YOUR-HOST/api/ee/saml/metadata — many IdPs let you paste that URL to configure everything at once.

Set the IdP to release an email address as the NameID (or as an email / mail attribute) — that’s how people are matched to accounts. A display name (displayName, or givenName + surname) is used for the account name when present.

2. Give CompassDocs the IdP details

Back in the SAML panel, the fastest path is Paste your IdP’s metadata XML — download the IdP’s federation metadata (Okta, ADFS, and most others offer a metadata URL or file) and paste it. CompassDocs extracts the three values it needs:

• IdP sign-on URL — where CompassDocs sends people to authenticate.
• IdP issuer (entity ID) — must match the <Issuer> in the IdP’s responses; assertions from any other issuer are refused.
• IdP signing certificate — the X.509 cert (PEM or bare base64) used to verify every assertion’s signature.

You can also fill these three fields by hand. Then set your policies — create accounts on first sign-in and default role, allowed email domains, and the login button label — and tick Enabled on the login page. Use Test sign-in to run the flow yourself first.

Provider quick-reference

Provider	Where to add the app
Okta	Applications → Create App Integration → SAML 2.0
OneLogin	Applications → Add App → search SAML Custom Connector (Advanced)
Google Workspace	Admin console → Apps → Web and mobile apps → Add custom SAML app
ADFS	Relying Party Trusts → Add → enter the SP metadata URL
Entra ID (SAML)	Enterprise applications → New → Create your own application

In every case the SP values from step 1 are what the IdP needs, and CompassDocs maps the email NameID to an account exactly as OIDC does.

---

How accounts are matched

This is identical for OIDC and SAML:

1. A returning SSO user is recognized by their immutable directory ID (the OIDC subject, or the SAML NameID) — renames and email changes are safe.
2. Otherwise, if an account with the same email exists, the SSO identity is linked to it. The account keeps its role, and a local password (if set) keeps working alongside SSO.
3. Otherwise a new account is provisioned (if enabled). SSO-provisioned accounts have no password — they can only sign in through your IdP.

Roles are managed in CompassDocs (Settings → Users & roles), not by the IdP — an admin can promote or disable any account, including SSO ones. Disabled accounts can’t sign in, even with valid IdP credentials.

Automatic provisioning (SCIM)

Pair SSO with SCIM provisioning (enterprise) and Entra also manages the account lifecycle: new hires appear automatically, and departed employees are deactivated with their sessions revoked — no manual cleanup.

Locked out? (break-glass)

If SSO only is on and your IdP is down or misconfigured, local sign-in still works at the API level:

curl -X POST https://YOUR-HOST/api/auth/login \
  -H "content-type: application/json" \
  -d '{"username":"admin","password":"…"}'

…then open the app in the same browser session, or simply turn SSO only back off from Settings → Single sign-on.

Security notes

• OIDC is authorization code + PKCE, with state and nonce checks bound to a short-lived, HTTP-only cookie. ID tokens are fully validated: RS256 signature against the provider’s published keys, issuer, audience, expiry, and nonce.
• SAML responses are validated against the configured IdP signing certificate (audience and timestamps included), and each sign-in is bound to the exact request the browser started — a flow cookie carries the AuthnRequest ID and RelayState, and both must match, so replayed or unsolicited (IdP-initiated) responses are refused. The expected issuer is enforced even when a signature verifies.
• Both protocols mint the same session as a password login, honoring your session-timeout and secure-cookie settings.
• Sign-ins, provisioned accounts, and settings changes all land in the audit log — auth.sso_login, user.sso_provisioned, and settings.sso / settings.saml.