Installing and configuring OpenLDAP

IBM RPA imports the users configured in your OpenLDAP server through the User Management Service (UMS). If you plan to use SSO, you must set up your OpenLDAP server properly before you proceed with the installation of the IBM RPA server.

The following sections provide information about how to install and configure a minimal OpenLDAP distribution, and how to register new users in your OpenLDAP server. If you already have an LDAP server, proceed to install IBM RPA and then configure the server to connect with OpenLDAP. For more information, see Configuring UMS to connect with OpenLDAP.

To learn how to import users into IBM RPA, see Managing LDAP users.

Installing OpenLDAP

Go to the following procedures that apply to your current environment:

Installing OpenLDAP on Windows

OpenLDAP does not provide official installers for Windows™.

You can run OpenLDAP through the Windows™ Subsystem for Linux™ (WSL)🡥, which runs a minimal Linux distribution under Windows, or install a Windows build of OpenLDAP from a third-party provider.

Important: Third-party Windows distributions of OpenLDAP are not recommended because they might include special licenses and limitations. If you want a safe binary on Windows, compile the source code of OpenLDAP. Refer to Building and Installing OpenLDAP Software 🡥 for details.

Follow the instructions in Installing OpenLDAP on Linux to install OpenLDAP in WSL according to your WSL distribution.

Installing OpenLDAP on Linux

Search for ldap in the distribution's package manager. Some of the common packages of OpenLDAP are slapd or openldap in most Linux distributions.

Note: The following commands apply to Ubuntu™ 22.04 LTS and CentOS™ Stream 9.

If you use Red Hat® Enterprise Linux 8 (RHEL 8) or later, the distribution no longer provides OpenLDAP packages. Consider using Red Hat Directory Server for official LDAP support. See Installing Red Hat Directory Server🡥 to install and configure your Red Hat Directory Server.

On Ubuntu 22.04 LTS, run the following command on the terminal:

sudo apt-get install ldap-utils slapd

You get prompted to set up your administrator password. Enter a new password and then confirm the password.

Then reconfigure the default entries:

sudo dpkg-reconfigure slapd
  1. Select if you want to omit the OpenLDAP server configuration. In this example, select No.
  2. Enter your DNS domain name. It might be the Fully Qualified Domain Name to your server, or any domain name that you want the LDAP server to use, even if you don't own the domain itself.
    Important:The DNS domain name becomes your Base Distinguished Name (Base DN). If you enter a domain name such as rpa.ibm.com, it is converted to the dc=rpa,dc=ibm,dc=com distinguished name in the LDAP entries.
  3. Select if you want to remove the database files in case you uninstall the LDAP server. In this example, select Yes.
  4. Select if you want to move existing LDAP files to prevent breaking the server configuration. In this example, select Yes.

On CentOS, you must first enable the EPEL repository to install OpenLDAP:

sudo dnf install epel-release

And then install the OpenLDAP server and client:

sudo dnf -y install openldap openldap-servers openldap-clients
Tip: If you experience problems with these commands in CentOS, try installing them separately:
sudo dnf install --enablerepo=epel openldap-clients


sudo dnf install openldap-servers

Configuring OpenLDAP

The following sections guide you through the process of configuring and registering users in OpenLDAP.

  1. Starting the service
  2. Allowing external connections
  3. Editing default configuration
  4. Configuring the root user
  5. Registering new users

Starting the service

Start the OpenLDAP service:

sudo systemctl start slapd.service

Enable the OpenLDAP service to initialize with the operating system:

sudo systemctl enable slapd.service

Allowing external connections

Add an exception to the firewall to enable external connections to OpenLDAP on Ubuntu:

sudo ufw allow ldap

On CentOS, you need to allow connections to the firewall and allow applications to access OpenLDAP through SELinux:

