Skip to main content
Version: 2.11

Integrate OpenLDAP with Keycloak

This guide explains how to integrate OpenLDAP with Portworx Backup Keycloak for centralized user authentication and authorization. This integration allows you to use your existing LDAP directory for user management in Portworx Backup.

Prerequisites​

Before you begin, ensure you have:

  • OpenLDAP server installed and configured

    • Server accessible from the Portworx Backup cluster
    • Administrative access to the LDAP server
    • LDAP service running on standard ports (389 for LDAP, 636 for LDAPS)

  • LDAP directory structure with:

    • Users organized in a specific organizational unit (OU)
    • Groups organized in a specific organizational unit (OU)
    • Proper LDAP schema for user and group objects

  • Portworx Backup installed and running with:

    • Access to Keycloak admin console
    • Administrative privileges in Keycloak

  • Network connectivity between Keycloak and LDAP server with:

    • Firewall rules allowing LDAP traffic
    • DNS resolution for LDAP server hostname (if using FQDN)

LDAP Directory Structure Example​

For this integration, your LDAP directory should follow a structure similar to:

dc=example,dc=com
├── ou=users,dc=example,dc=com
│   ├── uid=john,ou=users,dc=example,dc=com
│   ├── uid=jane,ou=users,dc=example,dc=com
│   └── uid=admin,ou=users,dc=example,dc=com
└── ou=groups,dc=example,dc=com
    ├── cn=pxb-admins,ou=groups,dc=example,dc=com
    ├── cn=pxb-users,ou=groups,dc=example,dc=com
    └── cn=pxb-operators,ou=groups,dc=example,dc=com

Configure LDAP User Federation​

  1. Navigate to the Keycloak admin console:

    http://<NODE_IP>:<NODE_PORT>/admin/
    note

    If your Portworx Backup installation uses Keycloak 16 or earlier, the URL format is http://<NODE_IP>:<NODE_PORT>/auth/admin/ instead.

    For detailed instructions on accessing the Keycloak console, refer to Configure access to web console.

  2. Log in with administrator credentials

  3. In the left navigation pane, click User Federation.

  4. Click Add provider and select ldap:

  5. In the Add user federation provider page, configure the following:

    General Options​

    • Console Display Name: OpenLDAP
    • Vendor: Select Other from the dropdown
    • Priority: 0 (default priority)

    Connection Settings​

    • Connection URL: ldap://<LDAP_SERVER_IP>:389
      • For secure connections: ldaps://<LDAP_SERVER_IP>:636
      • Example: ldap://192.168.1.100:389
    • Enable StartTLS: OFF (unless using StartTLS)
    • Use Truststore SPI: Only for ldaps (for LDAPS connections)
    • Connection Pooling: ON (recommended for performance)
    • Connection Timeout: 5000 (milliseconds)

  6. Click Test connection to verify the connection settings

    Authentication Settings​

    • Bind Type: simple
    • Bind DN: cn=admin,dc=example,dc=com
      • Replace with your LDAP admin user DN
    • Bind Credential: Enter the password for the bind DN user

  7. Click Test authentication to verify the bind credentials

  8. Configure the following search and update settings:



    LDAP Searching and Updating​

    • Edit Mode: READ_ONLY (recommended for production)

    • Users DN: ou=users,dc=example,dc=com

      • The DN where user entries are located

    • Username LDAP Attribute: uid

      • Attribute used for username (common: uid, cn, sAMAccountName)

    • RDN LDAP Attribute: uid

      • Relative Distinguished Name attribute

    • UUID LDAP Attribute: entryUUID

      • For OpenLDAP, use entryUUID; for Active Directory, use objectGUID

    • User Object Classes: inetOrgPerson,organizationalPerson,person

      • Object classes for user entries

    • User LDAP Filter: (objectClass=inetOrgPerson)

      • Optional filter to limit user search

    • Search Scope: One Level

      • Search only direct children of Users DN

    • Read Timeout: 10000 (milliseconds)

    • Pagination: ON (recommended for large directories)


    Synchronization Settings​

    • Import Users: ON
      • Import existing LDAP users into Keycloak
    • Sync Registrations: OFF
      • Disable if you don't want new Keycloak users created in LDAP
    • Batch Size: 1000
      • Number of users to sync in each batch
    • Periodic Full Sync: ON (optional)
      • Full Sync Period: 604800 (7 days in seconds)
    • Periodic Changed Users Sync: ON (optional)
      • Changed Users Sync Period: 86400 (24 hours in seconds)

    Kerberos Integration​

    • Allow Kerberos Authentication: OFF
    • Use Kerberos for Password Authentication: OFF

    Cache Settings​

    • Cache Policy: DEFAULT
    • Eviction Day: Leave empty
    • Eviction Hour: Leave empty
    • Eviction Minute: Leave empty
    • Max Lifespan: 3600000 (1 hour in milliseconds)

    Advanced Settings​

    • Enable the LDAPv3 Password Modify Extended Operation: OFF
    • Validate Password Policy: OFF
    • Trust Email: ON
      • Enable if LDAP email addresses are trusted

  9. Click Test connection to verify connectivity.

  10. Click Test authentication to verify bind credentials.

  11. Click Save to create the LDAP provider.

