Single Sign-On (SSO)

Mit Single Sign-On melden sich deine Nutzer über den zentralen Identity-Provider (IdP) deines Unternehmens an — ohne Code per E-Mail und ohne eigenen roleALPHA-Passkey. roleALPHA spricht dabei OpenID Connect (OIDC), das von Microsoft Entra ID (Azure AD), Google Workspace, Okta und praktisch jedem modernen IdP unterstützt wird. Klassische Enterprise-Protokolle wie SAML/Shibboleth bindest du über einen vorgelagerten IAM-Broker (z.B. Keycloak) an, der nach innen ein OIDC spricht.

SSO wird pro Tenant konfiguriert und ist ein Opt-in — solange du es nicht aktivierst, ändert sich für deine Nutzer nichts. Du kannst mehrere Anbieter gleichzeitig aktivieren: Microsoft, Google und einen generischen OIDC-Anbieter (SSO). Jeder aktivierte Anbieter erscheint als eigener Button auf der Login-Seite („Mit Google anmelden”, „Mit Microsoft anmelden”, „SSO”). Für Microsoft und Google gibt es Presets — du gibst dort nur Client-ID und Secret (bei Microsoft zusätzlich die Directory-ID) ein.

Voraussetzungen

• Du bist Tenant-Admin (oder Platform-Admin).
• Du hast Zugriff auf die Verwaltung deines IdP, um dort eine „App”/„Client”-Registrierung anzulegen.

Schritt 1 — Callback-URL beim IdP registrieren

Der IdP muss wissen, wohin er den Nutzer nach der Anmeldung zurückschickt. Trage bei deinem IdP genau diese Redirect-URI (Callback) ein — je Anbieter eine eigene (<anbieter> = microsoft, google oder generic):

https://<deine-roleALPHA-Basis-URL>/api/auth/sso/<Tenant-UUID>/<anbieter>/callback

Beispiel Google: …/api/auth/sso/<Tenant-UUID>/google/callback. Die Tenant-UUID findest du in der Adresszeile bzw. in den Tenant-Einstellungen. Nutze eine stabile Basis-URL (deine Produktiv-Domain) — so überlebt die Anmeldung auch einen späteren Umzug des Tenants.

Schritt 2 — App beim IdP anlegen

Microsoft Entra ID (Azure AD):

1. Azure-Portal → App registrations → New registration.
2. Redirect-URI (Typ Web) = die Callback-URL aus Schritt 1.
3. Notiere Application (client) ID und Directory (tenant) ID.
4. Unter Certificates & secrets ein Client secret erzeugen und kopieren.
5. Issuer-URL: https://login.microsoftonline.com/<Directory-ID>/v2.0
6. Für Gruppen: unter Token configuration den optionalen Claim groups ergänzen.

Google Workspace:

1. Google Cloud Console → APIs & Services → Credentials → OAuth client ID (Typ Web application).
2. Authorized redirect URI = die Callback-URL aus Schritt 1.
3. Client-ID + Client-Secret kopieren.
4. Issuer-URL: https://accounts.google.com

Keycloak / IAM-Broker (auch für SAML/Shibboleth):

1. Im Broker einen OIDC Client (confidential) anlegen, Redirect-URI = Callback aus Schritt 1.
2. Client-ID + Secret kopieren; Issuer-URL = https://<broker>/realms/<realm>.
3. Im Broker die Upstream-Verbindung (SAML zu Shibboleth/ADFS oder ein weiteres OIDC) einrichten — nach innen bleibt es ein OIDC.

Schritt 3 — In roleALPHA eintragen

Öffne Einstellungen → Benutzer & Zugriff → Single Sign-On. Dort findest du drei Karten — Microsoft, Google und Single Sign-On (generisch). Fülle die Karte(n) des/der gewünschten Anbieter(s):

