Configura la federazione LDAP o Active Directory per IBM Bob on-premises usando la custom resource BobIDP e il comando bobctl configure-idp.

Usa bobctl configure-idp per connettere il tuo ambiente LDAP o Active Directory a Keycloak come provider di federazione utenti. Puoi completare questa configurazione durante l'installazione o in qualsiasi momento dopo il deployment.

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 IDP dal template fornito prima di registrare un provider LDAP.

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

Il file di configurazione ha due sezioni: campi di primo livello che si applicano all'intero deployment e un elenco opzionale ldaps in cui ogni voce descrive un provider di federazione LDAP.

Campi di primo livello

Campo	Obbligatorio	Descrizione
`domains`	Sì	Elenco di domini email che Bob accetta al login. La rimozione di un dominio ne annulla la registrazione; gli utenti con quel dominio non potranno accedere.
`adminEmails`	No	Elenco di email di utenti a cui concedere l'accesso amministratore a Bob. L'operator aggiorna sia il gruppo Keycloak `bob-admins` che il database degli amministratori di Bob in modo atomico.
`ldaps`	No	Elenco di configurazioni dei provider di federazione LDAP. Ometti completamente per i deployment che utilizzano solo utenti Keycloak diretti.

Campi obbligatori (per voce di provider LDAP)

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.

Importante:

Il campo domains è l'unico modo 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 è il metodo corretto e può causare errori di autenticazione.

Campi opzionali (per voce di provider LDAP)

Campo	Descrizione
`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`	Nome di un Secret preesistente contenente la password dell'account bind. Deve essere creato nel namespace dell'istanza prima di eseguire `bobctl configure-idp`.
`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`	Nome di un Secret preesistente contenente il certificato CA del server LDAP in formato PEM. Deve essere creato nel namespace dell'istanza prima di eseguire `bobctl configure-idp`.
`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. Con la sincronizzazione dei gruppi, gli utenti e le appartenenze ai gruppi della tua directory LDAP vengono importati e gestiti tramite Keycloak.

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. Non sono inclusi nella 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

# Email domains Bob should accept at login
domains:
  - corp.example.com

# Users to be granted Bob admin access
adminEmails:
  - alice@corp.example.com

# LDAP federation providers
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: synchronize LDAP groups into Keycloak
    groupMapper:
      groupsDn: ou=Groups,dc=corp,dc=example,dc=com
      groupObjectClasses: groupOfNames
      membershipLdapAttribute: member

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

Validazione di una configurazione IDP prima dell'applicazione

Prima di applicare una configurazione IDP 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 configure-idp --config my-idp.yaml --dry-run

Il dry run esegue i seguenti controlli:

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

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

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 IDP, esegui il comando configure-idp per applicare la configurazione al cluster.

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

Flag	Obbligatorio	Descrizione
`--config <file>`	Sì	Specifica il percorso del file di configurazione IDP.
`--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 l'IDP controllando le condizioni di stato riportate dalla custom resource BobIDP.

Controllo	Cosa conferma
`Ready`	La configurazione è stata applicata correttamente.
`LDAPRegistered`	Il provider LDAP è stato registrato in Keycloak.
`LDAPReachable`	Il server LDAP è accessibile dal cluster.
`LDAPAuthenticated`	Le credenziali bind configurate sono valide.
`LDAPUserSyncSucceeded`	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_IDP_WAIT_TIMEOUT:

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

Configurazione di più provider LDAP

Per integrare utenti da più sorgenti LDAP o Active Directory, aggiungi ciascuna directory come voce separata nell'elenco ldaps del file di configurazione IDP ed esegui nuovamente configure-idp.

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

Ispezione dello stato delle risorse IDP

Per visualizzare lo stato della configurazione IDP:

oc get bobidp -n <instance-namespace>

Per visualizzare informazioni dettagliate sulla configurazione e sullo stato:

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

Verifica dell'integrazione

Dopo che bobctl configure-idp è completato correttamente, verifica che l'integrazione LDAP funzioni correttamente.

Verifica lo stato della custom resource BobIDP:

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

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

Condizione	Scopo
`Ready`	Conferma che la configurazione è stata applicata correttamente.
`LDAPRegistered`	Conferma che il provider LDAP è stato registrato in Keycloak.
`LDAPReachable`	Conferma che il cluster può comunicare con il server LDAP.
`LDAPAuthenticated`	Conferma che le credenziali bind configurate sono valide.
`LDAPUserSyncSucceeded`	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