SSO und LDAP¶

Unter Administration > SSO (/v2/admin/sso) wird die Single-Sign-On- und LDAP-Anmeldung konfiguriert. Beide Verfahren sind in v2 vollständig als Login-Methoden umgesetzt — inklusive Just-in-Time-Provisionierung (JIT) und Rollen-/Gruppenzuordnung.

Unterstützte Verfahren¶

Verfahren	Beschreibung
SAML 2.0	Single Sign-On über jeden Identity Provider, der SAML 2.0 spricht (Microsoft Entra ID, ADFS, Keycloak u. a.); Anmeldeknopf auf der Login-Seite
LDAP-Bind	Anmeldung gegen OpenLDAP oder Active Directory; Checkbox „Über LDAP anmelden" auf der Login-Seite

Die Konfiguration ist V1-kompatibel: Alle Einstellungen liegen unter denselben Property-Schlüsseln (settings/EntraID, settings/LDAP, settings/LDAP_UserProperty, settings/LDAP_RoleMapping) — per V1→V2-Migration übernommene Konfiguration funktioniert unverändert. Der Schlüssel heißt aus V1-Gründen weiter EntraID, gilt aber für jeden SAML-Anbieter.

SAML 2.0¶

Identity Provider wählen¶

Im Reiter SAML steht oben die Auswahl Identity Provider: Microsoft Entra ID, Microsoft ADFS, Keycloak oder „Anderer Identity Provider". Die Wahl ändert nur Hinweise, Beispielwerte und den Anmeldeknopf; die SAML-Verbindung selbst ist für alle gleich (Bibliothek onelogin/php-saml).

Wahl	Anmeldeknopf	Hinweis im Admin
Microsoft Entra ID	„Mit Microsoft anmelden" (Microsoft-Symbol)	Unternehmensanwendung, Gruppen-Claim liefert Objekt-IDs
Microsoft ADFS	„Mit Single Sign-On anmelden"	Vertrauensstellung per Metadaten-URL, Gruppen per Anspruchsregel
Keycloak	„Mit Single Sign-On anmelden"	Client per Metadaten-URL importieren, Mapper „Group list"
Anderer	„Mit Single Sign-On anmelden"	allgemeine Hinweise

Bestehende Anlagen, deren SAML-Verbindung vor dieser Auswahl eingerichtet wurde, gelten ohne gespeicherte Wahl als Entra ID und behalten den Microsoft-Knopf. Eine neue Anlage startet neutral.

Keycloak: Assertion signieren

calServer nimmt nur signierte Assertions an (Schutz gegen untergeschobene Antworten). Keycloak signiert in der Grundeinstellung nur das Dokument. Im Keycloak-Client unter Keys den Schalter Sign assertions einschalten, sonst wird jede Anmeldung abgelehnt. Entra ID und ADFS signieren die Assertion von Haus aus.

Attribut-Zuordnung¶

Welche SAML-Attribute als E-Mail, Vor- und Nachname gelten, steht im Abschnitt Attribut-Mapping (SAML → Benutzerfeld); das Gruppenattribut unter Provisionierung (Standard groups). Leere Felder nutzen die Standard-Claims (…/claims/emailaddress, givenname, surname), die Entra ID und ADFS senden; fehlt die E-Mail ganz, gilt die NameID als E-Mail. Die Felder teilen sich die Werte mit dem LDAP-Attribut-Mapping.

Die Login-Seite zeigt bei aktiviertem SAML den Anmeldeknopf (siehe Tabelle oben).
GET /api/v2/auth/saml/login leitet zum Identity Provider weiter (AuthnRequest).
Der IdP sendet die Assertion an POST /api/v2/auth/saml/acs; nach Validierung und JIT-Provisionierung wird ins Frontend mit einem Einmal-Code (60 s gültig, einmalig verwendbar) weitergeleitet.
Die SPA tauscht den Code über POST /api/v2/auth/sso/exchange gegen einen API-Token — der Token erscheint nie in einer URL.

