Configure LDAP or Active Directory federation for IBM Bob self-hosted using the BobIDP custom resource and the bobctl configure-idp command.

Use bobctl configure-idp to connect your LDAP or Active Directory environment to Keycloak as a user federation provider. You can complete this setup during installation or at any point after deployment.

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 IDP configuration file from the provided template before registering an LDAP provider.

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

The configuration file has two sections: top-level fields that apply to the whole deployment, and an optional ldaps list where each entry describes one LDAP federation provider.

Top-level fields

Field	Required	Description
`domains`	Yes	List of email domains Bob accepts at login. Removing a domain de-registers it; users with that domain will be unable to log in.
`adminEmails`	No	List of user emails to be granted Bob admin access. The operator updates both the Keycloak `bob-admins` group and the Bob admin database atomically.
`ldaps`	No	List of LDAP federation provider configurations. Omit entirely for deployments that use direct Keycloak users only.

Required fields (per LDAP provider entry)

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.

Important:

The domains field is the only way to configure domain-based routing in on-premises deployments. Do not configure domains through the Bob administration user interface because doing so is not the correct method and can cause authentication errors.

Optional fields (per LDAP provider entry)

Field	Description
`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`	Name of a pre-existing Secret containing the bind account password. Must be created in the instance namespace before running `bobctl configure-idp`.
`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`	Name of a pre-existing Secret containing the LDAP server's CA certificate in PEM format. Must be created in the instance namespace before running `bobctl configure-idp`.
`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. With group synchronization, users and group memberships from your LDAP directory are 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. They are not included in LDAP group synchronization.

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

# 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

Validating an IDP configuration before applying it

Before you apply an IDP 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 configure-idp --config my-idp.yaml --dry-run

The dry run performs the following checks:

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

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

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 IDP configuration file, run the configure-idp command to apply the configuration to the cluster.

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

Flag	Required	Description
`--config <file>`	Yes	Specifies the path to the IDP configuration file.
`--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 IDP by checking the status conditions reported by the BobIDP custom resource.

Check	What it confirms
`Ready`	The configuration has been successfully applied.
`LDAPRegistered`	The LDAP provider has been registered in Keycloak.
`LDAPReachable`	The LDAP server is accessible from the cluster.
`LDAPAuthenticated`	The configured bind credentials are valid.
`LDAPUserSyncSucceeded`	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_IDP_WAIT_TIMEOUT environment variable:

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

Configuring multiple LDAP providers

To integrate users from multiple LDAP or Active Directory sources, add each directory as a separate entry in the ldaps list of the IDP configuration file and re-run configure-idp.

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

Inspecting IDP resource status

To view the status of the IDP configuration:

oc get bobidp -n <instance-namespace>

To view detailed configuration and status information:

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

Verifying the integration

After bobctl configure-idp completes successfully, verify that the LDAP integration is functioning correctly.

Check the status of the BobIDP custom resource:

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

Verify that the following status conditions are set to True:

Condition	Purpose
`Ready`	Confirms that the configuration was applied successfully.
`LDAPRegistered`	Confirms that the LDAP provider was registered in Keycloak.
`LDAPReachable`	Confirms that the cluster can communicate with the LDAP server.
`LDAPAuthenticated`	Confirms that the configured bind credentials are valid.
`LDAPUserSyncSucceeded`	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