Configura la federación LDAP o Active Directory para IBM Bob on-premises usando el recurso personalizado BobLDAP y el comando bobctl add-ldap.

Bob on-premises integra tu entorno LDAP o Active Directory con Keycloak a través de la utilidad bobctl, que configura el directorio como un proveedor de federación de usuarios de Keycloak. Aunque esta integración suele configurarse durante la instalación, también puede configurarse, actualizarse o mantenerse después del despliegue como parte de las actividades de gestión de usuarios en curso.

Antes de empezar

Antes de configurar la federación LDAP, asegúrate de que se cumplen los siguientes requisitos:

El clúster de OpenShift Container Platform (OCP) tiene conectividad de red al servidor LDAP en el puerto adecuado:

389 para ldap://
636 para ldaps://

Hay disponible una cuenta de servicio (bind DN) con acceso de lectura al directorio, o el servidor LDAP está configurado para permitir binds anónimos.

Si usas ldaps:// con una autoridad de certificación (CA) privada o firmada internamente, obtén el certificado CA del servidor LDAP en formato PEM.

La utilidad de línea de comandos bobctl está instalada y oc está configurado y autenticado contra el clúster de destino.

Referencia del archivo de configuración

Crea un archivo de configuración LDAP a partir de la plantilla proporcionada antes de registrar un proveedor LDAP.

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

El archivo de configuración contiene parámetros obligatorios y opcionales que definen cómo Bob se conecta, se autentica y sincroniza usuarios desde tu directorio LDAP.

Campos obligatorios

Campo	Descripción
`name`	Un identificador único y descriptivo para el proveedor LDAP. Cada proveedor configurado debe tener un nombre distinto.
`vendor`	Especifica el tipo de directorio LDAP con el que integrarse. Valores admitidos: `other` (OpenLDAP y compatibles con LDAPv3), `ad` (Microsoft Active Directory), `rhds` (Red Hat Directory Server), `tivoli` (IBM Security Directory Server), `edirectory` (NetIQ eDirectory).
`connectionUrl`	La URL completa del servidor LDAP, incluyendo el protocolo (`ldap://` o `ldaps://`), el hostname y el número de puerto.
`usersDn`	La ubicación en el directorio donde se almacenan las cuentas de usuario y desde la cual se buscan e importan las entradas de usuario.
`usernameLDAPAttribute`	El atributo del directorio que los usuarios proporcionan como nombre de usuario al autenticarse.
`rdnLDAPAttribute`	El atributo del directorio utilizado para identificar entradas dentro de la estructura del directorio. En la mayoría de las configuraciones, es el mismo que `usernameLDAPAttribute`.
`uuidLDAPAttribute`	Un atributo de directorio único, estable e inmutable usado para identificar permanentemente cada cuenta de usuario.
`userObjectClasses`	Una lista separada por comas de clases de objeto LDAP que definen qué entradas del directorio se reconocen y procesan como cuentas de usuario.
`domains`	Uno o más dominios de correo electrónico asociados al directorio. Durante la autenticación, los usuarios cuyos correos electrónicos coinciden con alguno de los dominios configurados son enrutados automáticamente a este proveedor LDAP para la validación de credenciales.

Importante:

El parámetro domains es el único método admitido para configurar el enrutamiento basado en dominio en despliegues on-premises. No configures dominios a través de la interfaz de administración de Bob porque no está soportado y puede causar errores de autenticación.

Campos opcionales

Campo	Descripción
`adminEmails`	Direcciones de correo electrónico de usuarios a los que conceder privilegios administrativos. Bob asigna automáticamente acceso de administrador a estos usuarios.
`bindDn`	El DN de la cuenta de servicio utilizada para autenticarse y conectarse al directorio. Puede omitirse si el directorio permite el acceso con bind anónimo.
`bindPasswordSecret`	Hace referencia al Secret que almacena la contraseña de la cuenta de bind. Este Secret se crea automáticamente cuando se proporciona la opción `--bind-password` con el comando `bobctl`.
`useTruststoreSpi`	Especifica cuándo se usa el certificado CA de LDAP para la validación del servidor. Valores: `always` (predeterminado, para certificados CA privados o emitidos internamente), `ldapsOnly` (para certificados CA de confianza pública), `never` (cuando se conecta por `ldap://` sin cifrar).
`ldapsCACertSecret`	Hace referencia al Secret que contiene el certificado CA del servidor LDAP en formato PEM. Este Secret se crea automáticamente cuando se proporciona `--ca-cert-file`.
`searchScope`	Determina la profundidad de las búsquedas en el directorio. `2` busca en todos los contenedores y subárboles hijo (predeterminado); `1` restringe las búsquedas solo a las entradas hijo directas.
`customUserSearchFilter`	Un filtro adicional aplicado a todas las operaciones de búsqueda de usuarios, por ejemplo para excluir cuentas de servicio o restringir las búsquedas a tipos de usuario específicos.
`userSync.enabled`	Cuando se establece en `true`, todos los usuarios se importan cuando el proveedor se configura inicialmente, y los cambios posteriores en el directorio se sincronizan cada cinco minutos. Recomendado para la mayoría de los despliegues.
`userAttributeMappings`	Define cómo se mapean los atributos del directorio a los campos del perfil de usuario de Bob, como `email`, `firstName` y `lastName`.
`priority`	Determina el orden en que se evalúan los proveedores cuando hay múltiples proveedores configurados. Los proveedores con valores más bajos se comprueban primero. El valor predeterminado es `0`.
`groupMapper`	Sincroniza grupos LDAP en Keycloak. Consulta Configurar la sincronización de grupos LDAP.

