Configura la federazione LDAP o Active Directory per IBM Bob on-premises usando la custom resource BobLDAP e il comando bobctl add-ldap.

Bob on-premises integra il tuo ambiente LDAP o Active Directory con Keycloak tramite l'utility bobctl, che configura la directory come provider di federazione utenti Keycloak. Sebbene questa integrazione venga solitamente configurata durante l'installazione, può anche essere configurata, aggiornata o mantenuta dopo il deployment come parte delle attività di gestione degli utenti in corso.

Prima di iniziare

Prima di configurare la federazione LDAP, assicurati che i seguenti requisiti siano soddisfatti:

Il cluster OpenShift Container Platform (OCP) ha connettività di rete al server LDAP sulla porta appropriata:

389 per ldap://
636 per ldaps://

È disponibile un account di servizio (bind DN) con accesso in lettura alla directory, oppure il server LDAP è configurato per consentire i bind anonimi.

Se stai usando ldaps:// con una certificate authority (CA) privata o firmata internamente, ottieni il certificato CA del server LDAP in formato PEM.

L'utility della riga di comando bobctl è installata e oc è configurato e autenticato nel cluster di destinazione.

Riferimento al file di configurazione

Crea un file di configurazione LDAP dal template fornito prima di registrare un provider LDAP.

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

Il file di configurazione contiene parametri obbligatori e opzionali che definiscono come Bob si connette, si autentica e sincronizza gli utenti dalla tua directory LDAP.

Campi obbligatori

Campo	Descrizione
`name`	Un identificatore univoco e descrittivo per il provider LDAP. Ogni provider configurato deve avere un nome distinto.
`vendor`	Specifica il tipo di directory LDAP con cui integrarsi. Valori supportati: `other` (OpenLDAP e compatibili LDAPv3), `ad` (Microsoft Active Directory), `rhds` (Red Hat Directory Server), `tivoli` (IBM Security Directory Server), `edirectory` (NetIQ eDirectory).
`connectionUrl`	L'URL completo del server LDAP, inclusi il protocollo (`ldap://` o `ldaps://`), il hostname e il numero di porta.
`usersDn`	La posizione nella directory dove sono memorizzati gli account utente e da cui vengono cercati e importati i record degli utenti.
`usernameLDAPAttribute`	L'attributo della directory che gli utenti forniscono come nome utente durante l'autenticazione.
`rdnLDAPAttribute`	L'attributo della directory utilizzato per identificare i record nella struttura della directory. Nella maggior parte delle configurazioni, è uguale a `usernameLDAPAttribute`.
`uuidLDAPAttribute`	Un attributo della directory univoco, stabile e non modificabile utilizzato per identificare in modo permanente ogni account utente.
`userObjectClasses`	Un elenco separato da virgole di classi di oggetti LDAP che definiscono quali record della directory vengono riconosciuti ed elaborati come account utente.
`domains`	Uno o più domini email associati alla directory. Durante l'autenticazione, gli utenti i cui indirizzi email corrispondono a uno dei domini configurati vengono automaticamente instradati a questo provider LDAP per la validazione delle credenziali.

Importante:

Il parametro domains è l'unico metodo supportato per configurare il routing basato sul dominio nei deployment on-premises. Non configurare i domini tramite l'interfaccia utente di amministrazione di Bob perché non è supportato e può causare errori di autenticazione.

Campi opzionali

Campo	Descrizione
`adminEmails`	Indirizzi email degli utenti a cui concedere privilegi amministrativi. Bob assegna automaticamente l'accesso amministratore a questi utenti.
`bindDn`	Il DN dell'account di servizio utilizzato per autenticarsi e connettersi alla directory. Può essere omesso se la directory consente l'accesso con bind anonimo.
`bindPasswordSecret`	Fa riferimento al Secret che memorizza la password dell'account bind. Questo Secret viene creato automaticamente quando l'opzione `--bind-password` viene fornita con il comando `bobctl`.
`useTruststoreSpi`	Specifica quando il certificato CA LDAP viene utilizzato per la validazione del server. Valori: `always` (predefinito, per certificati CA privati o emessi internamente), `ldapsOnly` (per certificati CA pubblicamente attendibili), `never` (quando ci si connette tramite `ldap://` non sicuro).
`ldapsCACertSecret`	Fa riferimento al Secret che contiene il certificato CA del server LDAP in formato PEM. Questo Secret viene creato automaticamente quando viene fornito `--ca-cert-file`.
`searchScope`	Determina la profondità delle ricerche nella directory. `2` cerca tutti i contenitori figli e i sottoalberi (predefinito); `1` limita le ricerche ai soli record figli diretti.
`customUserSearchFilter`	Un filtro aggiuntivo applicato a tutte le operazioni di ricerca utenti, ad esempio per escludere account di servizio o limitare le ricerche a tipi di utenti specifici.
`userSync.enabled`	Quando impostato su `true`, tutti gli utenti vengono importati quando il provider viene inizialmente configurato e le successive modifiche alla directory vengono sincronizzate ogni cinque minuti. Consigliato per la maggior parte dei deployment.
`userAttributeMappings`	Definisce come gli attributi della directory vengono mappati ai campi del profilo utente Bob, come `email`, `firstName` e `lastName`.
`priority`	Determina l'ordine in cui i provider vengono valutati quando sono configurati più provider. I provider con valori più bassi vengono controllati per primi. Il valore predefinito è `0`.
`groupMapper`	Sincronizza i gruppi LDAP in Keycloak. Vedere Configurazione della sincronizzazione dei gruppi LDAP.

