Konfiguriere LDAP- oder Active-Directory-Federation für IBM Bob Self-Hosted mit der benutzerdefinierten BobIDP-Ressource und dem Befehl bobctl configure-idp.

Verwende bobctl configure-idp, um deine LDAP- oder Active-Directory-Umgebung als Benutzerföderationsprovider mit Keycloak zu verbinden. Du kannst diese Einrichtung während der Installation oder jederzeit nach dem Deployment abschließen.

Voraussetzungen

Stelle vor der Konfiguration der LDAP-Federation sicher, dass die folgenden Anforderungen erfüllt sind:

Der OpenShift Container Platform (OCP)-Cluster hat Netzwerkkonnektivität zum LDAP-Server auf dem entsprechenden Port:

389 für ldap://
636 für ldaps://

Ein Dienstkonto (Bind-DN) mit Lesezugriff auf das Verzeichnis ist verfügbar, oder der LDAP-Server ist für anonyme Binds konfiguriert.

Wenn du ldaps:// mit einer privaten oder intern signierten Zertifizierungsstelle (CA) verwendest, beschaffe das CA-Zertifikat des LDAP-Servers im PEM-Format.

Das bobctl-Befehlszeilendienstprogramm ist installiert, und oc ist konfiguriert und gegen den Zielcluster authentifiziert.

Konfigurationsdateireferenz

Erstelle eine IDP-Konfigurationsdatei aus der bereitgestellten Vorlage, bevor du einen LDAP-Provider registrierst.

cp config-idp-template.yaml my-idp.yaml

Die Konfigurationsdatei hat zwei Abschnitte: übergeordnete Felder, die für das gesamte Deployment gelten, und eine optionale ldaps-Liste, in der jeder Eintrag einen LDAP-Föderationsprovider beschreibt.

Übergeordnete Felder

Feld	Erforderlich	Beschreibung
`domains`	Ja	Liste der E-Mail-Domänen, die Bob bei der Anmeldung akzeptiert. Das Entfernen einer Domäne hebt deren Registrierung auf; Benutzer mit dieser Domäne können sich nicht mehr anmelden.
`adminEmails`	Nein	Liste der Benutzer-E-Mails, denen Bob-Admin-Zugriff gewährt werden soll. Der Operator aktualisiert sowohl die Keycloak-Gruppe `bob-admins` als auch die Bob-Admin-Datenbank atomar.
`ldaps`	Nein	Liste der LDAP-Föderationsprovider-Konfigurationen. Vollständig weglassen für Deployments, die nur direkte Keycloak-Benutzer verwenden.

Pflichtfelder (pro LDAP-Provider-Eintrag)

Feld	Beschreibung
`name`	Eine eindeutige, beschreibende Kennung für den LDAP-Provider. Jeder konfigurierte Provider muss einen eindeutigen Namen haben.
`vendor`	Gibt den Typ des zu integrierenden LDAP-Verzeichnisses an. Unterstützte Werte: `other` (OpenLDAP und LDAPv3-konform), `ad` (Microsoft Active Directory), `rhds` (Red Hat Directory Server), `tivoli` (IBM Security Directory Server), `edirectory` (NetIQ eDirectory).
`connectionUrl`	Die vollständige URL des LDAP-Servers, einschließlich Protokoll (`ldap://` oder `ldaps://`), Hostname und Portnummer.
`usersDn`	Der Verzeichnisstandort, an dem Benutzerkonten gespeichert sind und von dem aus Benutzereinträge gesucht und importiert werden.
`usernameLDAPAttribute`	Das Verzeichnisattribut, das Benutzer als Benutzernamen bei der Authentifizierung angeben.
`rdnLDAPAttribute`	Das Verzeichnisattribut, das zur Identifizierung von Einträgen innerhalb der Verzeichnisstruktur verwendet wird. In den meisten Konfigurationen ist dies dasselbe wie `usernameLDAPAttribute`.
`uuidLDAPAttribute`	Ein eindeutiges, stabiles, unveränderliches Verzeichnisattribut, das zur dauerhaften Identifizierung jedes Benutzerkontos verwendet wird.
`userObjectClasses`	Eine kommagetrennte Liste von LDAP-Objektklassen, die definieren, welche Verzeichniseinträge als Benutzerkonten erkannt und verarbeitet werden.

