Skonfiguruj federację LDAP lub Active Directory dla IBM Bob on-premises za pomocą zasobu niestandardowego BobLDAP i polecenia bobctl add-ldap.

Bob on-premises integruje środowisko LDAP lub Active Directory z Keycloak za pomocą narzędzia bobctl, które konfiguruje katalog jako dostawcę federacji użytkowników Keycloak. Chociaż integracja ta jest zwykle konfigurowana podczas instalacji, można ją również skonfigurować, zaktualizować lub obsługiwać po wdrożeniu w ramach bieżących działań związanych z zarządzaniem użytkownikami.

Zanim rozpoczniesz

Przed skonfigurowaniem federacji LDAP upewnij się, że spełnione są następujące wymagania:

Klaster OpenShift Container Platform (OCP) ma łączność sieciową z serwerem LDAP na odpowiednim porcie:

389 dla ldap://
636 dla ldaps://

Dostępne jest konto usługowe (bind DN) z uprawnieniami do odczytu katalogu lub serwer LDAP jest skonfigurowany tak, aby zezwalać na anonimowe powiązania (anonymous binds).

W przypadku korzystania z ldaps:// z prywatnym lub wewnętrznie podpisanym urzędem certyfikacji (CA), uzyskaj certyfikat CA serwera LDAP w formacie PEM.

Narzędzie wiersza poleceń bobctl jest zainstalowane, a oc jest skonfigurowane i uwierzytelnione w klastrze docelowym.

Informacje o pliku konfiguracyjnym

Przed zarejestrowaniem dostawcy LDAP utwórz plik konfiguracyjny LDAP z dostarczonego szablonu.

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

Plik konfiguracyjny zawiera wymagane i opcjonalne parametry, które określają, w jaki sposób Bob łączy się, uwierzytelnia i synchronizuje użytkowników z Twojego katalogu LDAP.

Pola wymagane

Pole	Opis
`name`	Unikalny, opisowy identyfikator dostawcy LDAP. Każdy skonfigurowany dostawca musi mieć unikalną nazwę.
`vendor`	Określa typ katalogu LDAP do integracji. Obsługiwane wartości: `other` (OpenLDAP i zgodne z LDAPv3), `ad` (Microsoft Active Directory), `rhds` (Red Hat Directory Server), `tivoli` (IBM Security Directory Server), `edirectory` (NetIQ eDirectory).
`connectionUrl`	Kompletny adres URL serwera LDAP, w tym protokół (`ldap://` lub `ldaps://`), nazwa hosta i numer portu.
`usersDn`	Lokalizacja katalogu, w której przechowywane są konta użytkowników i z której wpisy użytkowników są wyszukiwane i importowane.
`usernameLDAPAttribute`	Atrybut katalogu, który użytkownicy podają jako nazwę użytkownika podczas uwierzytelniania.
`rdnLDAPAttribute`	Atrybut katalogu używany do identyfikacji wpisów w strukturze katalogu. W większości konfiguracji jest to to samo co `usernameLDAPAttribute`.
`uuidLDAPAttribute`	Unikalny, stabilny, niezmienny atrybut katalogu używany do trwałej identyfikacji każdego konta użytkownika.
`userObjectClasses`	Rozdzielana przecinkami lista klas obiektów LDAP, które określają, które wpisy katalogowe są rozpoznawane i przetwarzane jako konta użytkowników.
`domains`	Jedna lub więcej domen poczty e-mail skojarzonych z katalogiem. Podczas uwierzytelniania użytkownicy, których adresy e-mail pasują do dowolnej ze skonfigurowanych domen, są automatycznie kierowani do tego dostawcy LDAP w celu weryfikacji poświadczeń.

Ważne:

Parametr domains jest jedyną obsługiwaną metodą konfigurowania routingu opartego na domenach we wdrożeniach on-premises. Nie konfiguruj domen za pośrednictwem interfejsu użytkownika administracji Bob, ponieważ nie jest to obsługiwane i może powodować błędy uwierzytelniania.

Pola opcjonalne