Comportamento della sincronizzazione utenti

Quando userSync.enabled è impostato su true, Bob esegue un'importazione una tantum di tutti gli utenti quando il provider LDAP viene registrato. Al termine dell'importazione iniziale, la sincronizzazione continua del ciclo di vita degli utenti viene gestita automaticamente tramite SCIM.

Suggerimento:

Per le directory LDAP di grandi dimensioni, considera di lasciare userSync.enabled impostato su false e consentire il provisioning degli utenti al loro primo accesso. Questo approccio può ridurre il tempo necessario per registrare il provider LDAP.

Configurazione della sincronizzazione dei gruppi LDAP

Usa la configurazione opzionale groupMapper per sincronizzare i gruppi LDAP con Keycloak. La sincronizzazione dei gruppi consente di importare e gestire tramite Keycloak gli utenti e le appartenenze ai gruppi definiti nella directory LDAP.

Il parametro groupsDn è obbligatorio. Tutti gli altri parametri sono opzionali e possono essere personalizzati per corrispondere allo schema della directory LDAP e alla struttura dei gruppi.

Restrizione:

I gruppi bob-admins e bob-users sono gruppi gestiti dalla piattaforma e vengono esclusi automaticamente dalla sincronizzazione dei gruppi LDAP.

Parametro	Valore predefinito	Descrizione
`groupsDn`	Obbligatorio	Distinguished name (DN) base che contiene i record dei gruppi LDAP.
`name`	`groups`	Nome visualizzato del group mapper in Keycloak.
`groupNameLdapAttribute`	`cn`	Attributo LDAP che Keycloak usa come nome del gruppo.
`groupObjectClasses`	`groupOfNames`	Classe o classi di oggetti LDAP che identificano i record dei gruppi.
`membershipLdapAttribute`	`member`	Attributo nel record del gruppo che contiene le informazioni sui membri.
`membershipAttributeType`	`DN`	Formato dei valori dei membri. Valori supportati: `DN` (distinguished name) e `UID` (ID utente).
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Metodo utilizzato per determinare le appartenenze ai gruppi.
`memberOfLdapAttribute`	`memberOf`	Attributo utente contenente le informazioni sull'appartenenza ai gruppi quando viene usato `GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`.
`customGroupSearchFilter`	Nessuno	Filtro LDAP aggiuntivo utilizzato durante la ricerca di gruppi. Il filtro deve essere racchiuso tra parentesi, ad esempio `(cn=dept-*)`.
`mode`	`LDAP_ONLY`	Modalità di sincronizzazione. Valori supportati: `LDAP_ONLY` e `READ_ONLY`.
`groupsPath`	`/`	Posizione nella gerarchia dei gruppi Keycloak dove vengono creati i gruppi sincronizzati.

Strategie di recupero delle appartenenze ai gruppi

Il parametro userRolesRetrieveStrategy controlla come Keycloak identifica le appartenenze ai gruppi di un utente.

Strategia	Descrizione
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Recupera le appartenenze ai gruppi cercando i record dei gruppi che contengono riferimenti agli utenti.
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	Recupera le appartenenze ai gruppi dall'attributo `memberOf` dell'utente.
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	Recupera le appartenenze ai gruppi in modo ricorsivo, inclusi i gruppi annidati dove supportato dalla directory LDAP.

Suggerimento:

Usa LOAD_GROUPS_BY_MEMBER_ATTRIBUTE a meno che la tua directory LDAP non memorizzi le informazioni sull'appartenenza ai gruppi nei record degli utenti tramite l'attributo memberOf o utilizzi strutture di gruppi annidati che richiedono ricerche ricorsive.

Esempio di configurazione

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

Validazione di una configurazione LDAP prima dell'applicazione

Prima di applicare una configurazione LDAP al cluster, usa l'opzione --dry-run per validare la configurazione e visualizzare in anteprima le risorse che verrebbero create. L'esecuzione di un dry run può aiutare a identificare problemi di configurazione comuni prima che vengano apportate modifiche al cluster.

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

Il dry run esegue i seguenti controlli:

Verifica che tutti i parametri di configurazione obbligatori siano presenti nel file di configurazione.

Verifica che il file del certificato CA specificato sia disponibile localmente quando viene usato --ca-cert-file.

