1. Home
  2. LogonBox SSPR
  3. Administration
  4. User Directory
  5. Connecting to an LDAP Directory

Connecting to an LDAP Directory

Can't find what you're looking for?
Request Supporthere

Christopher Dakin 11 November, 2021

Introduction

LDAP is an open standard protocol for user directories, this article shows you how you can connect your on-premise LDAP server to your cloud tenant enabling your users to manage their account from the cloud. 

As LDAP is an open standard, there are many different LDAP servers available, hence configuration of LDAP can be more complicated. Some examples of LDAP servers are:

  • OpenLDAP
  • Microsoft Active Directory (but use our Active Directory Directory for better support)
  • NetIQ eDirectory
  • Apache DS
  • Oracle Internet Directory
  • IBM Security Directory Server

For the purposes of this article we will connect to an example OpenLDAP server.

 

Prerequisite 

In order for your cloud tenant to locate your LDAP server the directory needs to be visible to the tenant, whether the directory is located on the same network as your cloud tenant (if you have hosted your own LogonBox server) or through a secure node agent connection - as documented in the article titled Installing a secure node agent.

 

Step 1 - Create Directory

Whilst managing a tenant, navigate to Users & Permissions and select Configure User Database located at the top of the User table. 

 

From the form that opens up type on a new Realm Name and select Realm Type as LDAP (Generic).

 

 

 

Step 2 - Configuring your server Settings

With the correct realm type selected, the next step requires the LDAP settings to be configured.

There are 2 links at the top to switch between standard and advanced settings. Step 2 here concerns all of the Standard settings.

 

Step 2a - Connection

The first tab is where you enter the connection details for your LDAP server. You will need to provide the following information:

  • LDAP Host - the hostname or IP address of the LDAP server you want to get users from.
  • Base DN - The Base DN of the server (usually the domain name of the server in dc=example,dc=com format). You can filter a subset of users from a specified sub container if required which can help with performance on a large userbase, using ou=container, dc=example,dc=com.
  • Backup Hostnames - A list of other hostnames to contact if the primary LDAP server cannot be contacted.
  • Service Account DN - The user name of the service account that will be used to list end edit users. Needs to be the full Distinguished Name (or DN). For example, cn=Manager,dc=example,dc=com.
  • Service Account Password - the password for the above user.

 

If you happen to be connecting to an OpenLDAP server hosted on a Linux system, there is a chance that the default advanced settings might work without any modification. If so, you can cpress Update to save the config. From there the first synchronisation with your LDAP will begin, you will see a green message stating, reconciling with directory. Once completed, a similar message stating, reconcile finished successfully, will be shown. 

However in most cases you will need to configure the other settings as the LogonBox server will need to know the class and property names for users and groups, which can differ from LDAP to LDAP.

 

Step 2b - Users

The second tab, Users, is where the configuration is entered of what a user object looks like on the LDAP server. The required information can be discovered by using an LDAP browsing tool to inspect a user object.

  • Class: The objectClass name that belongs only user objects. For example, there might be 3 objectClass entries for a user – top, person, organizationalPerson. Top is not unique as groups have this class too, so person or organizationalPerson would be valid entries in this case. Defaults to posixAccount
  • Name Attribute: The attribute that represents the username that will be used to authenticate with. Defaults to uid.
  • Identifier Attribute: An attribute that uniquely identifies a user. Can be the same as the identity name attribute, or any other unique value. Defaults to uidNumber.
  • Primary Role Identifier Attribute: (Optional) The attribute that represents the unique identifier of the user’s primary role. Defaults to gidNumber.
  • Primary Role Name Attribute: (Optional) The attribute that represents the name of the user’s primary role. Defaults to blank.

 

Step 2c - Groups

The third tab is Groups. This asks for the same information as the User tab, except for a group object (sometimes known as roles in LDAP).

  • Class: The objectClass name that belongs only group objects. For example, there might be 3 objectClass entries for a group – top, group, organizationalRole. Top is not unique as users have this class too, so group or organizationalRole would be valid entries in this case. Defaults to posixGroup.
  • Name Attribute: The attribute that represents the username that will be used to authenticate with. Defaults to cn.
  • Identifier Attribute: An attribute that uniquely identifies a user. Can be the same as the identity name attribute, or any other unique value. Defaults to gidNumber.

  

Step 2d - Password

The fourth tab is Password and concerns the password attribute and encoding method.

  • Password Attribute: The attribute that represents the user’s password. Defaults to userPassword.
  • Password Encoding: The encoding type to use when setting the user’s password. Several different password encoding methods are supported, choose the encoding that is already in use for existing accounts on the LDAP server. Defaults to plain.

 

Step 2d - Principal Filter

The last tab, Principal Filter, is optional. If nothing is configured here then all users and groups on the LDAP server will be cached into LogonBox. If you wish to exclude and users or groups, you can do so in this tab.

Users can be excluded by adding a filter using Ignored Users or Ignored Groups. 

To add a filter, type in the user or group name into the relevant text box and press enter (or click on the plus icon) to add it to the list box below that. An existing filter can be removed by clicking on the X to the right of the name in the list.

 

Step 3 - Advanced Settings

The configuration items below are not neccesary (with the exception of the Users and Groups tabs) to get your LDAP connected and synching with your tenant, however they may be useful for those that wish to add a little more control.

To access these settings click the Advanced Settings link above the tabs.

 

Step 3a - Advanced

The first tab, Advanced, contains extra settings relating to the connection:

  • Encryption Method: The protocol to use when making the LDAP connection, choose between plain or ssl. Defaults to ssl.
  • Follow Referrals: Check if any returned referrals should be followed. Defaults to ON.
  • Timeout: The amount of time in seconds to wait before a connection to LDAP fails. Defaults to 30 seconds.
  • Page Size: Users are read in blocks (or pages) of users at a time whilst caching. This sets the amount of users to be read in each page and should be set to less than the paging setting configured on the LDAP server. Defaults to 1000.
  • Read Only: Enable if you do not want to manage or update users from the Hypersocket server. Defaults to OFF.

 

Step 3b - Reconcile

 

The other tab that is available is Reconcile. This contains settings relating to how the users are cached in Hypersocket. Hypersocket connects to the remote user database periodically to update its list of cached users and then performs an update (reconcile) of this cache by either adding new users, deleting users that no longer exist or updating existing users.

The reconcile settings are:

  • Rebuild Cache: On next reconcile, delete the cache and import all user objects from scratch. This takes more time than a normal reconcile. Defaults to OFF.
  • Purge Duplicates: On rare occasions an out of date cache can cause duplicate users to be created in the cache. If that happens, this option can force removal of these duplicate users and rebuilds the cache. Defaults to OFF.
  • Cache Passwords: Hypersocket will generate a one-way hash of the users’ passwords the next time they log on and cache this. Subsequent authentication attempts do not need to contact the domain controller for authentication until the Hypersocket server is restarted. Defaults to OFF.
  • Reconcile at Login: Performs a reconcile of the user’s account at login. This can ensure that the latest information for that user (such as group membership and AD attributes) are perfectly up to date each login. Generally this is not needed as user accounts do not change very often. Defaults to OFF.

 

Conclusion

This article has detailed the core settings needed for your tenant to begin reconciling with your LDAP server. Your tenant should now successfully begin synchronizing with your LDAP enabling your users to be able to fully manage their accounts in the cloud.