• Microsoft — Issuer URL aus dem Template (Directory-ID einsetzen: https://login.microsoftonline.com/<Directory-ID>/v2.0), Client ID, Client-Secret.
• Google — kein Issuer-Feld (fest auf https://accounts.google.com); nur Client ID und Client-Secret.
• Single Sign-On (generisch) — alles manuell (Issuer, Client-ID, Secret) für Okta/Keycloak/beliebige OIDC-IdPs.

Der Anzeigename erscheint auf dem Login-Button. Das Client-Secret wird verschlüsselt gespeichert und nie wieder angezeigt (nur beim Ändern erneut eingeben). Unter Erweitert stehen Scopes, Claims und das Gruppen→Rollen-Mapping. Zum Schluss den Enable-Schalter der Karte einschalten und Speichern — aktivieren ist erst möglich, wenn Issuer, Client-ID und Secret gesetzt sind (bei Google genügt Client-ID + Secret).

Schritt 4 — Gruppen auf Rollen abbilden

roleALPHA-Rollen bleiben in roleALPHA definiert (der IdP kennt die feingranularen Berechtigungen nicht). Du legst nur fest, welche IdP-Gruppe welche roleALPHA-Rolle bekommt — als JSON:

{
  "meine-idp-admin-gruppe": ["tenant_admin"],
  "alle-mitarbeitenden": ["user"]
}

• Der rechte Wert ist der Schlüssel einer in deinem Tenant existierenden Rolle (siehe Rollen & Berechtigungen). Unbekannte Schlüssel werden ignoriert — lege die Rolle also zuerst an.
• Default-Rollen greifen, wenn keine Gruppe passt.
• IdP-Rollen sind autoritativ (Standard): Bei jeder Anmeldung werden die Rollen aus dem IdP übernommen und überschreiben lokale Änderungen. Schalte das ab, wenn du Rollen in roleALPHA zusätzlich manuell vergeben willst.

Verhalten & Optionen

• Just-in-Time-Provisioning (Standard an): Meldet sich ein Nutzer zum ersten Mal an, wird sein Konto automatisch angelegt und mit seiner E-Mail verknüpft. Welche Wege daneben offen bleiben (Code, Anmeldelink, Passkey), legst du unter Anmeldeverfahren fest. Ein Passwort gibt es für Mandantenkonten nicht.

Wiedererkannt wird ein Konto an der Kennung des IdP, nicht an der E-Mail-Adresse. Das zählt, sobald sich eine Adresse im Verzeichnisdienst ändert: die Person landet weiter in ihrem Konto — mit allen Rollen, Zuordnungen und Entwürfen — und die hinterlegte Anmeldeadresse zieht beim nächsten Anmelden nach. Konten, die vor dieser Änderung angelegt wurden, bekommen die Kennung beim nächsten Anmelden angeheftet; bis dahin gilt für sie noch die Erkennung über die Adresse.

Zwei Grenzen, die man kennen sollte: Gehört die neue Adresse im Mandanten bereits einem anderen Konto, bleibt die alte stehen (sonst bekäme der rechtmäßige Inhaber der Adresse Anmeldecodes für ein fremdes Konto). Und meldet sich derselbe Mensch in einem Mandanten über zwei Anbieter an, merkt sich die Zuordnung nur den zuletzt benutzten — der andere fällt auf die Erkennung über die Adresse zurück.

Zwei-Faktor-Authentifizierung und SSO

Föderierte Nutzer erhalten ihren zweiten Faktor in der Regel von ihrem IdP — roleALPHA fragt bei SSO-Logins standardmäßig nicht zusätzlich nach. Willst du es trotzdem, schaltest du unter Anmeldeverfahren den zweiten Faktor nach Single Sign-on ein: dann fragt roleALPHA nach dem SSO den Code aus der roleALPHA-eigenen Authenticator-App ab — bei allen, die eine eingerichtet haben.

Fehlersuche

• „sso_disabled” — SSO ist für den Tenant nicht aktiviert.
• „sso_state_invalid” / „sso_state_mismatch” — der Anmeldeversuch ist abgelaufen (10 min) oder die Rückkehr passt nicht zum Start. Erneut versuchen.
• „sso_no_email” — der IdP liefert keine E-Mail. Prüfe die Scopes (email) und den E-Mail-Claim.
• „sso_user_unknown” — der Nutzer existiert nicht und JIT-Provisioning ist aus.
• „sso_callback_failed” — Client-ID/Secret oder Redirect-URI stimmen nicht mit der IdP-Registrierung überein.

Verwandt

• Zwei-Faktor-Authentifizierung
• Rollen & Berechtigungen