Visualizza un'anteprima della custom resource BobLDAP che verrebbe creata o aggiornata.

Mostra i Secret Kubernetes che verrebbero generati come parte della configurazione.

Esce senza creare, modificare o eliminare risorse nel cluster.

Nota:

L'operazione di dry run non valida la connettività di rete al server LDAP, non autentica le credenziali fornite nella directory e non conferma l'esistenza dei Secret referenziati nel cluster. Queste validazioni vengono eseguite solo dopo l'applicazione della configurazione e si riflettono nelle condizioni di stato LDAPReachable e LDAPAuthenticated.

Applicazione della configurazione

Dopo aver creato e validato il file di configurazione LDAP, esegui il comando add-ldap per applicare la configurazione al cluster.

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

Flag	Obbligatorio	Descrizione
`--config <file>`	Sì	Specifica il percorso del file di configurazione LDAP.
`--bind-password <password>`	No	Crea il `bindPasswordSecret` nel cluster. Non richiesto quando la directory consente l'accesso con bind anonimo.
`--ca-cert-file <path>`	No	Crea il `ldapsCACertSecret` da un file PEM locale. Può essere omesso quando si usa una CA pubblicamente attendibile o una connessione `ldap://` non sicura.
`--dry-run`	No	Valida la configurazione e visualizza un'anteprima delle risorse che verrebbero create o aggiornate, senza applicare alcuna modifica al cluster.

Quando il comando viene eseguito, bobctl attende che l'operator riconcili la configurazione e valida il provider LDAP controllando le condizioni di stato riportate dalla custom resource BobLDAP.

Controllo	Cosa conferma
`Ready`	Il provider è stato creato e registrato correttamente.
`LDAPReachable`	Il server LDAP è accessibile dal cluster.
`LDAPAuthenticated`	Le credenziali bind configurate sono valide.
`UserSyncSucceeded`	L'importazione iniziale degli utenti è stata completata correttamente. Questa condizione viene valutata solo quando `userSync.enabled` è impostato su `true`.

Il timeout di validazione predefinito è di 600 secondi (10 minuti). Negli ambienti con directory di grandi dimensioni, la sincronizzazione iniziale degli utenti può richiedere diversi minuti. Per aumentare il timeout, imposta la variabile di ambiente BOB_LDAP_WAIT_TIMEOUT:

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

Configurazione di più provider LDAP

Per integrare utenti da più sorgenti LDAP o Active Directory, crea un file di configurazione separato per ogni directory e assegna un valore univoco al campo name in ogni configurazione.

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

Ispezione dello stato delle risorse LDAP

Per visualizzare lo stato dei provider LDAP configurati:

oc get bobldap -n <instance-namespace>

Per visualizzare informazioni dettagliate sulla configurazione e sullo stato di un provider specifico:

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

Verifica dell'integrazione

Dopo che bobctl add-ldap è completato correttamente, verifica che l'integrazione LDAP funzioni correttamente.

Verifica lo stato della custom resource BobLDAP:

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

Verifica che le seguenti condizioni di stato siano impostate su True:

Condizione	Scopo
`Ready`	Conferma che il provider LDAP è stato registrato correttamente.
`LDAPReachable`	Conferma che il cluster può comunicare con il server LDAP.
`LDAPAuthenticated`	Conferma che le credenziali bind configurate sono valide.
`UserSyncSucceeded`	Conferma che tutti gli utenti sono stati importati correttamente. Presente solo quando `userSync.enabled: true`.

Se una condizione è False, esamina il campo message corrispondente per i dettagli diagnostici.

Accedi usando le credenziali della directory LDAP federata per verificare che l'autenticazione degli utenti funzioni.

Apri l'URL di Bob:

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

Un accesso riuscito conferma che la connettività, l'autenticazione, il routing del dominio, il provisioning SCIM e la mappatura dei ruoli funzionano correttamente.

Dopo che l'utente ha effettuato l'accesso per la prima volta, conferma che il record dell'utente sia disponibile in Bob.

Apri l'interfaccia utente di amministrazione Bob:

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

Accedi come amministratore Bob e verifica che l'utente di test appaia nell'elenco degli utenti.

Se groupMapper è configurato per mappare un gruppo LDAP agli amministratori Bob:

Accedi con un account utente che appartiene al gruppo amministratore mappato.
Conferma che l'utente possa accedere all'interfaccia utente di amministrazione Bob.
Verifica che le funzioni a livello amministratore siano disponibili.

Se userSync.enabled: true, gli utenti vengono importati automaticamente dopo la registrazione del provider LDAP. L'utente di test dovrebbe apparire in Bob senza richiedere un accesso iniziale.

Se l'utente non appare dopo diversi minuti, esamina i log di bob-admin per gli errori di provisioning:

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

Esamina gli errori SCIM riportati e risolvili prima di riprovare il processo di sincronizzazione.

Integrazione LDAP