Set Up LDAP Using an OpenLDAP Container
Litmus Edge allows you to set up an LDAP server for managing user access to Litmus Edge devices, eliminating the need to define users locally on each Litmus Edge device.
Before completing these steps, make sure to do the following:
- Have access to Litmus Edge version 3.11.1 or later.
- Have basic knowledge of LDAP protocol.
To set up the OpenLDAP container and access the PHP LDAP Admin UI:
In Litmus Edge, navigate to Applications > Containers.
Applications > Containers page- Copy and paste the below commands and click the Run button.
- Command to run the OpenLDAP server: docker run -dit -p 389:389 -p 636:636 --name my-openldap-container osixia/openldap:latest
Command to run the web UI to configure users and groups: docker run -dit --name phpldapadmin-service -p 9080:80 --env PHPLDAPADMIN_LDAP_HOSTS=<IP-OF-MY-OPENLDP-CONTAINER> -e PHPLDAPADMIN_HTTPS=false osixia/phpldapadmin:latest Replace <IP-OF-MY-OPENLDP-CONTAINER> with the IP address of the openLDAP container.
LDAP docker container images
Once both containers are running, you can access PHP LDAP Admin UI by going to <IP Address of LE>:9080 in your web browser. You should see this landing page:
PHP LDAP Admin UI Landing Page
To configure the Litmus Edge LDAP container, we need to first create some users and groups on the LDAP server. We will create two users, Alice Smith and Bob Jones, and two groups, litmus-admin and litmus-viewer.
These LDAP groups will correspond to the Administrator and Viewer groups in Litmus Edge, respectively.
To proceed, we need to log in to the LDAP server using the default credentials from the container.
Login DN: cn=admin,dc=example,dc=org
Password: admin
To log into the PHP LDAP Admin UI:
Click the login button.
PHP LDAP Admin UI Landing Page - LoginEnter the default Login DN and Password.
PHP LDAP Admin UI - Login Dialog BoxUpon successful login, you will see the landing page and an empty tree structure on the left side.
PHP LDAP Admin UI Landing Page
Note: To keep this guide simple, we will add the groups and users under this root level. However, in an actual LDAP server, the structure is more complicated and contains many subfolders.
To add users to the LDAP server:
Click the Globe icon and then select Create a child entry. The Create Object page appears.
PHP LDAP Admin UI Create User Page- From Templates, select Default.
- From the ObjectClasses list for the LDAP server container, select inetOrgPerson.
Click Proceed >>
PHP LDAP Admin UI Create User Dialog Box- Fill out the basic details for the users:
- cn: asmith
- sn: Smith
- givenName: Alice
- employeeNumber: 12345
- Password: <enter a password>
Click Create Object and then Commit.
PHP LDAP Admin UI Create LDAP Entry Page- Repeat the above for Bob Jones (make sure you do this on the root of the LDAP by clicking on dc=example, dc=org and Create a child entry). Enter the following details:
- cn: bjones
- sn: Jones
- givenName: Bob
- employeeNumber: 54321
- Password: <enter a password>
Click Create Object and then Commit.
PHP LDAP Admin UI Create LDAP Entry Page
You should see both Alice and Bob added to the LDAP server:
To add groups to the LDAP server:
- Click the Globe icon and then select Create a child entry. The Create Object page appears.
- From Templates, select Default.
- From the ObjectClasses list for the LDAP server container, select groupOfNames.
- Click Proceed >>
- Fill out the basic details for the groups:
- cn: litmus-admin
- member: Click the search icon and select cn=asmith
Click Create Object.
PHP LDAP Admin UI - Create GroupsClick Commit.
PHP LDAP Admin UI Create LDAP Entry Page- Repeat the above for Litmus-viewer group (make sure you do this on the root of the LDAP by clicking on dc=example, dc=org and Create a child entry). Enter the following details:
- cn: litmus-viewer
- member: Click the search icon and select cn=bjones
Click Create Object.
PHP LDAP Admin UI - Create GroupsClick Commit.
PHP LDAP Admin UI Create LDAP Entry Page
We should now have four entries under the root folder of the LDAP server. Next, we will configure Litmus Edge.
To define the LDAP server connection from Litmus Edge:
Navigate to System > LDAP/AD Auth and then click the + button to define a new LDAP Provider.
System > LDAP/AD Auth PageThe Add Provider dialog box appears. Here, we have the option to start from a template or to define everything manually. Select Advanced to fill in all details and understand each parameter.
Add Provider dialog boxOn the Generic tab, give the provider a name and click Next. The default selection for Type is generic.
Add Provider dialog box - Generic tab- On the Connection tab, enter the following:
- Host: Enter the IP address of the LDAP container as the host.
- Port: Enter the port number used to define the docker container for the LDAP server. For this guide, we used port 389 in Step 1.
- Bind DN and Bind DN Password: Enter the same admin user credentials to authenticate PHP LDAP Admin UI.
Click Next.
Add Provider dialog box - Connection tab
In the User tab, we define the parameters for Litmus Edge to search and parse relevant information from the LDAP server, such as first name, last name, username, and UserID.
The following information defines the User configuration:
- User Search Base DN: The DN (Distinguished Name) of the folder in the LDAP server is the starting point for searching users. As our LDAP server is simple, we'll start searching from the top-level folder, which is dc=example, dc=org.
- Search Scope: Litmus Edge can use this setting to determine the level at which it should search for users. There are three options in the drop-down menu to choose from:
- base: Search at the base level of the User Search Base DN.
- one: Search one level below the base level of the User Search Base DN.
- sub: Search all levels below the User Search Base DN. For this guide, select sub to search everything under the top level folder.
- User Search Filter: We require a filter to provide Litmus Edge with a list of users who should have access to it. In a practical scenario, individuals may want to limit access to only specific employees, but for our guide, we will match any entry that has an objectClass of inetOrgPerson: (&(objectClass=inetOrgPerson)). If you need more information on how to write LDAP filters, you can refer to How to write LDAP search filters.
- Attribute For Unique UserID: This is the attribute that Litmus Edge will use as a unique identifier for each user. In this example, we will use employeeNumber.
- Attribute For Username: This is the attribute that Litmus Edge will use for the username when logging in to Litmus Edge. In this example, we will use cn. So Alice's username will be asmith and Bob's username will be bjones.
- First Name: This is the attribute that Litmus Edge will use for the user's first name. This is the givenName attribute that we filled out when creating Alice and Bob's user accounts in the LDAP server.
- Last Name: This is the attribute that Litmus Edge will use for the user's last name. For this example, we will use sn attribute.
After configuring your User tab, it will look like the screenshot below.
The Group tab is same as the user section, but this time we are telling Litmus Edge how to search for the groups.
The following information defines the Group configuration:
- Group Search Base DN: The DN (Distinguished Name) of the folder in the LDAP server will be our starting point for searching groups. As our LDAP server is simple, we'll start searching from the top-level folder, which is dc=example, dc=org.
- Search Scope: Litmus Edge can use this setting to determine the level at which it should search for groups. There are three options in the drop-down menu to choose from:
- base: Search at the base level of the Group Search Base DN.
- one: Search one level below the base level of the Group Search Base DN.
- sub: Search all levels below the Group Search Base DN. For this guide, select sub to search everything under the top level folder.
- Group Search Filter: We require a filter to provide Litmus Edge with a list of groups who should have access to it. For this guide, we will match any entry that has an objectClass of groupOfNames and then we will add an additional filter to only include the groupOfNames that have a cn that starts with Litmus. The filter looks like the following: (&(objectClass=groupOfNames)(cn=litmus*)).
- Group Name Attribute: This is the attribute Litmus Edge will use to display the group name. In this example, we will use cn.
- Group Membership Attribute: This attribute informs Litmus Edge which users belong to the group. This information is necessary for Litmus Edge to determine a user's permissions upon login. In this example, we use member attribute.
- Group Member Value Type: This attribute tells Litmus Edge about the type of information stored in the list of members. When we added Bob and Alice to the group, their user account DN was inserted. In this example, Litmus Edge can use the attribute DN to identify members in the list.
After configuring your Groups tab, it will look like the screenshot below.
You will find a Test button on this screen that will verify the input settings.
Click the Test button. The Update Provider dialog box appears. It shows the expected results for two users and two groups.
After a successful test of the connection, click Create and Map Groups. The Map Groups dialog box appears.
Litmus Edge was able to connect to the LDAP server and find the list of groups that we created.
Next, we need to map these groups to the local groups we have on Litmus Edge. This mapping will let Litmus Edge know which permissions the user should be granted when they log in.
From the drop-down menu, map litmus-admin to Administrators and litmus-viewer to Viewers and click Save.
Now, we will log in as Alice or Bob and verify that they each have the Administrator and Viewer permissions, respectively.
Note: Please use the login credentials that were configured for Alice and Bob in Step 2a.
Select openldap from Provider ID drop-down to log in via LDAP.
If you select Internal provider, Litmus Edge will look for a local user with the username of asmith, which does not exist. If your login was successful, you should see the EULA and need to accept it (this is only the case for the first login).
When you log in as Alice, you have complete access to Litmus Edge. To check, navigate to System/Users/Groups and select Administrators. You will notice that Alice has been added to the Administrators group. This is expected because Alice is part of the litmus admin on the LDAP server.
If you log in as Bob and try to access the same page as System/Users/Groups, you will find that you do not have the necessary access to view the page. This is because Bob has been assigned the Viewers group permissions and does not have the required privileges to view the page.