sudo firewall-cmd --permanent --add-port=389/tcp --add-port=389/udp
sudo firewall-cmd --reload
sudo setsebool -P allow_ypbind=1 authlogin_nsswitch_use_ldap=1
sudo setsebool -P httpd_can_connect_ldap on

Editing default configuration

Before you can use the OpenLDAP server, ensure that your server is configured properly. Check the default configuration written in the ldap.conf file.

  1. Open the ldap.conf file with your text editor of choice. In both Linux distributions, the nano text editor is installed by default, and you can edit the file with the following commands in the terminal:

    Ubuntu

    sudo nano /etc/ldap/ldap.conf

    CentOS

    sudo nano /etc/openldap/ldap.conf

  2. Uncomment the following contents:

    BASE     dc=example,dc=com
URI      ldap://ldap.example.com ldap://ldap-master.example.com:666

  3. Edit these entries, replacing the BASE with your distinguished name (Base DN), and the URI with your Fully Qualified Domain Name or IP address to your LDAP server. For example:

    BASE     dc=rpa,dc=ibm,dc=com
URI      ldap://rpa.ibm.com
    Important: The Base DN does not necessarily correspond to your Fully Qualified Domain Name (FQDN), and you can enter any Base DN that resembles an FQDN if you want to. However, the URI only accepts valid addresses that can connect to your server. Provide a valid IP address or FQDN to connect to your LDAP server.

  4. Press Ctrl+X and type Y to save and close the file in nano.

Configuring the root user

To perform administration tasks in LDAP, you must change the root user of LDAP. In LDAP entries, this user is known as olcRootDN.

In order to change anything in OpenLDAP, you must create LDIF files that contain information about what you want to change on the LDAP server. Do not edit the LDIF files in the /etc/ldap/slapd.d or /etc/openldap/slapd.d directories manually.

You need to create an LDIF file in a folder of your choice, preferably in a user folder, and put all the contents inside that file. Then you run the ldapadd tool to apply the LDIF file to your server.

In the following procedure, you change the default root user in LDAP to be able to manage all entries in the server:

  1. Create a password for your root user:

    slappasswd

    Enter your password and confirm it. The command outputs a password hash such as {SSHA}yh/GrT7AsObYUoHu89ynjzOljpBP10sp. Copy the output and save it in a text file.

  2. Create a rootpw.ldif file with your text editor of choice:

    nano rootpw.ldif

  3. Enter the following contents:

    dn: olcDatabase={0}config,cn=config
changetype: modify
add: olcRootPW
olcRootPW: {SSHA}yh/GrT7AsObYUoHu89ynjzOljpBP10sp

    Replace the {SSHA}yh/GrT7AsObYUoHu89ynjzOljpBP10sp with the hash that you obtained in the slappasswd command.

  4. Apply the changes:

    ldapadd -Y EXTERNAL -H ldapi:/// -f rootpw.ldif

  5. Import the basic LDAP schemas with the following commands:

    Ubuntu

    ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/cosine.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/nis.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/inetorgperson.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/openldap.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/dyngroup.ldif

    CentOS

    ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/cosine.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/nis.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/inetorgperson.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/openldap.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/dyngroup.ldif

  6. Configure access to your LDAP server and configure the Manager user to your server. Create the manager.ldif file:

    nano manager.ldif

  7. Enter the following contents:

    dn: olcDatabase={2}mdb,cn=config
changetype: modify
replace: olcSuffix
olcSuffix: dc=rpa,dc=ibm,dc=com

dn: olcDatabase={2}mdb,cn=config
changetype: modify
replace: olcRootDN
olcRootDN: cn=Manager,dc=rpa,dc=ibm,dc=com

