Konfiguriere LDAP- oder Active-Directory-Federation für IBM Bob On-Premises mit der benutzerdefinierten BobLDAP-Ressource und dem Befehl bobctl add-ldap.

Bob On-Premises integriert deine LDAP- oder Active-Directory-Umgebung mit Keycloak über das bobctl-Dienstprogramm, das das Verzeichnis als Keycloak-Benutzerföderationsprovider konfiguriert. Obwohl diese Integration typischerweise während der Installation eingerichtet wird, kann sie auch nach der Bereitstellung als Teil laufender Benutzerverwaltungsaktivitäten konfiguriert, aktualisiert oder gepflegt werden.

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 LDAP-Konfigurationsdatei aus der bereitgestellten Vorlage, bevor du einen LDAP-Provider registrierst.

cp config-ldap-template.yaml my-ldap.yaml

Die Konfigurationsdatei enthält erforderliche und optionale Parameter, die definieren, wie Bob sich mit deinem LDAP-Verzeichnis verbindet, sich authentifiziert und Benutzer synchronisiert.

Pflichtfelder

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.
`domains`	Eine oder mehrere E-Mail-Domänen, die dem Verzeichnis zugeordnet sind. Während der Authentifizierung werden Benutzer, deren E-Mail-Adressen mit einer der konfigurierten Domänen übereinstimmen, automatisch zu diesem LDAP-Provider für die Anmeldeinformationsvalidierung weitergeleitet.

Wichtig:

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

Optionale Felder

Feld	Beschreibung
`adminEmails`	E-Mail-Adressen von Benutzern, denen Administratorrechte gewährt werden sollen. Bob weist diesen Benutzern automatisch Administratorzugriff zu.
`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`	Verweist auf das Secret, das das Bind-Konto-Passwort speichert. Dieses Secret wird automatisch erstellt, wenn die Option `--bind-password` mit dem `bobctl`-Befehl angegeben 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`	Verweist auf das Secret, das das CA-Zertifikat des LDAP-Servers im PEM-Format enthält. Dieses Secret wird automatisch erstellt, wenn `--ca-cert-file` angegeben 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. Die Gruppensynchronisierung ermöglicht es, in deinem LDAP-Verzeichnis definierte Benutzer und Gruppenmitgliedschaften über Keycloak zu importieren und zu verwalten.

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 und werden automatisch von der LDAP-Gruppensynchronisierung ausgeschlossen.

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

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

domains:
  - corp.example.com

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

useTruststoreSpi: always

userSync:
  enabled: true

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

# Optional: synchronize LDAP groups into Keycloak
groupMapper:
  groupsDn: ou=Groups,dc=corp,dc=example,dc=com
  groupObjectClasses: groupOfNames
  membershipLdapAttribute: member

./bobctl add-ldap --config corp-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt

LDAP-Konfiguration vor der Anwendung validieren

Bevor du eine LDAP-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 add-ldap --config my-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt \
  --dry-run

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

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

Überprüft, ob die angegebene CA-Zertifikatsdatei lokal verfügbar ist, wenn --ca-cert-file verwendet wird.

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

Zeigt die Kubernetes-Secrets an, die als Teil der Konfiguration generiert werden würden.

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 LDAP-Konfigurationsdatei erstellt und validiert hast, führe den Befehl add-ldap aus, um die Konfiguration auf den Cluster anzuwenden.

./bobctl add-ldap --config my-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt

Flag	Erforderlich	Beschreibung
`--config <file>`	Ja	Gibt den Pfad zur LDAP-Konfigurationsdatei an.
`--bind-password <password>`	Nein	Erstellt das `bindPasswordSecret` im Cluster. Nicht erforderlich, wenn das Verzeichnis anonymen Bind-Zugriff erlaubt.
`--ca-cert-file <path>`	Nein	Erstellt das `ldapsCACertSecret` aus einer lokalen PEM-Datei. Kann weggelassen werden, wenn eine öffentlich vertrauenswürdige CA oder eine ungesicherte `ldap://`-Verbindung verwendet wird.
`--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 LDAP-Provider, indem er die Statusbedingungen überprüft, die von der benutzerdefinierten BobLDAP-Ressource gemeldet werden.

Prüfung	Was sie bestätigt
`Ready`	Der Provider wurde erfolgreich erstellt und registriert.
`LDAPReachable`	Der LDAP-Server ist vom Cluster aus zugänglich.
`LDAPAuthenticated`	Die konfigurierten Bind-Anmeldeinformationen sind gültig.
`UserSyncSucceeded`	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_LDAP_WAIT_TIMEOUT:

BOB_LDAP_WAIT_TIMEOUT=900 ./bobctl add-ldap --config my-ldap.yaml

Mehrere LDAP-Provider konfigurieren

Um Benutzer aus mehreren LDAP- oder Active-Directory-Quellen zu integrieren, erstelle eine separate Konfigurationsdatei für jedes Verzeichnis und weise im Feld name jeder Konfiguration einen eindeutigen Wert zu.

./bobctl add-ldap --config ldap-corp.yaml
./bobctl add-ldap --config ldap-subsidiary.yaml

LDAP-Ressourcenstatus prüfen

So zeigst du den Status der konfigurierten LDAP-Provider an:

oc get bobldap -n <instance-namespace>

So zeigst du detaillierte Konfigurations- und Statusinformationen für einen bestimmten Provider an:

oc get bobldap <name> -n <instance-namespace> -o yaml

Integration überprüfen

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

Status der benutzerdefinierten BobLDAP-Ressource prüfen:

oc get bobldap <name> -n <instance-namespace> -o yaml

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

Bedingung	Zweck
`Ready`	Bestätigt, dass der LDAP-Provider erfolgreich 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.
`UserSyncSucceeded`	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