Pole	Opis
`adminEmails`	Adresy e-mail użytkowników, którym mają zostać przyznane uprawnienia administracyjne. Bob automatycznie przypisuje dostęp administratora tym użytkownikom.
`bindDn`	DN konta usługowego używanego do uwierzytelniania i łączenia się z katalogiem. Można pominąć, jeśli katalog zezwala na anonimowy dostęp bind.
`bindPasswordSecret`	Odwołuje się do Secretu przechowującego hasło konta bind. Ten Secret jest tworzony automatycznie, gdy opcja `--bind-password` zostanie podana z poleceniem `bobctl`.
`useTruststoreSpi`	Określa, kiedy certyfikat CA LDAP jest używany do weryfikacji serwera. Wartości: `always` (domyślnie, dla certyfikatów CA prywatnych lub wydanych wewnętrznie), `ldapsOnly` (dla publicznie zaufanych certyfikatów CA), `never` (w przypadku łączenia przez niezabezpieczony protokół `ldap://`).
`ldapsCACertSecret`	Odwołuje się do Secretu zawierającego certyfikat CA serwera LDAP w formacie PEM. Ten Secret jest tworzony automatycznie, gdy podano `--ca-cert-file`.
`searchScope`	Określa głębokość przeszukiwania katalogu. `2` przeszukuje wszystkie kontenery podrzędne i poddrzewa (domyślnie); `1` ogranicza wyszukiwanie tylko do bezpośrednich wpisów podrzędnych.
`customUserSearchFilter`	Dodatkowy filtr stosowany do wszystkich operacji wyszukiwania użytkowników, na przykład w celu wykluczenia kont usługowych lub ograniczenia wyszukiwania do określonych typów użytkowników.
`userSync.enabled`	Po ustawieniu na `true` wszyscy użytkownicy są importowani po początkowej konfiguracji dostawcy, a kolejne zmiany w katalogu są synchronizowane co pięć minut. Zalecane dla większości wdrożeń.
`userAttributeMappings`	Definiuje sposób mapowania atrybutów katalogu na pola profilu użytkownika Bob, takie jak `email`, `firstName` i `lastName`.
`priority`	Określa kolejność, w jakiej dostawcy są oceniani, gdy skonfigurowano wielu dostawców. Dostawcy o niższych wartościach są sprawdzani jako pierwsi. Domyślnie `0`.
`groupMapper`	Synchronizuje grupy LDAP z Keycloak. Zobacz Konfiguracja synchronizacji grup LDAP.

Zachowanie synchronizacji użytkowników

Gdy userSync.enabled jest ustawione na true, Bob wykonuje jednorazowy import wszystkich użytkowników po zarejestrowaniu dostawcy LDAP. Po zakończeniu początkowego importu bieżąca synchronizacja cyklu życia użytkowników jest obsługiwana automatycznie za pośrednictwem SCIM.

Wskazówka:

W przypadku dużych katalogów LDAP warto rozważyć pozostawienie userSync.enabled ustawionego na false i umożliwienie aprowizacji użytkowników przy ich pierwszym logowaniu. Takie podejście może skrócić czas wymagany do zarejestrowania dostawcy LDAP.

Konfiguracja synchronizacji grup LDAP

Użyj opcjonalnej konfiguracji groupMapper, aby zsynchronizować grupy LDAP z Keycloak. Synchronizacja grup umożliwia importowanie użytkowników i członkostw w grupach zdefiniowanych w katalogu LDAP oraz zarządzanie nimi za pośrednictwem Keycloak.

Parametr groupsDn jest wymagany. Wszystkie pozostałe parametry są opcjonalne i można je dostosować do schematu katalogu LDAP oraz struktury grup.

Ograniczenie:

Grupy bob-admins i bob-users są grupami zarządzanymi przez platformę i są automatycznie wykluczane z synchronizacji grup LDAP.

