Single Sign-On — Cmssy Docs

Overview

Single sign-on lets the people in your organization reach the Cmssy admin through your own identity provider instead of a Cmssy password. Cmssy speaks OpenID Connect, so Google Workspace, Microsoft Entra ID and Okta all work.

Three things make it up, and they are configured in this order:

An identity provider — the issuer, a client id and a client secret.
One or more email domains, each proven yours with a DNS TXT record.
Optionally, enforcement — members of a verified domain can no longer sign in with a password.

SSO is part of the Enterprise plan. On any other plan the screen explains the feature but the settings stay closed.

Before you start

You need to be an owner or admin of the organization.
You need access to the DNS zone of the email domain you want to claim, to publish one TXT record.
You need permission to register an application in your identity provider.

Step 1 — register Cmssy with your provider

Create an OpenID Connect application in your provider and set the redirect URI to:

https://www.cmssy.io/api/auth/sso/callback

Request the scopes openid, email and profile. Your provider will give you a client id and a client secret.

Google Workspace

The issuer is the same for every tenant:

https://accounts.google.com

Microsoft Entra ID

The issuer is tenant-specific — copy the tenant id from the app registration overview:

https://login.microsoftonline.com/<tenant-id>/v2.0

Entra frequently omits the email_verified claim for work and school accounts. Cmssy accepts a token without that claim, because the trust anchor is the domain you verified below, not a claim the provider may or may not send. A token that reports email_verified: false is still refused.

Okta

https://<your-org>.okta.com

Step 2 — fill in the provider

Open Dashboard → your organization → Single sign-on and fill in:

Display name — what your people will recognise, e.g. Acme Entra.
Issuer URL — from the section above.
Client ID and Client secret — from your provider.

Saving checks the issuer immediately by fetching its OpenID configuration, so a typo fails while you are looking at it rather than at somebody's first sign-in. The secret is encrypted at rest and never sent back to the browser — once stored, the field shows a placeholder and stays empty until you type a replacement.

Test connection re-checks the issuer. It proves the issuer answers; it does not prove the client id, the secret or the redirect URI, because only a real sign-in exercises those.

Step 3 — verify your email domain

In Email domains, add the domain your people use, e.g. acme.com. Cmssy shows a TXT record:

cmssy-verification=<your-token>

Publish it on the domain apex in your DNS, wait for it to propagate, then press Verify.

Until a domain is verified it does nothing: it is invisible to sign-in and to the login screen's provider lookup. This is deliberate — without proof of ownership, any organization could claim someone else's domain and take over their accounts.

A domain that another organization has already verified cannot be claimed. Free mail providers and public suffixes are rejected outright.

Step 4 — turn SSO on

Once the provider is complete and a domain is verified, switch SSO enabled on. From that moment, typing an address on a verified domain into the Cmssy login screen sends that person to your identity provider.

Create accounts automatically is on by default: someone signing in for the first time gets an account and joins your organization with the default member role. Turn it off if you would rather invite people yourself — unknown addresses are then refused.

Step 5 — require SSO (optional)

Require SSO stops members of a verified domain from signing in with a password. Password login, signup, password reset and Google/Apple social login are all refused for those addresses.

You can only switch it on when three things are true:

you are the organization owner, not just an admin
somebody has already signed in successfully through your provider
you, the owner, have a password

The last two exist for the same reason: if your identity provider breaks, expires or is misconfigured, somebody has to be able to get back in. The owner keeps password access permanently for exactly that case — so treat the owner account accordingly.

Switching SSO off also switches enforcement off. An organization can never end up enforcing an identity provider it has disabled.

How signing in works

A person types their work address on the Cmssy login screen.
Cmssy checks whether the domain belongs to an organization with SSO enabled, and sends them to your provider if it does.
They authenticate with you — including whatever MFA and conditional access you enforce.
Your provider returns them to Cmssy, which verifies the token against your issuer's signing keys and signs them in.

The address your provider returns has to sit on one of your verified domains. A guest account from another tenant is refused, even if your provider vouches for it.

People whose domain has no SSO see the ordinary password form — nothing changes for them.

Troubleshooting

Check that the domain is verified (not just added), that SSO enabled is on, and that the address really uses that domain.

“Single sign-on did not complete”

The exchange with your provider failed. The usual causes are a redirect URI that does not match exactly, a rotated client secret, or a sign-in that took longer than ten minutes to come back.

“… is not on a domain this organization has verified”

Your provider returned an address outside your verified domains — commonly a guest or personal account in the same tenant.

Enforcement will not switch on

Read the error: it names which of the three conditions failed. Most often nobody has signed in through the provider yet.

Our plan changed and SSO stopped

SSO requires the Enterprise plan. Your configuration and verified domains are kept, and reading and removing them keeps working, so nothing is lost while you sort the plan out.