Skip to main content
Version: 2.10

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>/auth/admin/

    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 npw 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. Configure Role Mappings: Map LDAP groups to Portworx Backup roles
  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