Comportamiento de la sincronización de usuarios

Cuando userSync.enabled se establece en true, Bob realiza una importación puntual de todos los usuarios cuando se registra el proveedor LDAP. Una vez completada la importación inicial, la sincronización del ciclo de vida de los usuarios se gestiona automáticamente a través de SCIM.

Consejo:

Para directorios LDAP grandes, considera dejar userSync.enabled establecido en false y permitir que los usuarios se aprovisionen cuando inicien sesión por primera vez. Este enfoque puede reducir el tiempo necesario para registrar el proveedor LDAP.

Configurar la sincronización de grupos LDAP

Usa la configuración opcional groupMapper para sincronizar grupos LDAP con Keycloak. La sincronización de grupos permite que los usuarios y las membresías de grupos definidas en tu directorio LDAP se importen y gestionen a través de Keycloak.

El parámetro groupsDn es obligatorio. Todos los demás parámetros son opcionales y pueden personalizarse para adaptarse al esquema del directorio LDAP y a la estructura de grupos.

Restricción:

Los grupos bob-admins y bob-users son grupos gestionados por la plataforma y se excluyen automáticamente de la sincronización de grupos LDAP.

Parámetro	Valor predeterminado	Descripción
`groupsDn`	Obligatorio	Nombre distinguido (DN) base que contiene las entradas de grupo LDAP.
`name`	`groups`	Nombre de visualización del mapper de grupos en Keycloak.
`groupNameLdapAttribute`	`cn`	Atributo LDAP que Keycloak usa como nombre de grupo.
`groupObjectClasses`	`groupOfNames`	Clase u clases de objeto LDAP que identifican las entradas de grupo.
`membershipLdapAttribute`	`member`	Atributo en la entrada del grupo que contiene información sobre los miembros.
`membershipAttributeType`	`DN`	Formato de los valores de miembro. Valores admitidos: `DN` (nombres distinguidos) y `UID` (IDs de usuario).
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Método utilizado para determinar las membresías de grupo.
`memberOfLdapAttribute`	`memberOf`	Atributo de usuario que contiene información de membresía de grupo cuando se usa `GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`.
`customGroupSearchFilter`	Ninguno	Filtro LDAP adicional utilizado al buscar grupos. El filtro debe estar entre paréntesis, por ejemplo `(cn=dept-*)`.
`mode`	`LDAP_ONLY`	Modo de sincronización. Valores admitidos: `LDAP_ONLY` y `READ_ONLY`.
`groupsPath`	`/`	Ubicación en la jerarquía de grupos de Keycloak donde se crean los grupos sincronizados.

Estrategias de recuperación de membresía de grupos

El parámetro userRolesRetrieveStrategy controla cómo Keycloak identifica las membresías de grupos de un usuario.

Estrategia	Descripción
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Recupera las membresías de grupo buscando entradas de grupo que contengan referencias a usuarios.
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	Recupera las membresías de grupo desde el atributo `memberOf` del usuario.
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	Recupera las membresías de grupo de forma recursiva, incluyendo grupos anidados donde el directorio LDAP lo soporte.

Consejo:

Usa LOAD_GROUPS_BY_MEMBER_ATTRIBUTE a menos que tu directorio LDAP almacene información de membresía de grupo en entradas de usuario a través del atributo memberOf o use estructuras de grupos anidados que requieran búsquedas recursivas.

Ejemplo de configuración

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

Validar una configuración LDAP antes de aplicarla

Antes de aplicar una configuración LDAP al clúster, usa la opción --dry-run para validar la configuración y previsualizar los recursos que se crearían. Ejecutar una simulación puede ayudar a identificar problemas de configuración comunes antes de realizar cambios en el clúster.

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

La simulación realiza las siguientes comprobaciones:

Valida que todos los parámetros de configuración obligatorios estén presentes en el archivo de configuración.

Verifica que el archivo de certificado CA especificado esté disponible localmente cuando se usa --ca-cert-file.

