Open Navigation

LDAP Client

A client for interacting with an LDAP/LDAPS server.

Overview

The LDAP client connector provides operations for interaction with LDAP/LDAPS services.

Authentication

Credentials

For all authentication types, you will require username, password, and the Base DN for your connection.

The Base DN is the base domain name for the LDAP directory. For example, if a user's DN was CN=Bob,CN=Users,DC=example,DC=com, the base DN would be DC=example,DC=com

LDAP Username/Password/DN Authentication

Host Information

For a regular LDAP connection, you need the URL and Port for the host information. Do not include the protocol or the port in the URL.

URL and Port in LDAP Auth

When adding an LDAPS connection, URL and Port are required just like LDAP, but you can also provide additional options such as a certificate, or custom TLS Options. URL and Port in LDAP Auth

A common TLS option to add here might be rejectUnauthorized: false, allowing you to connect to LDAPS instances that have a self signed certificate. To do this, you would add a property to TLS Options, change the type to boolean and untick the box. The result can be seen below:

LDAPS Host settings with rejectUnauthorized false

The search operation can be used to perform LDAP queries, using a filter generated by the UI in the connector. If you want to enter your own custom filter, you can use the Search Raw operation, which will let you do so.

Alongside the filter, you can choose the scope for the query, as well as which attributes to return. You can return either a list of the DNs, or a selection of attributes. LDAP search attributes

If attributes is chosen, the default return type is to retrieve all attributes of the results. If you want to narrow this down further, you can provide a list of attributes to return.

Due to the possibility of very large result datasets, search operations will return up to 50 entries if returning as JSON. To return all the results, you can either choose to return the data as an XML file, or by paginating through the results as JSON by utilising the Batch get by DNs operation.

To return the data as an XML file, you can tick the Return as file option in the search operation. Return as file

Pagination

The easiest way to paginate is to perform a search query with DNs Only chosen for the return type, then processing the results in chunks. You can utilise the chunk operation in List Helpers to separate the list of DNs into groups of 50. Afterwards, you can loop through the groups of DNs and get their contents using Batch get by DNs.

Search operation for all users: List all users

List helper used to chunk the list of DNs: Chunk operation

Batch get all attributes on each set of DNs: Batch get by DNs

Modify

The LDAP Modify operation allows you to create entries, as well as modifying existing entries.

  • Add - The add operation allows you to add new entries into LDAP. To do this, you will need to specify the DN of the entry being created, as well as any required properties.

  • Replace - The replace option allows you to modify properties of existing LDAP entries. To do this, you will need to supply the DN of the entry being modified, as well as any properties being modified.

  • Delete - The delete option within the modify operation shouldn't be confused with the main delete operation. The delete within modify is used to remove properties from existing LDAP entries. To do this, you must provide the DN of the entry being modified, as well as the keys of any properties to be removed.

Modify DN

Performs an LDAP Modify DN (rename) operation against an entry in the LDAP server. A couple points with this operation:

  • There is no ability to set "keep old DN." It's always going to flag the old DN to be purged.
  • The client code will automatically figure out if the request is a "new superior" request ("new superior" means move to a different part of the tree, as opposed to just renaming the leaf).

Example use cases

List all users

To list users inside an organisational unit (commonly cn=Users), you can use the search operation to filter objects by their objectClass. To do this, you can use a filter that ensures that objectClass is equivalent to User.

List Users

The example shown here is equivalent to the regular Search, but is in raw query form using the Search Raw operation. List users -  Raw query

Find users by email address

Here is an example of using multiple filters. In this example 2 filters are being used together, one for checking object class and one for checking email address. The AND option is chosen so that only results that match both filters are returned. To add extra filters to search operations, you can add them in the further filters input.

Search - Find user by email

This is how you would do the same query using raw query form. The & signifies that both filters must be matches.

Search Raw - Get user by email

NOT filter rules

Sometimes you might want to create rules to filter out certain result. To do this, you would select Not Equals in the dropdown for the filter.

The following query returns results that dont have the first name of Alex.

Search - Not Equals

To perform a not equals filter in a raw query, wrap the filter in !(), like in the example below.

Serch Raw - Not Equals

Nested filters

The following is an example of a query that would need to be done using the Search Raw operation. A raw query is required as the complexity is higher, due to the use of nested queries. The example searches for Users who have first names that are either Alex or Keith.

Image

In the example, you can see that inside one of the AND filters, there is an OR filter, signified use the pipe character( | ). This query thus implies that as well as being a User class object, the given name needs to be either Alex or Keith.

Create a user

To create a new user, use the add operation and enter the DN of the new user entry. The only required entry parameter to create a user is objectClass=User, but other entry items such as givenName, surname, mail, and password are commonly added.

Create User

Assign a user to a group

To add a user to a group, you need to modify the list of members in the group to include the user. The easiest method of doing this is to use the LDAP modify operation, with the Add option. The attribute you need to modify is usually member, and it is an array of strings.

Add user to group

Remove a user from a group

Removing a user from a group is very similar to adding a user to the group, except you should use the Delete option instead of Add. Remove user from group

Delete a user

To delete a user, use the delete operation and pass in the DN of the user to be deleted. Delete User

Was this article helpful?
Yes
No