Parametr	Wartość domyślna	Opis
`groupsDn`	Wymagany	Bazowa unikalna nazwa (DN) zawierająca wpisy grup LDAP.
`name`	`groups`	Nazwa wyświetlana mappera grup w Keycloak.
`groupNameLdapAttribute`	`cn`	Atrybut LDAP, którego Keycloak używa jako nazwy grupy.
`groupObjectClasses`	`groupOfNames`	Klasa lub klasy obiektów LDAP identyfikujące wpisy grup.
`membershipLdapAttribute`	`member`	Atrybut we wpisie grupy zawierający informacje o członkach.
`membershipAttributeType`	`DN`	Format wartości elementów członkowskich. Obsługiwane wartości: `DN` (nazwy wyróżniające) i `UID` (identyfikatory użytkowników).
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Metoda używana do określania członkostwa w grupach.
`memberOfLdapAttribute`	`memberOf`	Atrybut użytkownika zawierający informacje o członkostwie w grupie w przypadku użycia `GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`.
`customGroupSearchFilter`	Brak	Dodatkowy filtr LDAP używany podczas wyszukiwania grup. Filtr musi być ujęty w nawiasy, na przykład `(cn=dept-*)`.
`mode`	`LDAP_ONLY`	Tryb synchronizacji. Obsługiwane wartości: `LDAP_ONLY` i `READ_ONLY`.
`groupsPath`	`/`	Lokalizacja w hierarchii grup Keycloak, w której tworzone są zsynchronizowane grupy.

Strategie pobierania członkostwa w grupach

Parametr userRolesRetrieveStrategy kontroluje, w jaki sposób Keycloak identyfikuje członkostwo użytkownika w grupach.

Strategia	Opis
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Pobiera członkostwa w grupach, przeszukując wpisy grup zawierające odwołania do użytkowników.
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	Pobiera członkostwa w grupach z atrybutu `memberOf` użytkownika.
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	Pobiera członkostwa w grupach rekurencyjnie, w tym grupy zagnieżdżone, jeśli jest to obsługiwane przez katalog LDAP.

Wskazówka:

Użyj LOAD_GROUPS_BY_MEMBER_ATTRIBUTE, chyba że katalog LDAP przechowuje informacje o członkostwie w grupie we wpisach użytkowników za pośrednictwem atrybutu memberOf lub używa zagnieżdżonych struktur grup wymagających wyszukiwania rekurencyjnego.

Przykładowa konfiguracja

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

# Opcjonalnie: synchronizacja grup LDAP z 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

Walidacja konfiguracji LDAP przed jej zastosowaniem

Przed zastosowaniem konfiguracji LDAP w klastrze użyj opcji --dry-run, aby zweryfikować konfigurację i wyświetlić podgląd zasobów, które zostałyby utworzone. Uruchomienie przebiegu próbnego (dry run) może pomóc w zidentyfikowaniu typowych problemów z konfiguracją przed wprowadzeniem jakichkolwiek zmian w klastrze.

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

Przebieg próbny wykonuje następujące kontrole:

Sprawdza, czy wszystkie wymagane parametry konfiguracyjne są obecne w pliku konfiguracyjnym.

Weryfikuje, czy określony plik certyfikatu CA jest dostępny lokalnie, gdy używana jest opcja --ca-cert-file.

Wyświetla podgląd zasobu niestandardowego BobLDAP, który zostałby utworzony lub zaktualizowany.

Pokazuje sekrety Kubernetes, które zostałyby wygenerowane w ramach konfiguracji.

Kończy działanie bez tworzenia, modyfikowania ani usuwania jakichkolwiek zasobów w klastrze.

Uwaga:

Operacja dry-run nie weryfikuje łączności sieciowej z serwerem LDAP, nie uwierzytelnia podanych poświadczeń w katalogu ani nie potwierdza istnienia przywoływanych obiektów Secret w klastrze. Te kontrole są wykonywane dopiero po zastosowaniu konfiguracji i są odzwierciedlane w warunkach stanu LDAPReachable i LDAPAuthenticated.

Stosowanie konfiguracji

Po utworzeniu i sprawdzeniu poprawności pliku konfiguracyjnego LDAP uruchom polecenie add-ldap, aby zastosować konfigurację w klastrze.

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

Flaga	Wymagana	Opis
`--config <file>`	Tak	Określa ścieżkę do pliku konfiguracyjnego LDAP.
`--bind-password <password>`	Nie	Tworzy `bindPasswordSecret` w klastrze. Nie jest wymagane, gdy katalog zezwala na anonimowy dostęp bind.
`--ca-cert-file <path>`	Nie	Tworzy `ldapsCACertSecret` z lokalnego pliku PEM. Można pominąć w przypadku korzystania z publicznie zaufanego urzędu certyfikacji lub niezabezpieczonego połączenia `ldap://`.
`--dry-run`	Nie	Weryfikuje konfigurację i wyświetla podgląd zasobów, które zostałyby utworzone lub zaktualizowane, bez wprowadzania jakichkolwiek zmian w klastrze.