Wichtig:

Das Feld domains ist die einzige Methode zur Konfiguration des domänenbasierten Routings in On-Premises-Deployments. Konfiguriere keine Domänen über die Bob-Administrations-Benutzeroberfläche, da dies nicht die korrekte Methode ist und Authentifizierungsfehler verursachen kann.

Optionale Felder (pro LDAP-Provider-Eintrag)

Feld	Beschreibung
`bindDn`	Der DN des Dienstkontos, das zur Authentifizierung und Verbindung mit dem Verzeichnis verwendet wird. Kann weggelassen werden, wenn das Verzeichnis anonymen Bind-Zugriff erlaubt.
`bindPasswordSecret`	Name eines bereits vorhandenen Secrets, das das Bind-Konto-Passwort enthält. Muss im Instanz-Namespace erstellt werden, bevor `bobctl configure-idp` ausgeführt wird.
`useTruststoreSpi`	Gibt an, wann das LDAP-CA-Zertifikat für die Servervalidierung verwendet wird. Werte: `always` (Standard, für private oder intern ausgestellte CA-Zertifikate), `ldapsOnly` (für öffentlich vertrauenswürdige CA-Zertifikate), `never` (bei ungesicherter `ldap://`-Verbindung).
`ldapsCACertSecret`	Name eines bereits vorhandenen Secrets, das das CA-Zertifikat des LDAP-Servers im PEM-Format enthält. Muss im Instanz-Namespace erstellt werden, bevor `bobctl configure-idp` ausgeführt wird.
`searchScope`	Bestimmt die Tiefe der Verzeichnissuchen. `2` durchsucht alle untergeordneten Container und Teilbäume (Standard); `1` beschränkt die Suche auf direkte untergeordnete Einträge.
`customUserSearchFilter`	Ein zusätzlicher Filter, der auf alle Benutzer-Suchoperationen angewendet wird, z. B. um Dienstkonten auszuschließen oder Suchen auf bestimmte Benutzertypen zu beschränken.
`userSync.enabled`	Wenn auf `true` gesetzt, werden alle Benutzer beim ersten Konfigurieren des Providers importiert, und nachfolgende Verzeichnisänderungen werden alle fünf Minuten synchronisiert. Für die meisten Deployments empfohlen.
`userAttributeMappings`	Definiert, wie Verzeichnisattribute auf Bob-Benutzerprofilfelder abgebildet werden, z. B. `email`, `firstName` und `lastName`.
`priority`	Bestimmt die Reihenfolge, in der Provider ausgewertet werden, wenn mehrere Provider konfiguriert sind. Provider mit niedrigeren Werten werden zuerst geprüft. Standard ist `0`.
`groupMapper`	Synchronisiert LDAP-Gruppen in Keycloak. Siehe LDAP-Gruppensynchronisierung konfigurieren.

Benutzersynchronisierungsverhalten

Wenn userSync.enabled auf true gesetzt ist, führt Bob einen einmaligen Import aller Benutzer durch, wenn der LDAP-Provider registriert wird. Nach Abschluss des anfänglichen Imports wird die laufende Benutzer-Lifecycle-Synchronisierung automatisch über SCIM abgewickelt.

Tipp:

Bei großen LDAP-Verzeichnissen solltest du userSync.enabled auf false belassen und Benutzer bei ihrer ersten Anmeldung bereitstellen lassen. Dieser Ansatz kann die Zeit reduzieren, die zum Registrieren des LDAP-Providers benötigt wird.

LDAP-Gruppensynchronisierung konfigurieren

