Configura la federación LDAP o Active Directory para IBM Bob on-premises usando el recurso personalizado BobIDP y el comando bobctl configure-idp.

Usa bobctl configure-idp para conectar tu entorno de LDAP o Active Directory a Keycloak como un proveedor de federación de usuarios. Puedes completar esta configuración durante la instalación o en cualquier momento posterior al despliegue.

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 de IDP a partir de la plantilla proporcionada antes de registrar un proveedor LDAP.

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

El archivo de configuración consta de dos secciones: campos de nivel superior que se aplican a todo el despliegue y una lista opcional ldaps donde cada entrada describe un proveedor de federación LDAP.

Campos de nivel superior

Campo	Obligatorio	Descripción
`domains`	Sí	Lista de dominios de correo electrónico que Bob acepta al iniciar sesión. Al eliminar un dominio, se anula su registro; los usuarios con ese dominio no podrán iniciar sesión.
`adminEmails`	No	Lista de correos electrónicos de usuarios a los que se les otorgará acceso de administrador de Bob. El operador actualiza de forma atómica tanto el grupo `bob-admins` de Keycloak como la base de datos de administración de Bob.
`ldaps`	No	Lista de configuraciones de proveedores de federación LDAP. Omitir por completo para despliegues que utilicen únicamente usuarios directos de Keycloak.

Campos obligatorios (por entrada de proveedor LDAP)

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.

Importante:

El campo domains es la única forma de configurar el enrutamiento basado en dominios en despliegues on-premises. No configures dominios a través de la interfaz de administración de Bob porque no es el método correcto y puede causar errores de autenticación.

Campos opcionales (por entrada de proveedor LDAP)

Campo	Descripción
`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`	Nombre de un Secret preexistente que contiene la contraseña de la cuenta de bind. Debe crearse en el namespace de la instancia antes de ejecutar `bobctl configure-idp`.
`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`	Nombre de un Secret preexistente que contiene el certificado CA del servidor LDAP en formato PEM. Debe crearse en el namespace de la instancia antes de ejecutar `bobctl configure-idp`.
`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. Con la sincronización de grupos, los usuarios y las membresías de grupos de tu directorio LDAP se importan y gestionan 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. No se incluyen en 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

# Dominios de correo electrónico que Bob debe aceptar al iniciar sesión
domains:
  - corp.example.com

# Usuarios a los que se les concederá acceso de administrador de Bob
adminEmails:
  - alice@corp.example.com

# Proveedores de federación 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

    # 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

Validar una configuración de IDP antes de aplicarla

Antes de aplicar una configuración de IDP 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 configure-idp --config my-idp.yaml --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.

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

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 de IDP, ejecuta el comando configure-idp para aplicar la configuración al clúster.

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

Flag	Requerido	Descripción
`--config <file>`	Sí	Especifica la ruta al archivo de configuración de IDP.
`--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 IDP comprobando las condiciones de estado reportadas por el recurso personalizado BobIDP.

Comprobación	Qué confirma
`Ready`	La configuración se ha aplicado correctamente.
`LDAPRegistered`	El proveedor LDAP se ha registrado en Keycloak.
`LDAPReachable`	El servidor LDAP es accesible desde el clúster.
`LDAPAuthenticated`	Las credenciales de bind configuradas son válidas.
`LDAPUserSyncSucceeded`	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_IDP_WAIT_TIMEOUT:

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

Configurar múltiples proveedores LDAP

Para integrar usuarios de múltiples fuentes LDAP o Active Directory, añade cada directorio como una entrada separada en la lista ldaps del archivo de configuración de IDP y vuelve a ejecutar configure-idp.

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

Inspeccionar el estado del recurso IDP

Para ver el estado de la configuración de IDP:

oc get bobidp -n <instance-namespace>

Para ver información detallada de configuración y estado:

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

Verificar la integración

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

Comprueba el estado del recurso personalizado BobIDP:

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

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

Condición	Propósito
`Ready`	Confirma que la configuración se aplicó correctamente.
`LDAPRegistered`	Confirma que el proveedor LDAP se registró en Keycloak.
`LDAPReachable`	Confirma que el clúster puede comunicarse con el servidor LDAP.
`LDAPAuthenticated`	Confirma que las credenciales de bind configuradas son válidas.
`LDAPUserSyncSucceeded`	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