Endpunkte für die IdP-Registrierung¶

Endpunkt	Zweck
`GET /api/v2/auth/saml/metadata`	SP-Metadata (für die Registrierung beim Identity Provider)
`POST /api/v2/auth/saml/acs`	Assertion Consumer Service
`GET/POST /api/v2/auth/saml/sls`	Single Logout

Der Admin-Tab SAML enthält Kopier-Buttons für Metadata- und ACS-URL sowie die Verbindungseinstellungen (Entity ID, ACS-URL, Logout-URL, X.509-Zertifikat des IdP, Aktivieren-Schalter).

LDAP-Bind (OpenLDAP / Active Directory)¶

Die Anmeldung erfolgt als explizite Login-Methode (method: 'ldap' beim Login); das Login-Feld akzeptiert dann auch reine Benutzernamen (z. B. sAMAccountName).

Active Directory: Service-Bind (Bind-DN + Passwort) → Benutzersuche unter dem Base DN → Bind mit dem gefundenen distinguishedName und dem Benutzerpasswort. Gruppen aus memberOf.
OpenLDAP: Benutzersuche → Bind mit konstruiertem DN (user_id_key=login,base_dn). Gruppenabgleich über groupOfUniqueNames/uniqueMember.
Leere Passwörter werden vor jedem Bind abgewiesen — ein anonymer Bind kann nie als Login durchgehen.

Einstellung	Beschreibung
Server / Domain Controllers	LDAP-Server-Adresse(n)
Port	LDAP-Port (389/636), SSL/TLS-Schalter
Base DN	Basis-DN für die Benutzersuche
Bind DN / Admin-Passwort	Service-Konto für die Suche
User-ID-Attribut	z. B. `sAMAccountName` oder `uid`
Account-Suffix	optionaler UPN-Suffix
Attribut-Mapping	Nachname/E-Mail/Telefon (Standard: `sn`, `mail`, `telephoneNumber`)

Der Admin-Tab LDAP bietet einen „Verbindung testen"-Button (POST /api/v2/admin/sso/ldap/test), der den Service-Bind mit den aktuellen — auch ungespeicherten — Formularwerten prüft.

Rollen- und Gruppenzuordnung (JIT-Provisionierung)¶

Über SSO Role Group Mapping werden IdP-/LDAP-Gruppen automatisch calServer-Rollen und -Gruppen zugeordnet — identische Semantik für SAML und LDAP:

SSO-Gruppe angeben (Entra ID: Gruppen-Objekt-ID, Keycloak/ADFS: Gruppenname, LDAP: Gruppen-DN)
calServer-Rolle und/oder -Gruppe aus der Auswahlliste zuordnen
Bei jedem Login wird die Zuordnung angewendet; keep_existing-Schalter steuern Zusammenführen vs. Ersetzen
Greift kein Mapping, werden Default-Rolle und Default-Gruppe zugewiesen

Rolle und Gruppe werden im Dialog aus den vorhandenen Rollen (GET /api/v2/roles) und Gruppen (GET /api/v2/groups) ausgewählt, nicht frei getippt. Die API weist ein Mapping ab (422), das eine unbekannte Rolle oder Gruppe nennt oder weder Rolle noch Gruppe setzt — solche Einträge ließen sich früher speichern, wurden bei der Anmeldung aber stillschweigend ignoriert.

Ein Mapping trägt genau eine Rolle und eine Gruppe. Sollen Benutzer einer IdP-Gruppe mehrere Rollen erhalten, legt man mehrere Mappings mit derselben IdP-Gruppe an.

Erstanmeldung

Bei der ersten Anmeldung über SSO/LDAP wird automatisch ein calServer-Benutzerkonto erstellt (JIT) und die konfigurierten Rollen/Gruppen zugewiesen. Direkt zugewiesene Operations bestehender Benutzer bleiben unangetastet.