Verwende die optionale groupMapper-Konfiguration, um LDAP-Gruppen mit Keycloak zu synchronisieren. Mit der Gruppensynchronisierung werden Benutzer und Gruppenmitgliedschaften aus deinem LDAP-Verzeichnis über Keycloak importiert und verwaltet.

Der Parameter groupsDn ist erforderlich. Alle anderen Parameter sind optional und können angepasst werden, um deinem LDAP-Verzeichnisschema und deiner Gruppenstruktur zu entsprechen.

Einschränkung:

Die Gruppen bob-admins und bob-users sind plattformverwaltete Gruppen. Sie sind nicht in der LDAP-Gruppensynchronisierung enthalten.

Parameter	Standardwert	Beschreibung
`groupsDn`	Erforderlich	Basis-Distinguished-Name (DN), der LDAP-Gruppeneinträge enthält.
`name`	`groups`	Anzeigename des Gruppen-Mappers in Keycloak.
`groupNameLdapAttribute`	`cn`	LDAP-Attribut, das Keycloak als Gruppenname verwendet.
`groupObjectClasses`	`groupOfNames`	LDAP-Objektklasse(n), die Gruppeneinträge identifizieren.
`membershipLdapAttribute`	`member`	Attribut im Gruppeneintrag, das Mitgliedsinformationen enthält.
`membershipAttributeType`	`DN`	Format der Mitgliedswerte. Unterstützte Werte: `DN` (Distinguished Names) und `UID` (Benutzer-IDs).
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Methode zur Bestimmung von Gruppenmitgliedschaften.
`memberOfLdapAttribute`	`memberOf`	Benutzerattribut, das Gruppenmitgliedschaftsinformationen enthält, wenn `GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE` verwendet wird.
`customGroupSearchFilter`	Keiner	Zusätzlicher LDAP-Filter bei der Suche nach Gruppen. Der Filter muss in Klammern eingeschlossen sein, z. B. `(cn=dept-*)`.
`mode`	`LDAP_ONLY`	Synchronisierungsmodus. Unterstützte Werte: `LDAP_ONLY` und `READ_ONLY`.
`groupsPath`	`/`	Speicherort in der Keycloak-Gruppenhierarchie, an dem synchronisierte Gruppen erstellt werden.

Strategien zum Abrufen von Gruppenmitgliedschaften

Der Parameter userRolesRetrieveStrategy steuert, wie Keycloak die Gruppenmitgliedschaften eines Benutzers identifiziert.

Strategie	Beschreibung
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Ruft Gruppenmitgliedschaften ab, indem Gruppeneinträge gesucht werden, die Verweise auf Benutzer enthalten.
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	Ruft Gruppenmitgliedschaften aus dem `memberOf`-Attribut des Benutzers ab.
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	Ruft Gruppenmitgliedschaften rekursiv ab, einschließlich verschachtelter Gruppen, sofern vom LDAP-Verzeichnis unterstützt.

Tipp:

Verwende LOAD_GROUPS_BY_MEMBER_ATTRIBUTE, es sei denn, dein LDAP-Verzeichnis speichert Gruppenmitgliedschaftsinformationen in Benutzereinträgen über das memberOf-Attribut oder verwendet verschachtelte Gruppenstrukturen, die rekursive Suchen erfordern.

Beispielkonfiguration

# E-Mail-Domänen, die Bob bei der Anmeldung akzeptieren soll
domains:
  - corp.example.com

# Benutzer, denen Bob-Admin-Zugriff gewährt werden soll
adminEmails:
  - alice@corp.example.com