Muestra una vista previa del recurso personalizado BobLDAP que se crearía o actualizaría.

Muestra los Secrets de Kubernetes que se generarían como parte de la configuración.

Sale sin crear, modificar ni eliminar ningún recurso en el clúster.

Nota:

La operación de simulación no valida la conectividad de red al servidor LDAP, no autentica las credenciales proporcionadas contra el directorio, ni confirma la existencia de Secrets referenciados en el clúster. Estas validaciones se realizan solo después de que se ha aplicado la configuración y se reflejan en las condiciones de estado LDAPReachable y LDAPAuthenticated.

Aplicar la configuración

Una vez creado y validado el archivo de configuración LDAP, ejecuta el comando add-ldap para aplicar la configuración al clúster.

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

Flag	Requerido	Descripción
`--config <file>`	Sí	Especifica la ruta al archivo de configuración LDAP.
`--bind-password <password>`	No	Crea el `bindPasswordSecret` en el clúster. No es necesario cuando el directorio permite el acceso con bind anónimo.
`--ca-cert-file <path>`	No	Crea el `ldapsCACertSecret` desde un archivo PEM local. Puede omitirse cuando se usa una CA de confianza pública o una conexión `ldap://` sin cifrar.
`--dry-run`	No	Valida la configuración y muestra una vista previa de los recursos que se crearían o actualizarían, sin aplicar cambios al clúster.

Cuando se ejecuta el comando, bobctl espera a que el operador reconcilie la configuración y valida el proveedor LDAP comprobando las condiciones de estado reportadas por el recurso personalizado BobLDAP.

Comprobación	Qué confirma
`Ready`	El proveedor se ha creado y registrado correctamente.
`LDAPReachable`	El servidor LDAP es accesible desde el clúster.
`LDAPAuthenticated`	Las credenciales de bind configuradas son válidas.
`UserSyncSucceeded`	La importación inicial de usuarios se completó correctamente. Esta condición solo se evalúa cuando `userSync.enabled` está establecido en `true`.

El tiempo de espera de validación predeterminado es de 600 segundos (10 minutos). En entornos con directorios grandes, la sincronización inicial de usuarios puede tardar varios minutos en completarse. Para aumentar el tiempo de espera, establece la variable de entorno BOB_LDAP_WAIT_TIMEOUT:

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

Configurar múltiples proveedores LDAP

Para integrar usuarios de múltiples fuentes LDAP o Active Directory, crea un archivo de configuración separado para cada directorio y asigna un valor único al campo name en cada configuración.

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

Inspeccionar el estado de los recursos LDAP

Para ver el estado de los proveedores LDAP configurados:

oc get bobldap -n <instance-namespace>

Para ver información detallada de configuración y estado de un proveedor específico:

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

Verificar la integración

Después de que bobctl add-ldap se complete correctamente, verifica que la integración LDAP funciona correctamente.

Comprueba el estado del recurso personalizado BobLDAP:

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

Verifica que las siguientes condiciones de estado estén establecidas en True:

Condición	Propósito
`Ready`	Confirma que el proveedor LDAP se registró correctamente.
`LDAPReachable`	Confirma que el clúster puede comunicarse con el servidor LDAP.
`LDAPAuthenticated`	Confirma que las credenciales de bind configuradas son válidas.
`UserSyncSucceeded`	Confirma que todos los usuarios se importaron correctamente. Solo está presente cuando `userSync.enabled: true`.

Si alguna condición es False, revisa el campo message correspondiente para obtener detalles de diagnóstico.

Inicia sesión usando credenciales del directorio LDAP federado para verificar que la autenticación de usuarios funciona.

Abre la URL de Bob:

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

Un inicio de sesión exitoso confirma que la conectividad, la autenticación, el enrutamiento de dominio, el aprovisionamiento SCIM y el mapeo de roles funcionan correctamente.

Después de que el usuario inicie sesión por primera vez, confirma que el registro de usuario está disponible en Bob.

Abre la UI de administración de Bob:

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

Inicia sesión como administrador de Bob y verifica que el usuario de prueba aparece en la lista de usuarios.

Si groupMapper está configurado para mapear un grupo LDAP a administradores de Bob:

Inicia sesión con una cuenta de usuario que pertenezca al grupo de administradores mapeado.
Confirma que el usuario puede acceder a la UI de administración de Bob.
Verifica que las funciones de nivel de administrador están disponibles.

Si userSync.enabled: true, los usuarios se importan automáticamente después de registrar el proveedor LDAP. El usuario de prueba debería aparecer en Bob sin requerir un inicio de sesión inicial.

Si el usuario no aparece después de varios minutos, revisa los logs de bob-admin en busca de errores de aprovisionamiento:

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

Revisa los errores relacionados con SCIM que se reporten y resuélvelos antes de volver a intentar el proceso de sincronización.

Integración LDAP