Configure LDAP or Active Directory federation for IBM Bob on-premises using the BobLDAP custom resource and the bobctl add-ldap command.

Bob on-premises integrates your LDAP or Active Directory environment with Keycloak through the bobctl utility, which configures the directory as a Keycloak user federation provider. Although this integration is typically set up during installation, it can also be configured, updated, or maintained after deployment as part of ongoing user management activities.

Before you begin

Before configuring LDAP federation, ensure that the following requirements are met:

The OpenShift Container Platform (OCP) cluster has network connectivity to the LDAP server on the appropriate port:

389 for ldap://
636 for ldaps://

A service account (bind DN) with read access to the directory is available, or the LDAP server is configured to allow anonymous binds.

If you are using ldaps:// with a private or internally signed certificate authority (CA), obtain the LDAP server's CA certificate in PEM format.

The bobctl command-line utility is installed, and oc is configured and authenticated against the target cluster.

Configuration file reference

Create an LDAP configuration file from the provided template before registering an LDAP provider.

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

The configuration file contains required and optional parameters that define how Bob connects to, authenticates with, and synchronizes users from your LDAP directory.

Required fields

Field	Description
`name`	A unique, descriptive identifier for the LDAP provider. Each configured provider must have a distinct name.
`vendor`	Specifies the type of LDAP directory to integrate with. Supported values: `other` (OpenLDAP and LDAPv3-compliant), `ad` (Microsoft Active Directory), `rhds` (Red Hat Directory Server), `tivoli` (IBM Security Directory Server), `edirectory` (NetIQ eDirectory).
`connectionUrl`	The complete URL of the LDAP server, including the protocol (`ldap://` or `ldaps://`), hostname, and port number.
`usersDn`	The directory location where user accounts are stored and from which user entries are searched and imported.
`usernameLDAPAttribute`	The directory attribute that users provide as their username when authenticating.
`rdnLDAPAttribute`	The directory attribute used to identify entries within the directory structure. In most configurations, this is the same as `usernameLDAPAttribute`.
`uuidLDAPAttribute`	A unique, stable, non-changing directory attribute used to permanently identify each user account.
`userObjectClasses`	A comma-separated list of LDAP object classes that define which directory entries are recognized and processed as user accounts.
`domains`	One or more email domains associated with the directory. During authentication, users whose email addresses match any of the configured domains are automatically routed to this LDAP provider for credential validation.

Important:

The domains parameter is the only supported method for configuring domain-based routing in on-premises deployments. Do not configure domains through the Bob administration user interface because doing so is not supported and can cause authentication errors.

Optional fields

Field	Description
`adminEmails`	Email addresses of users to grant administrative privileges. Bob automatically assigns admin access to these users.
`bindDn`	The DN of the service account used to authenticate and connect to the directory. Can be omitted if the directory allows anonymous bind access.
`bindPasswordSecret`	References the Secret that stores the bind account password. This Secret is automatically created when the `--bind-password` option is provided with the `bobctl` command.
`useTruststoreSpi`	Specifies when the LDAP CA certificate is used for server validation. Values: `always` (default, for private or internally issued CA certificates), `ldapsOnly` (for publicly trusted CA certificates), `never` (when connecting over unsecured `ldap://`).
`ldapsCACertSecret`	References the Secret that contains the LDAP server's CA certificate in PEM format. This Secret is automatically created when `--ca-cert-file` is provided.
`searchScope`	Determines the depth of directory searches. `2` searches all child containers and subtrees (default); `1` restricts searches to direct child entries only.
`customUserSearchFilter`	An additional filter applied to all user search operations, for example to exclude service accounts or restrict searches to specific user types.
`userSync.enabled`	When set to `true`, all users are imported when the provider is initially configured, and subsequent directory changes are synchronized every five minutes. Recommended for most deployments.
`userAttributeMappings`	Defines how directory attributes are mapped to Bob user profile fields, such as `email`, `firstName`, and `lastName`.
`priority`	Determines the order in which providers are evaluated when multiple providers are configured. Providers with lower values are checked first. Default is `0`.
`groupMapper`	Synchronizes LDAP groups into Keycloak. See Configuring LDAP group synchronization.

User synchronization behavior

When userSync.enabled is set to true, Bob performs a one-time import of all users when the LDAP provider is registered. After the initial import completes, ongoing user lifecycle synchronization is handled automatically through SCIM.

Tip:

For large LDAP directories, consider leaving userSync.enabled set to false and allowing users to be provisioned when they first sign in. This approach can reduce the time required to register the LDAP provider.

Configuring LDAP group synchronization

Use the optional groupMapper configuration to synchronize LDAP groups with Keycloak. Group synchronization enables users and group memberships defined in your LDAP directory to be imported and managed through Keycloak.

The groupsDn parameter is required. All other parameters are optional and can be customized to match your LDAP directory schema and group structure.

Restriction:

The bob-admins and bob-users groups are platform-managed groups and are excluded from LDAP group synchronization automatically.

