Wie richte ich SSO/OIDC für einen Mandanten ein?

Ab Tarif Pro

Kurzantwort

Lege unter Verwaltung → SSO eine Provider-Konfiguration für deinen Mandanten an: Anzeigename, Discovery-URL des IdP, Client-ID und Client-Secret, dann aktivieren. Im IdP registrierst du Notory als OIDC-Client mit der Redirect-URI https://<deine-instanz>/api/v1/auth/sso/callback. Optional übernimmt Notory neue Benutzer automatisch per JIT-Provisionierung und leitet ihre Rolle aus IdP-Gruppen ab. SSO-Provider gelten immer pro Mandant.

Voraussetzungen

Benötigte Rolle Administrator (des Mandanten)

Provider anlegen/ändern erfordert Schreibrechte, das Löschen die Rolle Administrator. Zusätzlich muss das Feature sso lizenziert sein (ab Pro), sonst antworten alle /sso/…-Endpunkte mit 403.

Vom IdP brauchst du: die Discovery-URL (z. B. https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration), Client-ID und Client-Secret. Der IdP muss E-Mail-Adressen als verifiziert ausgeben (email_verified).

Anleitung

GUI (Weboberfläche)

1. SSO-Bereich öffnen. Verwaltung → SSO. Die Beschreibung erinnert daran: „Identity-Provider pro Mandant konfigurieren. Vollständiger Login benötigt einen erreichbaren IdP.” Klicke auf Provider anlegen.

   Screenshot ausstehend admin-sso-01 SSO-Verwaltung mit der Liste der Identity-Provider des Mandanten

   Die SSO-Verwaltung: Identity-Provider werden pro Mandant konfiguriert.

2. Provider konfigurieren. Fülle aus:

   • Anzeigename: erscheint später auf dem Login-Button („Anmelden mit …”).
   • Protokoll: oidc (Standard; der vollständige Login-Flow ist für OIDC implementiert, SAML-Felder sind vorbereitet).
   • Discovery-URL, Client-ID, Client-Secret: aus deinem IdP.
   • Scopes: leer lassen für den Standard openid email profile.
   • Standard-Rolle: Rolle für automatisch angelegte Benutzer (Standard: Betrachter).
   • JIT-Provisionierung: wenn aktiv, legt Notory unbekannte Benutzer beim ersten SSO-Login automatisch im Mandanten an.
   • Gruppen-Claim (Standard groups) und Gruppen-Rollen-Zuordnung: z. B. it-admins → admin, helpdesk → technician; optional Rolle bei jedem Login synchronisieren.

   Screenshot ausstehend admin-sso-02 Formular für einen OIDC-Provider mit Discovery-URL, Client-ID, Client-Secret, JIT und Gruppen-Mapping

   Die OIDC-Konfiguration: Discovery-URL, Client-Credentials, JIT-Provisionierung und Gruppen-Mapping.

3. Im IdP die Redirect-URI eintragen. Registriere in deinem IdP die Callback-Adresse https://<deine-instanz>/api/v1/auth/sso/callback als erlaubte Redirect-URI des OIDC-Clients.

4. Aktivieren und testen. Setze den Provider auf aktiviert. Öffne die Login-Maske in einem privaten Fenster und gib die E-Mail eines Kontos dieses Mandanten ein. Der Button „Anmelden mit …” erscheint automatisch (E-Mail-Discovery).

API (curl)

Provider-Konfigurationen sind normale CRUD-Ressourcen unter /api/v1/sso/configs (mandantengebunden):

OIDC-Provider anlegen

curl -X POST https://demo.notory.io/api/v1/sso/configs \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_name": "Firmen-Login (Entra ID)",
    "protocol": "oidc",
    "enabled": true,
    "discovery_url": "https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration",
    "client_id": "0f7e1c2d-…",
    "client_secret": "geheim",
    "scopes": "openid email profile",
    "default_role": "viewer",
    "allow_jit": true,
    "group_claim": "groups",
    "group_role_map": { "it-admins": "admin", "helpdesk": "technician" },
    "sync_role_on_login": false
  }'

Die Antwort (201 Created) enthält die Konfiguration, ohne das client_secret (wird nie zurückgegeben). Weitere Endpunkte: GET /api/v1/sso/configs (Liste), PUT /api/v1/sso/configs/{id} (ändern), DELETE /api/v1/sso/configs/{id} (löschen, nur Administrator) sowie GET /api/v1/sso/providers (aktivierte Provider des Mandanten).

Mögliche Fehler: 403 (Feature sso nicht lizenziert: „The Single sign-on (SSO) module is not included in the ’…’ plan”), 501 (Login-Start, wenn discovery_url oder client_id fehlen), 502 (Discovery-Dokument nicht abrufbar).

Was passiert dabei?

• Der Login-Flow (OIDC Authorization Code + PKCE). Beim Klick auf „Anmelden mit …” leitet Notory zum IdP weiter, mit PKCE (S256), state und nonce; der Zustand wird als signiertes, 10 Minuten gültiges Cookie (it_sso) gehalten. Nach der Rückkehr am Callback tauscht Notory den Code gegen Tokens und validiert das id_token kryptografisch gegen die JWKS des IdP (Signatur, iss, aud, Ablauf, nonce).
• Nur verifizierte E-Mails. Akzeptiert wird ausschließlich eine E-Mail mit email_verified: true, sonst bricht der Login ab.
• Konto-Zuordnung per E-Mail. Existiert ein Konto mit dieser E-Mail, wird es angemeldet, aber nur, wenn es zum Mandanten des Providers gehört (Mandanten-Isolation). Existiert keines: Mit JIT legt Notory den Benutzer im Mandanten des Providers an (Standard-Rolle bzw. Gruppen-Mapping, zufälliges unbrauchbares Passwort, das Konto ist SSO-only); ohne JIT erscheint „No account exists for this e-mail. Ask an administrator to invite you.”
• Rollen aus Gruppen. Aus dem Gruppen-Claim wird über die Zuordnungstabelle die höchstwertige passende Rolle ermittelt. Mit „Rolle bei jedem Login synchronisieren” zieht Notory Rollenänderungen aus dem IdP bei jeder Anmeldung nach.
• Deaktivierte Konten. Ein inaktives Konto wird beim SSO-Login nur mit aktiver JIT-Provisionierung automatisch reaktiviert; sonst bleibt es gesperrt.
• 2FA. Beim SSO-Login fragt Notory keinen lokalen Authenticator-Code ab. Mehrfaktor übernimmt der IdP. Eine erzwungene 2FA-Einrichtung (Instanz/Mandant) gilt aber weiterhin: Ohne eingerichtetes Gerät bleibt die App bis zur Einrichtung gesperrt.
• Secret-Handling. Das client_secret wird gespeichert, aber in keiner API-Antwort ausgegeben.

Verwandte Themen

• E-Mail-Discovery erklärt
• Fallback lokale Anmeldung
• Mandanten-Isolation
• Rollen & Berechtigungen