Skonfiguruj federację LDAP lub Active Directory dla IBM Bob on-premises za pomocą zasobu niestandardowego BobIDP i polecenia bobctl configure-idp.

Użyj bobctl configure-idp, aby połączyć środowisko LDAP lub Active Directory z Keycloak jako dostawcę federacji użytkowników. Konfigurację można przeprowadzić podczas instalacji lub w dowolnym momencie po wdrożeniu.

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 IDP z dostarczonego szablonu.

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

Plik konfiguracyjny ma dwie sekcje: pola najwyższego poziomu stosowane do całego wdrożenia oraz opcjonalną listę ldaps, gdzie każdy wpis opisuje jednego dostawcę federacji LDAP.

Pola najwyższego poziomu

Pole	Wymagane	Opis
`domains`	Tak	Lista domen e-mail akceptowanych przez Bob przy logowaniu. Usunięcie domeny wyrejestrowuje ją; użytkownicy z tą domeną nie będą mogli się zalogować.
`adminEmails`	Nie	Lista adresów e-mail użytkowników, którym ma zostać przyznany dostęp administratora Bob. Operator atomowo aktualizuje zarówno grupę `bob-admins` w Keycloak, jak i bazę danych administratorów Bob.
`ldaps`	Nie	Lista konfiguracji dostawców federacji LDAP. Pomiń całkowicie w przypadku wdrożeń korzystających wyłącznie z bezpośrednich użytkowników Keycloak.

Pola wymagane (na wpis dostawcy LDAP)

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.

Ważne:

Pole domains jest jedyną 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 prawidłowa metoda i może powodować błędy uwierzytelniania.

Pola opcjonalne (na wpis dostawcy LDAP)

Pole	Opis
`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`	Nazwa istniejącego wcześniej Secretu zawierającego hasło konta bind. Musi zostać utworzony w przestrzeni nazw instancji przed uruchomieniem `bobctl configure-idp`.
`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`	Nazwa istniejącego wcześniej Secretu zawierającego certyfikat CA serwera LDAP w formacie PEM. Musi zostać utworzony w przestrzeni nazw instancji przed uruchomieniem `bobctl configure-idp`.
`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. Dzięki synchronizacji grup użytkownicy i członkostwa w grupach z katalogu LDAP są importowani i zarządzani 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ę. Nie są uwzględniane w 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

# Domeny e-mail akceptowane przez Bob przy logowaniu
domains:
  - corp.example.com

# Użytkownicy, którym ma zostać przyznany dostęp administratora Bob
adminEmails:
  - alice@corp.example.com

# Dostawcy federacji LDAP
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

    # Opcjonalnie: synchronizacja grup LDAP z Keycloak
    groupMapper:
      groupsDn: ou=Groups,dc=corp,dc=example,dc=com
      groupObjectClasses: groupOfNames
      membershipLdapAttribute: member

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

Walidacja konfiguracji IDP przed jej zastosowaniem

Przed zastosowaniem konfiguracji IDP 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 configure-idp --config my-idp.yaml --dry-run

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

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

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

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 IDP uruchom polecenie configure-idp, aby zastosować konfigurację w klastrze.

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

Flaga	Wymagana	Opis
`--config <file>`	Tak	Określa ścieżkę do pliku konfiguracyjnego IDP.
`--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 IDP, sprawdzając warunki stanu zgłaszane przez zasób niestandardowy BobIDP.

Kontrola	Co potwierdza
`Ready`	Konfiguracja została pomyślnie zastosowana.
`LDAPRegistered`	Dostawca LDAP został zarejestrowany w Keycloak.
`LDAPReachable`	Serwer LDAP jest dostępny z klastra.
`LDAPAuthenticated`	Skonfigurowane poświadczenia bind są prawidłowe.
`LDAPUserSyncSucceeded`	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_IDP_WAIT_TIMEOUT:

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

Konfiguracja wielu dostawców LDAP

Aby zintegrować użytkowników z wielu źródeł LDAP lub Active Directory, dodaj każdy katalog jako oddzielny wpis na liście ldaps w pliku konfiguracyjnym IDP i uruchom ponownie configure-idp.

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

Sprawdzanie stanu zasobów IDP

Aby wyświetlić stan konfiguracji IDP:

oc get bobidp -n <instance-namespace>

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

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

Weryfikacja integracji

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

Sprawdź stan zasobu niestandardowego BobIDP:

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

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

Warunek	Przeznaczenie
`Ready`	Potwierdza, że konfiguracja została pomyślnie zastosowana.
`LDAPRegistered`	Potwierdza, że dostawca LDAP został zarejestrowany w Keycloak.
`LDAPReachable`	Potwierdza, że klaster może komunikować się z serwerem LDAP.
`LDAPAuthenticated`	Potwierdza, że skonfigurowane poświadczenia bind są prawidłowe.
`LDAPUserSyncSucceeded`	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