Licensed to be used in conjunction with basebox, only.
// integration
LDAP / OIDC
Gilt für
Produkt: Cloud · Server · Zielgruppe: Platform Operator · IT · Administrator
Identitätsintegration: Benutzer und Gruppen aus LDAP/Active Directory, Single Sign-on über OpenID Connect. Was in basebox konfiguriert wird, was bei Ihrem Identitätsanbieter, und welche Netzwerkpfade nötig sind. Die Admin-Sicht ohne Technik steht unter LDAP-Anbindung und OIDC / Single Sign-on.
Wie basebox Identität verarbeitet
basebox bringt Keycloak als Identitätsanbieter mit. Das Frontend authentifiziert Nutzer per OpenID Connect gegen Keycloak; der Anwendungsserver AISRV prüft die ausgestellten JWTs. Beide Integrationen setzen an Keycloak an:
| Integration | Keycloak-Funktion | Was passiert |
|---|---|---|
| LDAP / Active Directory | User Federation | Keycloak liest Benutzer (und optional Gruppen) aus dem Verzeichnis und prüft Passwörter dort |
| OIDC-Anbieter (Entra ID, Okta, …) | Identity Providers (Brokering) | Keycloak leitet die Anmeldung an Ihren Anbieter weiter und übernimmt die bestätigte Identität |
Beides lässt sich kombinieren; lokale Konten – etwa der erste Administrator – bleiben daneben bestehen.
LDAP / Active Directory
Benötigt: Adresse und Port des LDAP-Servers (389, für LDAPS 636), ein Servicekonto mit Lesezugriff (Bind-DN + Passwort), den Basis-DN der Benutzer, den Vendor (Active Directory oder Other).
Einrichtung in der Keycloak Admin Console (https://<basebox-domain>/auth, Realm in der Regel primary): User Federation → Add provider → ldap, Verbindungsdaten eintragen, Test connection und Test authentication, Save, Synchronize all users. Schritt für Schritt: Keycloak mit LDAP / Active Directory verbinden.
Empfohlene Einstellungen:
- Edit mode
READ_ONLY– Keycloak schreibt nichts zurück. - Periodic Changed Users Sync
3600s, Periodic Full Sync86400s. - User LDAP Filter, um den Personenkreis zu begrenzen, z. B.
(memberOf=CN=AppUsers,OU=Groups,DC=corp,DC=example,DC=com). group-ldap-mapper, wenn Verzeichnisgruppen gespiegelt werden sollen; weitere Attribute peruser-attribute-ldap-mapper.- LDAPS im Produktivbetrieb; Zertifikate einer privaten CA in den Keycloak-Truststore importieren.
Netzwerkpfad: Keycloak → LDAP-Server, TCP 389/636. In basebox Cloud muss Ihr Verzeichnis aus dem Noris-Rechenzentrum erreichbar sein (private Anbindung oder Freigabe) – deshalb ist für die Cloud meist OIDC der praktischere Weg.
OpenID Connect (Single Sign-on)
Benötigt: Client-ID und Client-Secret einer bei Ihrem Anbieter registrierten Anwendung, die Discovery-URL (…/.well-known/openid-configuration), und die Redirect-URI aus Keycloak, die beim Anbieter einzutragen ist: https://<basebox-domain>/auth/realms/<realm>/broker/<alias>/endpoint.
Einrichtung: Keycloak Admin Console → Identity Providers → OpenID Connect v1.0 → Discovery-URL importieren, Client-ID und -Secret eintragen, Alias vergeben, speichern; Anmeldung mit einem Testkonto prüfen. Optional: First login flow anpassen (etwa Konten anhand der E-Mail-Adresse verknüpfen) und Attribut-Mapper für Vorname, Nachname, E-Mail.
Netzwerkpfad: Browser der Nutzer → Ihr Anbieter (öffentlich); Keycloak → Anbieter (Token-Endpunkt, TCP 443). Funktioniert in Cloud und Server ohne private Anbindung, solange der Anbieter aus beiden Richtungen erreichbar ist.
Was in basebox bleibt
- Rollen (Administrator/Nutzer) werden in basebox vergeben, nicht aus dem Verzeichnis übernommen.
- Gruppen für Freigaben werden unter Administration → Gruppen verwaltet.
- Lizenzplätze: jeder synchronisierte oder per SSO angemeldete Benutzer belegt einen.
- Die Benutzersynchronisation zwischen Keycloak und AISRV wurde in 1.8 robuster, auch für in Keycloak bereits vorhandene Benutzer.
Relevante Konfiguration auf basebox Server
| Komponente | Variable | Bedeutung |
|---|---|---|
| Frontend | VITE_BB_OIDC_DOMAIN |
Basis-URL des OIDC-Providers mit Realms-Pfad, endet mit /, z. B. https://basebox.firma.de/auth/realms/ |
| Frontend | VITE_BB_OIDC_FORCE_REALM |
Realm, in der Regel primary |
| Frontend | VITE_BB_OIDC_CLIENT_ID |
OIDC-Client-ID (Standard aiclient) |
| AISRV | AISRV_OIDC_IDP_URL |
Basis-URL des IdP (ohne Realm) |
| AISRV | AISRV_OIDC_ISSUER_URL |
Optionaler erwarteter Issuer – nur ändern, wenn Sie wissen, warum |
| AISRV | AISRV_OIDC_AUD |
Erwartete Audience |
Fehlerbilder – „Organisation not found", Weiterleitungsschleife, „iss does not match", 404 auf /auth/… – stehen mit Lösungen in der FAQ. Die vollständige Keycloak-Konfiguration: IDP (Keycloak).
Issuer ist eine Sicherheitsgrenze
AISRV prüft anhand des Issuers, ob ein Token von Ihrem Keycloak stammt. Ein fremder Issuer würde fremde Tokens zulassen. Änderungen nur durch den Platform Operator und nur mit Grund.
Entscheidungshilfe
| Situation | Empfehlung |
|---|---|
| Active Directory vorhanden, basebox Server im eigenen Netz | LDAP-Federation; LDAPS; Filter auf eine AD-Gruppe |
| Entra ID / Okta im Einsatz | OIDC-Brokering – in Cloud und Server |
| basebox Cloud, Verzeichnis nur intern erreichbar | OIDC statt LDAP, oder private Anbindung (Netzanbindung) |
| Kleine Organisation ohne zentrale Identität | Lokale Konten per Einladung; später umstellen |
Weiter: Keycloak-LDAP-Anbindung · Keycloak-LDAP (erweitert) · VPN / Netzwerk