Parameter	Default value	Description
`groupsDn`	Required	Base distinguished name (DN) that contains LDAP group entries.
`name`	`groups`	Display name of the group mapper in Keycloak.
`groupNameLdapAttribute`	`cn`	LDAP attribute that Keycloak uses as the group name.
`groupObjectClasses`	`groupOfNames`	LDAP object class or classes that identify group entries.
`membershipLdapAttribute`	`member`	Attribute in the group entry that contains member information.
`membershipAttributeType`	`DN`	Format of member values. Supported values: `DN` (distinguished names) and `UID` (user IDs).
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Method used to determine group memberships.
`memberOfLdapAttribute`	`memberOf`	User attribute containing group membership information when `GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE` is used.
`customGroupSearchFilter`	None	Additional LDAP filter used when searching for groups. The filter must be enclosed in parentheses, for example `(cn=dept-*)`.
`mode`	`LDAP_ONLY`	Synchronization mode. Supported values: `LDAP_ONLY` and `READ_ONLY`.
`groupsPath`	`/`	Location in the Keycloak group hierarchy where synchronized groups are created.

Group membership retrieval strategies

The userRolesRetrieveStrategy parameter controls how Keycloak identifies a user's group memberships.

Strategy	Description
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Retrieves group memberships by searching group entries that contain references to users.
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	Retrieves group memberships from the user's `memberOf` attribute.
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	Retrieves group memberships recursively, including nested groups where supported by the LDAP directory.

Tip:

Use LOAD_GROUPS_BY_MEMBER_ATTRIBUTE unless your LDAP directory stores group membership information in user entries through the memberOf attribute or uses nested group structures that require recursive searches.

Example configuration

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

Validating an LDAP configuration before applying it

Before you apply an LDAP configuration to the cluster, use the --dry-run option to validate the configuration and preview the resources that would be created. Running a dry run can help identify common configuration issues before any changes are made to the cluster.

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

The dry run performs the following checks:

Validates that all required configuration parameters are present in the configuration file.

Verifies that the specified CA certificate file is available locally when --ca-cert-file is used.

Displays a preview of the BobLDAP custom resource that would be created or updated.

Shows the Kubernetes Secrets that would be generated as part of the configuration.

Exits without creating, modifying, or deleting any resources in the cluster.

Note:

The dry-run operation does not validate network connectivity to the LDAP server, authenticate the supplied credentials against the directory, or confirm the existence of referenced Secrets in the cluster. These validations are performed only after the configuration has been applied and are reflected in the LDAPReachable and LDAPAuthenticated status conditions.

Applying the configuration

After you create and validate your LDAP configuration file, run the add-ldap command to apply the configuration to the cluster.

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

Flag	Required	Description
`--config <file>`	Yes	Specifies the path to the LDAP configuration file.
`--bind-password <password>`	No	Creates the `bindPasswordSecret` in the cluster. Not required when the directory allows anonymous bind access.
`--ca-cert-file <path>`	No	Creates the `ldapsCACertSecret` from a local PEM file. Can be omitted when using a publicly trusted CA or an unsecured `ldap://` connection.
`--dry-run`	No	Validates the configuration and displays a preview of the resources that would be created or updated, without applying any changes to the cluster.

When the command runs, bobctl waits for the operator to reconcile the configuration and validates the LDAP provider by checking the status conditions reported by the BobLDAP custom resource.

Check	What it confirms
`Ready`	The provider has been successfully created and registered.
`LDAPReachable`	The LDAP server is accessible from the cluster.
`LDAPAuthenticated`	The configured bind credentials are valid.
`UserSyncSucceeded`	The initial user import completed successfully. This condition is evaluated only when `userSync.enabled` is set to `true`.

The default validation timeout is 600 seconds (10 minutes). In environments with large directories, the initial user synchronization can take several minutes to complete. To increase the timeout, set the BOB_LDAP_WAIT_TIMEOUT environment variable:

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

Configuring multiple LDAP providers

To integrate users from multiple LDAP or Active Directory sources, create a separate configuration file for each directory and assign a unique value to the name field in each configuration.

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

Inspecting LDAP resource status

To view the status of configured LDAP providers:

oc get bobldap -n <instance-namespace>

To view detailed configuration and status information for a specific provider:

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

Verifying the integration

After bobctl add-ldap completes successfully, verify that the LDAP integration is functioning correctly.

Check the status of the BobLDAP custom resource:

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

Verify that the following status conditions are set to True:

Condition	Purpose
`Ready`	Confirms that the LDAP provider was registered successfully.
`LDAPReachable`	Confirms that the cluster can communicate with the LDAP server.
`LDAPAuthenticated`	Confirms that the configured bind credentials are valid.
`UserSyncSucceeded`	Confirms that all users were imported successfully. Present only when `userSync.enabled: true`.

If any condition is False, review the corresponding message field for diagnostic details.

Open the Bob URL:

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

A successful sign-in confirms that connectivity, authentication, domain routing, SCIM provisioning, and role mapping are functioning correctly.

After the user signs in for the first time, confirm that the user record is available in Bob.

Open the Bob administration UI:

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

If groupMapper is configured to map an LDAP group to Bob administrators:

Sign in with a user account that belongs to the mapped administrator group.
Confirm that the user can access the Bob administration UI.
Verify that administrator-level functions are available.

If userSync.enabled: true, users are imported automatically after the LDAP provider is registered. The test user should appear in Bob without requiring an initial sign-in.

If the user does not appear after several minutes, review the bob-admin logs for provisioning errors:

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

Review any reported SCIM-related errors and resolve them before retrying the synchronization process.

LDAP integration

On this page