dn: olcDatabase={2}mdb,cn=config
changetype: modify
add: olcRootPW
olcRootPW: {SSHA}yh/GrT7AsObYUoHu89ynjzOljpBP10sp
    • Replace the olcRootPW with the password hash that you obtained with the slappasswd tool.
    • Replace the dc=rpa,dc=ibm,dc=com with your own base DN.
    Tip: On Ubuntu, you might need to change the olcDatabase={2}mdb to olcDatabase={1}mdb. Check the name of the file with the output of the following command:
    ls /etc/ldap/slapd.d/cn\=config/

  8. Apply the contents:

    ldapmodify -Y EXTERNAL -H ldapi:/// -f manager.ldif

  9. Create an LDIF file to create your organization groups:

    nano org.ldif

  10. Enter the following contents:

dn: dc=rpa,dc=ibm,dc=com
objectClass: top
objectClass: dcObject
objectclass: organization
o: IBM RPA Server
dc: rpa

dn: cn=Manager,dc=rpa,dc=ibm,dc=com
objectClass: organizationalRole
cn: Manager
description: LDAP Manager

dn: ou=rpausers,dc=rpa,dc=ibm,dc=com
objectClass: organizationalUnit
ou: rpaUsers
  • Replace dc=rpa,dc=ibm,dc=com with your base DN.
  • You can change the names of the rpa and rpaUsers groups. IBM RPA does not require any specific name for user groups.
  1. Apply the contents with your Manager user:
ldapadd -x -D cn=Manager,dc=rpa,dc=ibm,dc=com -W -f org.ldif

You get prompted to enter your LDAP Password. Enter the plain text password that you defined for your LDAP root user.

Registering new users

LDAP entries are arranged in a tree-like structure called Directory Information Tree (DIT). Each entry of this tree is identified by a Distinguished Name (DN). The DN is composed by the specification of the entry in the DIT. For example, the user john in the rpa.ibm.com domain is identified by:

cn=john,dc=rpa,dc=ibm,dc=com

The cn field is the Common Name, which is most used to represent individual objects inside the tree. The dc field is the Domain Component, which is used to identify the components of the LDAP distinguished name.

If john is part of the rpausers group, then the following code block is the LDAP entry:

cn=john,ou=rpausers,dc=rpa,dc=ibm,dc=com

The ou field is the Organizational Unit, which is used to group other entries in the LDAP server.

To learn more about these object identifiers, see the LDAP OID Reference Guide🡥.

Users have attributes that can be registered in the LDAP entry. These attributes can correspond to the user's email, password, location, and more. IBM RPA requires that a user in the platform contains an email address, a username, and a password.

To register new users in the LDAP server, you must create LDIF files with all the attributes, and run the ldapmodify tool to register users. The following procedure details the entire process and the attributes that each user must have in the platform:

  1. Create an LDIF file:

    nano addUserName.ldif

    Replace addUserName with the name of the user that you want to add.

  2. Enter the following contents for the user:

    dn: cn=User Name,dc=rpa,dc=ibm,dc=com
changetype: add
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
uid: username
cn: User Name
sn: Name
displayName: User Name
mail: username@example.com
userPassword: {SSHA}xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    • Replace dc=rpa,dc=ibm,dc=com with your base DN.
    • In sn enter the user's surname.
    • In uid, enter the user's username.
    • In displayName, enter the user's display name.
    • In mail, enter the user's email address.
    • In userPassword, enter the hash of the user's password that you obtained with the slappasswd command.

  3. Enter the following command to register the user:

    ldapadd -D "cn=Manager,dc=rpa,dc=ibm,dc=com" -W -f addUserName.ldif

What to do next

The OpenLDAP environment is ready for the IBM RPA server. Proceed to Install the server.

If you are concerned about security, consider encrypting your OpenLDAP connection with SSL/TLS. See LDAP and Transport Layer Security (TLS) 🡥 for Ubuntu-specific instructions, and Establishing a secure connection 🡥. IBM RPA does not require SSL/TLS connections with OpenLDAP.

After you install the server, configure IBM RPA to connect with your OpenLDAP server. For more information, see Configuring UMS to connect with LDAP. For secured connections (LDAPS), see Configuring a secured LDAP connection (LDAPS).