# LDAP-Föderationsprovider
ldaps:
  - name: corp-ldap

    vendor: other
    connectionUrl: ldaps://ldap.corp.example.com:636
    usersDn: ou=People,dc=corp,dc=example,dc=com
    usernameLDAPAttribute: uid
    rdnLDAPAttribute: uid
    uuidLDAPAttribute: entryUUID
    userObjectClasses: inetOrgPerson,organizationalPerson,person

    bindDn: cn=bob-svc,ou=ServiceAccounts,dc=corp,dc=example,dc=com
    bindPasswordSecret: corp-ldap-bind

    useTruststoreSpi: always
    ldapsCACertSecret: corp-ldap-ca

    userSync:
      enabled: true

    userAttributeMappings:
      - ldapAttribute: mail
        userModelAttribute: email
      - ldapAttribute: givenName
        userModelAttribute: firstName
      - ldapAttribute: sn
        userModelAttribute: lastName

    # Optional: LDAP-Gruppen in Keycloak synchronisieren
    groupMapper:
      groupsDn: ou=Groups,dc=corp,dc=example,dc=com
      groupObjectClasses: groupOfNames
      membershipLdapAttribute: member

./bobctl configure-idp --config my-idp.yaml

IDP-Konfiguration vor der Anwendung validieren

Bevor du eine IDP-Konfiguration auf den Cluster anwendest, verwende die Option --dry-run, um die Konfiguration zu validieren und eine Vorschau der Ressourcen anzuzeigen, die erstellt werden würden. Ein Dry Run kann helfen, häufige Konfigurationsprobleme zu identifizieren, bevor Änderungen am Cluster vorgenommen werden.

./bobctl configure-idp --config my-idp.yaml --dry-run

Der Dry Run führt die folgenden Prüfungen durch:

Validiert, dass alle erforderlichen Konfigurationsparameter in der Konfigurationsdatei vorhanden sind.

Zeigt eine Vorschau der benutzerdefinierten BobIDP-Ressource an, die erstellt oder aktualisiert werden würde.

Beendet sich, ohne Ressourcen im Cluster zu erstellen, zu ändern oder zu löschen.

Hinweis:

Der Dry-Run-Vorgang validiert keine Netzwerkkonnektivität zum LDAP-Server, authentifiziert die angegebenen Anmeldeinformationen nicht gegen das Verzeichnis und bestätigt nicht die Existenz referenzierter Secrets im Cluster. Diese Validierungen werden erst durchgeführt, nachdem die Konfiguration angewendet wurde, und spiegeln sich in den Statusbedingungen LDAPReachable und LDAPAuthenticated wider.

Konfiguration anwenden

Nachdem du deine IDP-Konfigurationsdatei erstellt und validiert hast, führe den Befehl configure-idp aus, um die Konfiguration auf den Cluster anzuwenden.

./bobctl configure-idp --config my-idp.yaml

Flag	Erforderlich	Beschreibung
`--config <file>`	Ja	Gibt den Pfad zur IDP-Konfigurationsdatei an.
`--dry-run`	Nein	Validiert die Konfiguration und zeigt eine Vorschau der Ressourcen an, die erstellt oder aktualisiert werden würden, ohne Änderungen auf den Cluster anzuwenden.

Wenn der Befehl ausgeführt wird, wartet bobctl darauf, dass der Operator die Konfiguration abstimmt, und validiert den IDP, indem er die Statusbedingungen überprüft, die von der benutzerdefinierten BobIDP-Ressource gemeldet werden.

Prüfung	Was sie bestätigt
`Ready`	Die Konfiguration wurde erfolgreich angewendet.
`LDAPRegistered`	Der LDAP-Provider wurde in Keycloak registriert.
`LDAPReachable`	Der LDAP-Server ist vom Cluster aus zugänglich.
`LDAPAuthenticated`	Die konfigurierten Bind-Anmeldeinformationen sind gültig.
`LDAPUserSyncSucceeded`	Der anfängliche Benutzerimport wurde erfolgreich abgeschlossen. Diese Bedingung wird nur ausgewertet, wenn `userSync.enabled` auf `true` gesetzt ist.

Das Standard-Validierungs-Timeout beträgt 600 Sekunden (10 Minuten). In Umgebungen mit großen Verzeichnissen kann die anfängliche Benutzersynchronisierung mehrere Minuten dauern. Um das Timeout zu erhöhen, setze die Umgebungsvariable BOB_IDP_WAIT_TIMEOUT:

BOB_IDP_WAIT_TIMEOUT=900 ./bobctl configure-idp --config my-idp.yaml

Mehrere LDAP-Provider konfigurieren

Um Benutzer aus mehreren LDAP- oder Active-Directory-Quellen zu integrieren, füge jedes Verzeichnis als separaten Eintrag in der ldaps-Liste der IDP-Konfigurationsdatei hinzu und führe configure-idp erneut aus.

./bobctl configure-idp --config my-idp.yaml

IDP-Ressourcenstatus prüfen

So zeigst du den Status der IDP-Konfiguration an:

oc get bobidp -n <instance-namespace>

So zeigst du detaillierte Konfigurations- und Statusinformationen an:

oc get bobidp bob-idp -n <instance-namespace> -o yaml

Integration überprüfen

Nachdem bobctl configure-idp erfolgreich abgeschlossen wurde, überprüfe, ob die LDAP-Integration korrekt funktioniert.

Status der benutzerdefinierten BobIDP-Ressource prüfen:

oc get bobidp bob-idp -n <instance-namespace> -o yaml

Überprüfe, ob die folgenden Statusbedingungen auf True gesetzt sind:

Bedingung	Zweck
`Ready`	Bestätigt, dass die Konfiguration erfolgreich angewendet wurde.
`LDAPRegistered`	Bestätigt, dass der LDAP-Provider in Keycloak registriert wurde.
`LDAPReachable`	Bestätigt, dass der Cluster mit dem LDAP-Server kommunizieren kann.
`LDAPAuthenticated`	Bestätigt, dass die konfigurierten Bind-Anmeldeinformationen gültig sind.
`LDAPUserSyncSucceeded`	Bestätigt, dass alle Benutzer erfolgreich importiert wurden. Nur vorhanden, wenn `userSync.enabled: true`.

Wenn eine Bedingung False ist, überprüfe das entsprechende Feld message für Diagnosedetails.

Melde dich mit Anmeldeinformationen aus dem federierten LDAP-Verzeichnis an, um zu überprüfen, ob die Benutzerauthentifizierung funktioniert.

Öffne die Bob-URL:

https://bob.<namespace>.<ingress-domain>

Eine erfolgreiche Anmeldung bestätigt, dass Konnektivität, Authentifizierung, Domänen-Routing, SCIM-Bereitstellung und Rollenzuordnung korrekt funktionieren.

Nachdem sich der Benutzer zum ersten Mal angemeldet hat, bestätige, dass der Benutzerdatensatz in Bob verfügbar ist.

Öffne die Bob-Administrations-UI:

https://bob.<namespace>.<ingress-domain>/admin

Melde dich als Bob-Administrator an und überprüfe, ob der Testbenutzer in der Benutzerliste erscheint.

Wenn groupMapper so konfiguriert ist, dass eine LDAP-Gruppe auf Bob-Administratoren abgebildet wird:

Melde dich mit einem Benutzerkonto an, das zur zugeordneten Administratorgruppe gehört.
Bestätige, dass der Benutzer auf die Bob-Administrations-UI zugreifen kann.
Überprüfe, ob Funktionen auf Administratorebene verfügbar sind.

Wenn userSync.enabled: true, werden Benutzer automatisch importiert, nachdem der LDAP-Provider registriert wurde. Der Testbenutzer sollte in Bob erscheinen, ohne dass eine anfängliche Anmeldung erforderlich ist.

Wenn der Benutzer nach mehreren Minuten nicht erscheint, überprüfe die bob-admin-Protokolle auf Bereitstellungsfehler:

oc logs -n <instance-namespace> -l app=bob-admin --tail=100

Überprüfe alle gemeldeten SCIM-bezogenen Fehler und behebe sie, bevor du den Synchronisierungsprozess erneut versuchst.

LDAP-Integration

Auf dieser Seite