User management
Manage user access for IBM Bob on-premises using Keycloak as the identity provider, with LDAP or Active Directory federation or locally managed accounts.
IBM Bob on-premises includes a Keycloak identity provider for user authentication and access management. Users can be federated from an existing LDAP or Active Directory environment, or created directly in Keycloak. Regardless of how they are provisioned, users must be assigned an appropriate Bob role before they can access the service.
Overview
| Concept | Description |
|---|---|
| Identity provider | Keycloak — deployed and managed by the Bob operator. |
| User sources | Users can be created directly in Keycloak or federated from an LDAP or Active Directory service. |
| Authentication | Users authenticate through Keycloak using OpenID Connect (OIDC). Keycloak issues a short-lived authorization code that bob-authn exchanges for a Bob bearer token. |
| Authorization | Access to Bob capabilities is governed by roles assigned to users within Keycloak. |
| Configuration surface | LDAP integration is managed through the BobLDAP custom resource using the bobctl configure-idp command. |
Supported LDAP directory types
Bob on-premises supports any LDAPv3-compliant directory service. The vendor parameter in the LDAP configuration determines the Keycloak provider template to use, which defines the protocol-specific settings for the selected directory type.
vendor value | Directory type |
|---|---|
other | OpenLDAP and other generic LDAPv3-compatible directory services |
ad | Microsoft Active Directory |
rhds | Red Hat Directory Server |
tivoli | IBM Security Directory Server (formerly Tivoli Directory Server) |
edirectory | NetIQ / Micro Focus eDirectory |
Authentication and federation architecture
When a user signs in, Bob passes the request to Keycloak, which handles authentication. All users authenticate through Keycloak. LDAP federation is optional and only active when configured.
- LDAP federation enabled: Keycloak authenticates users directly against the LDAP directory. User passwords remain in the LDAP directory and are not stored in Keycloak.
- LDAP federation disabled: Keycloak authenticates users using the local Keycloak user store.
Authentication flow
- The user enters credentials.
- Keycloak authenticates the user.
- Keycloak issues a short-lived authorization code.
bob-authnexchanges the authorization code for a Bob bearer token.- All subsequent API requests use the Bob-issued token.
User synchronization behavior
Bob on-premises supports two synchronization modes, configured through the userSync.enabled setting in the LDAP configuration:
| Mode | userSync.enabled | Behavior |
|---|---|---|
| On-demand | false (default) | Users are imported into Keycloak only when they successfully sign in for the first time, eliminating the requirement for an upfront directory scan. This option is recommended for very large directory environments. |
| Eager sync (recommended) | true | When an LDAP provider is registered, a one-time full synchronization imports all users from the directory. After the initial import, Keycloak automatically synchronizes user updates every five minutes. This approach ensures that all users are immediately available, and administrator accounts specified through adminEmails can be provisioned without requiring users to sign in first. |
On-demand synchronization
Use this mode for very large directories where importing all users immediately is not practical.
During the first authentication attempt:
- The user is imported into Keycloak.
- The user is provisioned in Bob through SCIM.
- The first login attempt fails due to provisioning latency.
- The user can sign in successfully after provisioning completes.
Eager synchronization
Recommended for most deployments. All users become available immediately after synchronization completes and do not need to sign in to be provisioned.
The synchronization interval is currently fixed at 5 minutes.
Synchronizing users with SCIM
IBM Bob on-premises uses a customized SCIM 2.0 plugin embedded in Keycloak to synchronize user accounts between Keycloak and Bob. The Bob operator configures this integration automatically, and no additional configuration is required.
How user synchronization works
When a user lifecycle event occurs in Keycloak, the SCIM plugin sends the corresponding event to the bob-admin service. Bob then updates user access and profile information based on the event.
This synchronization applies to all users managed by Keycloak, including LDAP-federated users and users created directly in the Keycloak administration console.
| User event | Bob action |
|---|---|
| User created or first login | Provisions the user and grants access to Bob |
| User updated | Synchronizes profile changes |
| User removed from LDAP | Revokes access to Bob while retaining user data |
Removing a user from LDAP revokes their access to Bob but does not delete their data. If the user is added back to the directory, access is restored and previously created work remains available.
Verifying synchronization
Bob does not currently provide a status condition or health check that confirms SCIM synchronization is active. To verify that provisioning is working, create or import a test user and confirm that the user appears in Bob after their first sign-in or after the initial userSync import.
Managing roles and group membership
IBM Bob uses Keycloak groups to control user roles. The Bob operator automatically creates and maintains the required groups and role mappings.
| Keycloak group | Keycloak role granted | Who is added |
|---|---|---|
bob-users | bob-user | All authenticated users are automatically added on their first successful sign-in through the realm's default group. |
bob-admins | bob-admin | Users specified in the adminEmails field of the BobLDAP configuration are automatically assigned by the operator during each reconciliation cycle. |
Administrator access
All authenticated users receive standard Bob access.
To grant administrator privileges:
- Add the user's email address to
adminEmailsin the IDP configuration file. - Apply the change:
./bobctl configure-idp --config my-idp.yaml
To revoke administrator privileges:
- Remove the email address from
adminEmails. - Reapply the configuration.
bobctl configure-idp is the only supported method for managing Bob administrator access. Adding an email address to adminEmails does not create a user account — the user must already exist in Keycloak through LDAP federation or direct user creation.
Administering Keycloak
Bob on-premises includes a Keycloak deployment that provides identity and access management services. Keycloak administration is separate from Bob administration, and each interface serves a different purpose.
Administration interfaces
| Interface | URL | Purpose |
|---|---|---|
| Keycloak Admin Console | https://bob-keycloak.<namespace>.<ingress-domain> | Manage Keycloak infrastructure, users, groups, identity providers, and federation settings. |
| Bob Admin UI | https://bob.<namespace>.<ingress-domain>/admin | Manage Bob users, roles, invitations, and tenant-specific settings. |
The Bob operator automatically creates both routes during installation.
Activity logs are not available in the Bob Admin UI for this release. To access service logs, view the pod logs for the Authentication service, Authorisation service, and Admin service directly from the OpenShift Container Platform console or CLI. For more information, see Known limitations.
Accessing the Keycloak Admin Console
To find the Keycloak route in your cluster, run:
oc get route -n <instance-namespace> | grep keycloakRetrieve the initial administrator credentials from the cluster secret:
oc get secret bob-keycloak-initial-admin \
-n <instance-namespace> \
-o jsonpath='{.data.username}' | base64 -d && echooc get secret bob-keycloak-initial-admin \
-n <instance-namespace> \
-o jsonpath='{.data.password}' | base64 -d && echoDo not modify the bob-keycloak-initial-admin secret. The Bob operator uses these credentials during reconciliation. Changing the stored credentials can disrupt operator-managed functionality.
If you require a personal administrator account, sign in with the initial administrator credentials and create a separate user in the master realm for ongoing administrative tasks.
After signing in, switch to the bob realm by using the realm selector in the upper-left corner of the Keycloak console. All Bob users, groups, identity providers, and federation providers are managed from this realm.
Understanding Keycloak realms
A realm is an isolated management domain that contains its own users, credentials, roles, groups, and identity providers.
Bob on-premises uses two realms:
| Realm | Purpose |
|---|---|
| master | Reserved for Keycloak administration. Users in this realm can administer Keycloak but cannot access Bob. |
| bob | Contains all Bob users, groups, LDAP federation providers, and application clients. The Bob operator creates and manages this realm. |
The two realms are completely independent. Membership or privileges in one realm do not grant access to resources in the other.
The bob realm is operator-managed. You can make direct changes through the Keycloak console, but IBM support is limited to resolving issues that affect Bob authentication and access.
Managing LDAP federation providers
LDAP federation providers that are configured through bobctl configure-idp or the BobLDAP custom resource are visible in the User Federation section of the bob realm.
The Bob operator registers LDAP providers when they are created. Subsequent changes made directly in the Keycloak console are not synchronized back to the corresponding BobLDAP custom resource.
For consistent configuration management, use the BobLDAP custom resource and bobctl configure-idp commands whenever possible.
Security considerations
Follow these recommendations when administering Keycloak:
- Restrict access to the
bob-keycloak-initial-adminsecret to cluster administrators. - Perform Bob administration tasks in the
bobrealm. - Use the
masterrealm only for Keycloak infrastructure administration. - Do not create additional realms or clients unless explicitly required and supported.
- Manage LDAP federation through
BobLDAPresources instead of directly editing provider settings in the Keycloak console. - Treat the initial administrator account as an emergency or bootstrap account, and use dedicated personal administrator accounts for routine administration.
Managing direct Keycloak users
Users can be created and managed directly within Keycloak without integrating an LDAP directory. This approach is suitable for proof-of-concept environments, small-scale deployments, or installations where an LDAP server is not available. For production environments that already use a corporate directory service, LDAP federation is the recommended approach.
Adding a user
To create a local user, open the Users section in the bob realm and create a new user account. After saving the user, configure a password and assign the appropriate group memberships:
- Add the user to bob-users to grant standard access.
- Add the user to both bob-users and bob-admins to grant administrative access.
Managing passwords
Passwords for locally managed users are administered through the Keycloak administration console. Open the user record and use the Credentials tab to create, update, or reset the user's password.
Removing a user
To remove access for a user, open the user record in the Keycloak administration console and either delete or disable the account. Disabled users can no longer authenticate, while their user information remains available in the system.
Operations and troubleshooting
Monitor, maintain, and troubleshoot Model Gateway deployments, including model configuration updates, credential rotation, health monitoring, log collection, and resolution of common connectivity and authentication issues.
LDAP integration
Configure LDAP or Active Directory federation for IBM Bob on-premises using the BobLDAP custom resource and the bobctl add-ldap command.