Po uruchomieniu polecenia bobctl czeka, aż operator uzgodni konfigurację i zwaliduje dostawcę LDAP, sprawdzając warunki stanu zgłaszane przez zasób niestandardowy BobLDAP.

Kontrola	Co potwierdza
`Ready`	Dostawca został pomyślnie utworzony i zarejestrowany.
`LDAPReachable`	Serwer LDAP jest dostępny z klastra.
`LDAPAuthenticated`	Skonfigurowane poświadczenia bind są prawidłowe.
`UserSyncSucceeded`	Początkowy import użytkowników zakończył się pomyślnie. Ten warunek jest oceniany tylko wtedy, gdy `userSync.enabled` jest ustawione na `true`.

Domyślny limit czasu weryfikacji wynosi 600 sekund (10 minut). W środowiskach z dużymi katalogami początkowa synchronizacja użytkowników może zająć kilka minut. Aby zwiększyć limit czasu, ustaw zmienną środowiskową BOB_LDAP_WAIT_TIMEOUT:

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

Konfiguracja wielu dostawców LDAP

Aby zintegrować użytkowników z wielu źródeł LDAP lub Active Directory, utwórz oddzielny plik konfiguracyjny dla każdego katalogu i przypisz unikalną wartość do pola name w każdej konfiguracji.

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

Sprawdzanie stanu zasobów LDAP

Aby wyświetlić stan skonfigurowanych dostawców LDAP:

oc get bobldap -n <instance-namespace>

Aby wyświetlić szczegółowe informacje o konfiguracji i stanie określonego dostawcy:

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

Weryfikacja integracji

Po pomyślnym zakończeniu działania polecenia bobctl add-ldap sprawdź, czy integracja LDAP działa prawidłowo.

Sprawdź stan zasobu niestandardowego BobLDAP:

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

Sprawdź, czy następujące warunki stanu są ustawione na True:

Warunek	Przeznaczenie
`Ready`	Potwierdza, że dostawca LDAP został pomyślnie zarejestrowany.
`LDAPReachable`	Potwierdza, że klaster może komunikować się z serwerem LDAP.
`LDAPAuthenticated`	Potwierdza, że skonfigurowane poświadczenia bind są prawidłowe.
`UserSyncSucceeded`	Potwierdza, że wszyscy użytkownicy zostali pomyślnie zaimportowani. Obecne tylko wtedy, gdy `userSync.enabled: true`.

Jeśli jakikolwiek warunek ma wartość False, przejrzyj odpowiednie pole message, aby uzyskać szczegóły diagnostyczne.

Zaloguj się przy użyciu poświadczeń ze sfederowanego katalogu LDAP, aby sprawdzić, czy uwierzytelnianie użytkowników działa.

Otwórz adres URL Bob:

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

Pomyślne logowanie potwierdza, że łączność, uwierzytelnianie, routing domen, aprowizacja SCIM i mapowanie ról działają poprawnie.

Po pierwszym zalogowaniu się użytkownika upewnij się, że rekord użytkownika jest dostępny w Bob.

Otwórz interfejs administracyjny Bob:

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

Zaloguj się jako administrator Bob i sprawdź, czy użytkownik testowy pojawia się na liście użytkowników.

Jeśli parametr groupMapper jest skonfigurowany do mapowania grupy LDAP na administratorów Bob:

Zaloguj się za pomocą konta użytkownika należącego do zmapowanej grupy administratorów.
Potwierdź, że użytkownik ma dostęp do interfejsu administracyjnego Bob.
Sprawdź, czy funkcje na poziomie administratora są dostępne.

Jeśli userSync.enabled: true, użytkownicy są importowani automatycznie po zarejestrowaniu dostawcy LDAP. Użytkownik testowy powinien pojawić się w Bob bez konieczności początkowego logowania.

Jeśli użytkownik nie pojawi się po kilku minutach, przejrzyj dzienniki bob-admin pod kątem błędów aprowizacji:

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

Przejrzyj wszelkie zgłoszone błędy związane z SCIM i rozwiąż je przed ponowną próbą procesu synchronizacji.

Integracja LDAP