Artisan IMG > LDAP Client (ldap-client) (e2f73e87716a1c8c43e6c8a580f4fc73)

LDAP Client helper
1.2

A LDAP Client helper for interacting with an LDAP/LDAPS server.

Overview
Copy

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

To allow tray.io to connect to your LDAP service, you'll need to white list ALL of the following static IP addresses:

  • 52.40.200.248

  • 52.39.10.61

  • 52.26.59.155

Authentication
Copy

Credentials
Copy

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

Host Information
Copy

LDAP
Copy

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.

LDAPS
Copy

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.

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:

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.

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.

Pagination
Copy

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 helper used to chunk the list of DNs:

Batch get all attributes on each set of DNs:

Modify
Copy

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
Copy

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
Copy

List all users
Copy

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.

Search Raw
Copy

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

Find users by email address
Copy

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 Raw
Copy

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

NOT filter rules
Copy

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 Raw
Copy

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

Nested filters
Copy

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.

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
Copy

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.

Assign a user to a group
Copy

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.

Remove a user from a group
Copy

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.

Delete a user
Copy

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