Single sign-on and verified domains

Let colleagues join with their company address and sign in through Entra ID, Okta, Google Workspace or Keycloak (OIDC or SAML) — in every edition.

SSO is part of every edition. Owners and admins set it up in the onboarding (“How should people join?”) or in Settings; everything is also available in the REST API (/api/docs).

1. Verify your email domain

  1. Add your domain (e.g. acme.com). Checky shows a DNS record: TXT _checky-verification.acme.com with a value checky-verify=….
  2. Publish that TXT record at your DNS provider.
  3. Click Verify. Checky looks the record up via DNS-over-HTTPS (DNS_OVER_HTTPS_URL, default Cloudflare). “Not found yet” means DNS hasn’t propagated — try again later. A domain can only be verified by one organization.

Auto-join: with a verified domain, anyone who signs in with a verified address of that domain (email code, magic link, Google/Microsoft, SSO) becomes a member with the default role (member or admin — never owner) and the default department. On a self-hosted install a verified domain counts as an invitation.

2. Add your identity provider

Every domain of a provider must be verified first. After you create the provider, Checky shows the URLs to register at your IdP:

Protocol Field Value
OIDC Redirect URI <BASE_URL>/api/auth/sso/callback/<providerId>
SAML ACS URL <BASE_URL>/api/auth/sso/saml2/sp/acs/<providerId>
SAML SP Entity ID <BASE_URL>/api/auth/sso/saml2/sp/metadata?providerId=<providerId>

OIDC needs the issuer URL, client ID and client secret. Checky reads <issuer>/.well-known/openid-configuration and checks that the issuer matches exactly. SAML needs the IdP’s SSO URL (entry point), entity ID and signing certificate; assertions must be signed, and sign-in always starts at Checky (no IdP-initiated SAML).

Client secrets are encrypted with APP_SECRET and never shown again.

Provider notes

  • Microsoft Entra ID (OIDC recommended): App registration, redirect URI of type Web, a client secret, and the optional email claim in the ID token. Issuer https://login.microsoftonline.com/<tenant-id>/v2.0.
  • Okta: OIDC Web Application with the redirect URI; issuer https://<org>.okta.com or https://<org>.okta.com/oauth2/default. SAML: Name ID format EmailAddress.
  • Google Workspace: OAuth client of type Web application with an Internal consent screen; issuer https://accounts.google.com.
  • Keycloak: confidential OIDC client with standard flow; issuer https://<keycloak>/realms/<realm>. Internal Keycloak on a private address or http://: set SSO_ALLOW_PRIVATE_IDP=true and add its origin to TRUSTED_ORIGINS.

Departments from the IdP (JIT): name a claim/attribute (e.g. department); when its value matches an existing department, people are placed there on first sign-in and moved when it changes.

3. Signing in

The sign-in page offers Continue with SSO: people type their work email, Checky finds the provider and sends them to the IdP. The first sign-in creates the account and membership; an existing account with the same verified email is linked.

4. Enforce SSO (optional)

Turn on Require SSO for a domain (needs an active provider). Then password, email code and magic link sign-ins for that domain are refused and people are sent to SSO. Passkeys still work.

Break-glass: owners can still sign in with password or email code when the IdP is down. Each such sign-in is recorded in the audit log (sso.break_glass_used). Keep at least one owner with a password or passkey.

Not covered yet

  • SCIM provisioning: remove leavers in Checky; blocking them at the IdP stops new sign-ins.
  • Enforcement does not block Google/Microsoft social sign-in.
  • IdP-initiated SAML and SAML single logout.

Stuck? We help with installations: contact us