Your OpenLDAP server is now integrated with Keycloak. Users can now login to Portworx Backup web console using their OpenLDAP credentials.

Configure Group Mappers​

After creating the LDAP provider, configure mappers to synchronize groups and user attributes.

  1. Navigate to User Federation in the left navigation pane.

  2. Select your OpenLDAP provider.

  3. Click the Mappers tab.

  4. Click Add Mapper to add a new mapper.

  5. Configure the following settings:

    Basic Settings​

    • Name: ldap-group-mapper
    • Mapper Type: group-ldap-mapper

    Group Settings​

    • LDAP Groups DN: ou=groups,dc=example,dc=com
      • The DN where group entries are located
    • Group Name LDAP Attribute: cn
      • Attribute used for group name
    • Group Object Classes: groupOfNames,top
      • Object classes for group entries
    • Preserve Group Inheritance: OFF
      • Set to ON if you have nested groups
    • Ignore Missing Groups: OFF
    • Membership LDAP Attribute: member
      • Attribute that contains group members
    • Membership Attribute Type: DN
      • How members are referenced (DN or UID)
    • Membership User LDAP Attribute: uid
      • User attribute for membership mapping
    • LDAP Filter: (objectClass=groupOfNames)
      • Optional filter for group search
    • Mode: READ_ONLY
    • User Groups Retrieve Strategy: LOAD_GROUPS_BY_MEMBER_ATTRIBUTE

  6. Click Save to create the group mapper.

  7. In the Mappers tab, under Actions select the required sync option to sync the users and groups.

  8. Verify that groups are imported successfully.

  9. You can create additional mappers for user attributes:

    Email Mapper​

    • Name: email
    • Mapper Type: user-attribute-ldap-mapper
    • User Model Attribute: email
    • LDAP Attribute: mail
    • Read Only: ON

    First Name Mapper​

    • Name: first name
    • Mapper Type: user-attribute-ldap-mapper
    • User Model Attribute: firstName
    • LDAP Attribute: givenName
    • Read Only: ON

    Last Name Mapper​

    • Name: last name
    • Mapper Type: user-attribute-ldap-mapper
    • User Model Attribute: lastName
    • LDAP Attribute: sn
    • Read Only: ON

Troubleshooting​

Connection Problems​

  • Verify LDAP server is accessible from Keycloak
  • Check firewall rules and network connectivity
  • Ensure correct LDAP server URL and port

Authentication Failures​

  • Verify bind DN and credentials are correct
  • Check LDAP server logs for authentication errors
  • Ensure bind user has sufficient privileges

User/Group Sync Issues​

  • Verify Users DN and Groups DN are correct
  • Check LDAP filters and object classes
  • Review LDAP directory structure and permissions

Performance Issues​

  • Enable connection pooling
  • Adjust batch size for synchronization
  • Consider using pagination for large directories

Log Analysis​

Check Keycloak server logs for detailed error messages.

Next Steps​

After successfully integrating OpenLDAP with Keycloak:

  1. Map LDAP Groups to Portworx Backup Roles (Required): Importing LDAP groups into Keycloak alone does not grant users any access in Portworx Backup. You must explicitly map each LDAP group to a Portworx Backup role. To do this:

    1. Log in to the Portworx Backup web console as an administrator.
    2. Navigate to Settings > Users and Groups > Groups.
    3. Select the LDAP group and assign it a Portworx Backup role (for example, px-backup-app.admin or px-backup-app.user).

    Until role mappings are configured, authenticated users will have no authorization and cannot access any resources.

  2. Set Up Rancher Integration: If using Rancher, configure RBAC integration

  3. Test User Access: Verify users can access Portworx Backup with appropriate permissions

  4. Monitor Synchronization: Set up periodic sync to keep users and groups updated

Last updated on