Single Sign-on und verifizierte Domains

Kolleginnen und Kollegen mit der Firmenadresse beitreten und über Entra ID, Okta, Google Workspace oder Keycloak anmelden lassen (OIDC oder SAML) — in jeder Edition.

SSO gehört zu jeder Edition. Owner und Admins richten es im Onboarding („Wie kommen die Leute dazu?“) oder in den Einstellungen ein; alles gibt es auch über die REST-API (/api/docs).

1. E-Mail-Domain verifizieren

Füg deine Domain hinzu (z. B. acme.de). Checky zeigt dir einen DNS-Eintrag: TXT _checky-verification.acme.de mit einem Wert checky-verify=….
Leg diesen TXT-Eintrag bei deinem DNS-Anbieter an.
Klick auf Verifizieren. Checky fragt den Eintrag per DNS-over-HTTPS ab (DNS_OVER_HTTPS_URL, Standard Cloudflare). „Noch nicht gefunden“ heißt: DNS ist noch nicht verteilt — später nochmal probieren. Eine Domain kann nur eine Organisation verifizieren.

Automatisch beitreten: Mit einer verifizierten Domain wird jede Person, die sich mit einer verifizierten Adresse dieser Domain anmeldet (E-Mail-Code, Magic Link, Google/Microsoft, SSO), Mitglied mit der Standardrolle (Mitglied oder Admin — nie Owner) und der Standardabteilung. Bei Self-Hosting zählt eine verifizierte Domain wie eine Einladung.

2. Identity Provider hinzufügen

Alle Domains eines Providers müssen vorher verifiziert sein. Nach dem Anlegen zeigt Checky die URLs, die du beim IdP einträgst:

Protokoll	Feld	Wert
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 braucht Issuer-URL, Client-ID und Client-Secret. Checky liest <issuer>/.well-known/openid-configuration und prüft, dass der Issuer exakt passt. SAML braucht die SSO-URL (Entry Point), die Entity ID und das Signaturzertifikat des IdP; Assertions müssen signiert sein, und die Anmeldung startet immer bei Checky (kein IdP-initiiertes SAML).

Client-Secrets werden mit APP_SECRET verschlüsselt gespeichert und nie wieder angezeigt.

Hinweise je Anbieter

Microsoft Entra ID (OIDC empfohlen): App-Registrierung, Redirect-URI vom Typ Web, ein Client-Secret und der optionale Claim email im ID-Token. Issuer https://login.microsoftonline.com/<tenant-id>/v2.0.
Okta: OIDC-Web Application mit der Redirect-URI; Issuer https://<org>.okta.com oder https://<org>.okta.com/oauth2/default. SAML: Name-ID-Format EmailAddress.
Google Workspace: OAuth-Client vom Typ Webanwendung mit internem Zustimmungsbildschirm; Issuer https://accounts.google.com.
Keycloak: vertraulicher OIDC-Client mit Standard Flow; Issuer https://<keycloak>/realms/<realm>. Internes Keycloak unter einer privaten Adresse oder http://: SSO_ALLOW_PRIVATE_IDP=true setzen und die Origin in TRUSTED_ORIGINS eintragen.

Abteilungen aus dem IdP (JIT): Gib einen Claim bzw. ein Attribut an (z. B. department). Passt der Wert zu einer bestehenden Abteilung, landet die Person bei der ersten Anmeldung dort und wird verschoben, wenn er sich ändert.

3. Anmelden

Die Anmeldeseite bietet Weiter mit SSO: Man tippt die Firmen-E-Mail ein, Checky findet den Provider und leitet zum IdP weiter. Die erste Anmeldung legt Konto und Mitgliedschaft an; ein bestehendes Konto mit derselben verifizierten E-Mail wird verknüpft.

4. SSO erzwingen (optional)

Schalte für eine Domain SSO vorschreiben ein (braucht einen aktiven Provider). Dann werden Passwort, E-Mail-Code und Magic Link für diese Domain abgelehnt und die Leute zu SSO geschickt. Passkeys gehen weiterhin.

Notzugang: Owner können sich weiterhin mit Passwort oder E-Mail-Code anmelden, wenn der IdP ausfällt. Jede solche Anmeldung landet im Audit-Log (sso.break_glass_used). Behalte mindestens einen Owner mit Passwort oder Passkey.

Noch nicht abgedeckt

SCIM-Provisionierung: Ausgeschiedene in Checky entfernen; eine Sperre beim IdP verhindert neue Anmeldungen.
Das Erzwingen blockiert keine Anmeldung mit Google/Microsoft.
IdP-initiiertes SAML und SAML Single Logout.