Quick Links

Click here to contact a Symlabs representative.

LDAP Proxy :: Quick Start Guide

1 Welcome to LDAP Proxy!

An LDAP proxy plus virtual directory, supporting many protocols and functionality. This guide will help you to quickly create and run a configuration. You will need to have LDAP Proxy installed, and this guide assumes that it is installed in the directory /opt/ds/std in Unix systems and is accessible through Start Menu in Windows systems.

2 Operational Basics

LDAP Proxy works by listening on the network for requests using one or more protocols. These requests can then be evaluated and acted upon. Back-end servers, such as LDAP Directories, relational databases and other types of data sources can be accessed, and requests can be routed to them.

In most common usage patterns, Directory Extender acts as an LDAP proxy. This means that LDAP clients connect to LDAP Proxy, instead of connecting directly to the LDAP server. Since LDAP Proxy acts like an LDAP server, LDAP clients do not "notice" that they are in fact connecting to a proxy - the applications behave as if they were talking to an LDAP server directly.

LDAP Proxy will typically be configured to connect to one or more back-end LDAP servers (and potentially other data sources). Requests coming from the clients can then be routed to those back-ends as required. However, by utilizing LDAP Proxy, requests can be intercepted and transformed, by applying logical rules, and then be routed to one or more backend servers, or can optionally be responded to without forwarding the request on to a backend server at all.

Before creating a configuration, you must be aware of the basic concepts of LDAP Proxy: input, processing and output. LDAP Proxy supports these concepts through listeners, stages and server groups.

We understand that you may be eager to get started right away, but please do read the following short description of the LDAP Proxy concepts, as they are vital for the comprehension on how to create configurations.

2.1 Input (Listeners)

Listeners are the input for LDAP Proxy - they define the network ports that applications will connect to. In order for LDAP Proxy to work properly, you must at least configure one listener. Listeners are configured by specifying the protocol which they should support, a network port and an optional listen IP address. You can create multiple listeners on different ports and/or IP addresses. If you do not specify a listen address, LDAP Proxy will by default listen on the specified port on all IP addresses that the system has. Otherwise, the listener will only listen on the specified port of the specified IP address.

A listener can have an optional default server group. This is the default output back-end that requests will be routed to, unless they are being processed by one or more stages that act on the requests.

A listener can also have a list of stages where processing of requests will occur.

For typical configurations, you will need to define one or more LDAP or LDAPS (LDAP + SSL) listeners.

2.2 Output (Server Groups)

Server groups are the output of LDAP Proxy - they are comprised of the back-end servers that LDAP Proxy will send requests to. In a typical configuration, you will need to define at least one server group. Server groups are typically back-end LDAP servers or relational databases, but it is also possible to create server groups that use different protocols and access mechanisms in more advanced configurations.

Server groups, as the name implies, are groups of one or more servers that contain the same data. When a server group contains multiple servers, it is possible to load-balance operations between those servers, or to use a fail-over mechanism to automatically route requests around a failed server, to another server in the server group.

There are two types of server groups: automatic and manual. In almost all cases, automatic server groups should be used. These automatic server groups can be used for LDAP and relational database back-ends, and they support features such as connection pooling, fail-over and load-balancing. For experienced users, manual servergroups can also be created - however these come without the features mentioned before, and any connection pooling, fail-over or load-balancing features must be developed explicitly.

2.3 Processing (Stages)

Stages contain processing rules that intercept requests and responses, and act on them. There are many different plugins bundled with LDAP Proxy that implement a variety of useful functionality out-of-the-box. It is also possible to write customized processing rules using the embedded DirectoryScript language, and inserting them into a stage.

Two types of stages exist: automatic and manual. Automatic stages allow you to make use of the bundled plugins (also known as standard scriptlets) that come with LDAP Proxy. These plugins are easily configured using DSGUI. Manual stages can be used by experienced users to write their own rules as scriptlets and then adding these to hooks within a stage. A hook corresponds to a certain operation which is protocol specific - there can be one hook per operation type (per stage). In LDAP, for example, there is one hook for every protocol operation, such as REQ_BIND (BIND request), RES_BIND (BIND response), REQ_SEARCH (search request), RES_SEARCH_ENTRY (search entry), RES_SEARCH_DONE (search result), and so on.

If you are experimenting in order to learn LDAP Proxy, we recommend that you create automatic stages and explore the bundled plugins. Then, you may want to look at creating manual stages with hooks, and associating conditions to those hooks.

3 Before you start

Before you start this exercise, you must have the following:

LDAP Proxy installed
An accessible LDAP Directory Server installed and running

If you do not have LDAP Proxy installed on your computer, please refer to Installation chapter in the LDAP Proxy Administration Guide for a description on how to do this.

This Quick Start tutorial assumes that you have an LDAP directory server running somewhere on your network that is accessible from your computer. You will need the following information regarding your LDAP server:

The host name or IP address of your LDAP server
The network port where your LDAP server is running
The Base DN (root tree) of your LDAP server
If your LDAP server requires authentication, you will also need a DN and password to authenticate to your LDAP server.
Last but not least, your LDAP server should contain some entries that are browsable.

If you do not have an LDAP server installed yet, you will need to set one up before you will be able to proceed. Please refer to the manuals of your chosen LDAP server for installation instructions.

If you need some sample data, you can use the samples provided by default with LDAP Proxy. Sample data is stored within the data subdirectory within the samples directory of your LDAP Proxy installation. Sample data is stored as a set of LDIF files that can be loaded easily into an LDAP directory. If you choose to do this, make sure that you configure your LDAP server to create a root suffix for importing the sample data. Please refer to the README.TXT file in the samples subdirectory for more information.

4 A simple configuration

In this example, we will create a very simple configuration that acts as a simple LDAP proxy. No filtering, mapping or other advanced functionality will be used in this example.

4.1 Starting the GUI (DSGUI)

4.1.1 Linux / Solaris / AIX

In order to start the Graphical User Interface of LDAP Proxy run "bin/dsgui" from /opt/ds/std/ directory with the following command:

bin/dsgui

(or just "dsgui" from /opt/ds/std/ directory , if /opt/ds/std/bin is in your PATH).

4.1.2 Windows

You can launch DSGUI using the "Symlabs LDAP Proxy" shortcut in your Start Menu (under Symlabs > DE > RX.X.X). You can also run dsgui.bat in the root of the installation directory to launch DSGUI.

4.2 Step 1: Create a Configuration

Each LDAP Proxy process runs with a configuration that specifies what to do with the packets of data that it receives. So, the first step needed to run LDAP Proxy is to create a (default) configuration.

Fig-1: Creating a new Configuration

To create a configuration press the New Config button in the toolbar (on the far left). A file chooser will be shown that allows you to enter a name for the configuration. The default path used to store the configuration is the subdirectory configs within the directory that LDAP Proxy is installed. Click on the Filename field and write test as the name of your configuration and then click the New Config button. DSGUI will create a minimal default configuration. This configuration will need you to define an input listener and an output server group.

4.3 Step 2: Create a Listener

Listeners are the "input" nodes of LDAP Proxy - where clients connect to. Each listener needs a port number on which it will listen. There are several types of listeners available, allowing LDAP Proxy to support a variety of different protocols.

We will start by creating a Listener that makes use of the LDAP protocol. To create the listener, right-click on the Input node in the configuration tree in the navigation panel on the left side of the GUI. Select New Listener from the pop-up menu as depicted in the image.

Fig-2: Creating a new Listener

A window will pop up, asking you to enter a name for the new listener. You can choose any name that you wish - in this example, we have used the name ldap-input. Press the OK button.

Fig-3: Entering a Name for your new Listener

You will now see the newly created listener node as a sub-node of the Input node in the configuration tree in the navigation panel. Select the node by clicking on it. The configuration panel will appear on the right-hand side of the GUI window, and will display the various settings that need to be configured for the new listener.

Fig-4: The Listener Configuration Panel

Now configure a port on which LDAP Proxy should listen. If you are logged in as the root user under UNIX, and if no other server is listening on port 389 on your machine, you can leave the port as 389. Be aware that if you already have an LDAP server running on the same computer that LDAP Proxy is installed on, it is likely that this LDAP server will already be using port 389, and will conflict with LDAP Proxy when you attempt to run an instance of LDAP Proxy with this configuration. In Windows, Active Directory is by default configured to listen at port 389. For this reason, we recommend that you change this setting to port "3890" as a safe alternative, or if you are not the root user on the computer that will run LDAP Proxy.

The listen address is useful if your machine has multiple IP addresses, and you want LDAP Proxy to listen only on one address. By default this field is left blank, meaning that LDAP Proxy will listen on the specified port on all its IP addresses. In this first example, you may leave this field blank.

Leave every other parameter the way it is. Since we have not created a server group yet, we cannot yet select the Default Server Group. In the next steps, we will create a server group, and then come back to the listener configuration and set the newly created server group as the "Default Server Group" for this listener.

4.4 Step 3: Create a Server Group

A Server group defines the "output" for LDAP Proxy - the back-end servers that LDAP Proxy can send traffic to. There are two types of server groups: automatic and manual.

Automatic server groups come are simple to set up and come with useful built-in functionality, such as load-balancing or fail-over facilities. Health checking is also available for automatic server groups. Last, but not least, it is even possible to use a relational database as a virtual back-end for automatic server groups. Should you choose to make use of a relational database as a backend, you are able to define one or more tables or views in the database that will be treated as a virtual tree to be accessed via LDAP.

Manual server groups are very complex to set up and do not come with built-in functions such as load-balancing or fail-over facilities. They should only be used if you plan to implement this extra functionality yourself and really require the flexibility to define a very advanced output configuration. In the vast majority of cases, this is not the case and automatic servergroups should be used instead. Only make use of the manual server group option if you really know what you are doing and have very advanced configuration requirements.

In our example configuration, you can proceed by creating an automatic server group. Right-click the "Server Groups" node in the tree and then select "New Automatic Server Group". Alternatively, you can select the "Server Groups" node and click the "New " button located in the middle of the toolbar. You will be asked for a name of your server group. You can call this server group any name that you like. In our example, we are using the name "ldap-output".

Dsgui will create a sub-node under the "Server Group" node in the tree, labeled with the name that you provided above. Click on your newly created server group node and a configuration panel will appear on the right hand side of the dsgui window.

The next sections describe how to configure your server group. When you are finished editing the form in the configuration panel, click on the "OK" button to commit the changes that you have made to the current node. If you forget to press the "OK" button after configuring the listener, a warning dialog will pop up to ask you whether you want to save your settings to this node. This does not mean that the whole configuration is saved to disk - it just means that the changes you have made are applied to the node that you have been working on. If you choose not to save your changes, they will be discarded, and when you next select your listener, you will see the original listener configuration.

4.4.1 Configure your Automatic Server Group

The configuration panel, where you will configure your server group settings, will look different depending on the Protocol that you have selected for your server group. By default, the protocol is set to LDAP and the configuration panel has three tabs: Servers, Reliability/Performance and Connection Pooling. If you change the protocol to Relational Database, the configuration panel will change to provide alternative settings. In our example, we will stick to working with the default LDAP protocol.

In order to complete the configuration of our server group, we will need to:

Provide the hostname or IP address and the port for each server in the group
Configure a Fail-over / Load-balancing strategy
Define whether or not to use Connection Pooling

Adding Servers to your Server Group
We are almost finished configuring the server group. What remains is the essential step of adding at least one server to the server group. Make sure that the Servers tab in the configuration panel is selected. When this tab is selected, a tabulated list with two fields is available:

Host name / IP Address of the Server
Port of the server

Add the host name or IP address and the port of your back-end LDAP server to this table. In our set-up, and for this example, we are running our LDAP server on the same computer on which we are running LDAP Proxy, so we will configure the name localhost for the server name with port 389. Obviously, you should use the host name/IP address as well as the port number for the server on which you are running your example LDAP server, if you have a different setup to ours.

Fig-5: Configuring the List of Servers

When you are finished configuring the server group, click on the "OK" button. Your changes will now be applied to the server group. Although we will be making no further changes to the Server Group configuration, it is worth having a look at the settings available to you under the other two tabs.

Configure Fail-over for your Server Group

If you click the Reliability/Performance tab in the configuration panel, you will see a panel that will allow you to configure load-balancing and failover options for the server group that you are configuring.

Fig-6: Configuring Fail-Over

Automatic server groups implement fail-over, load-balancing or multisite facilities with health-checking by default. This functionality is applicable as soon as you have more than one server listed within the server group. In our simple configuration, only one server is listed within the server group, so it really doesn't matter whether you select fail-over, load-balancing or multisite, as this functionality will not be applied to the group until another server is added.

By default, fail-over is selected with the fail-over algorithm First available server, no fail-back. Leave this setting as it is for now. If you decide to add further servers to this server group in the future, you may want to define your failover strategy here.

Configure Connection Pooling

If you click on the tab entitled Connection Pooling. You will see a panel that will allow you to configure LDAP Proxy's connection pooling functionality.

Fig-7: Configuring Connection Pooling

Connection Pooling is a useful feature that can enhance performance dramatically when you have LDAP clients that connect to LDAP Proxy frequently, and only carry out few operations with each connection.

The main idea behind connection pooling is that LDAP Proxy will open a number of connections to the back-end servers, and will send requests over these connections. When connection pooling is used, special care must be taken in order to ensure that connection credentials are properly handled. Connection pools support either fixed credentials or proxy auth.

Fixed credentials for connection pooling mean that no matter how LDAP clients bind to LDAP Proxy, each non-bind request (i.e. every LDAP request except for BIND and UNBIND) are sent to the back-end servers using the connection pool. The connection pool is pre-bound using the fixed credentials supplied. Since this overrides the default permissions based model, this can potentially be dangerous, and should only be used if you know exactly what you are doing - for example, if you implement your own access control within LDAP Proxy or if you want to make sure that all your LDAP clients have the same privileges.

Proxy Auth is an extension of the LDAP protocol that allows connection pools to be used efficiently while preserving the credentials of the LDAP clients. A special "proxy auth user" must be created in the target back-end directories. This proxy-auth user will then be able to execute any request (except for BIND and UNBIND) on behalf of other credentials. The only exception is the Directory Manager, since the proxy auth extension does not allow executing a request on behalf of the Directory Manager. Whenever your LDAP server support proxy auth, and you have multiple credentials in use for your LDAP clients, this is a good feature to use.

In our example configuration, we will not use connection pooling, so you can ensure that the Use Connection Pooling check box is not checked.

4.5 Step 4: Reconfigure your Listener

Now that you've created a server within your server group, go back to the listener node by clicking on it in the tree. The configuration panel for the listener will come up in the right-hand side of dsgui. Select your newly created server group in the "Default Server Group" combo box. This will set your new server group as the default destination for traffic coming into the listener.

Fig-8: Set Default Server Group for Listener

Click the "OK" button to apply your changes to the listener.

4.6 Step 5: Save your updated configuration

Up until now all your changes have been kept in memory. If you have changes pending to be committed to the file system, the Save button in the toolbar will contain a red exclamation mark. If you have properly committed the changes in your forms to your nodes, an explanation mark will have appeared in the Save button on your toolbar. Press it and your saved configuration will reflect the latest changes done in DSGUI.

4.7 Step 6: Run your configuration

We are now ready to run our configuration. In this very basic configuration, no Processing directives have been defined and the instance of LDAP Proxy will only connect to a single backend server.

To run the configuration, click on the "Run" button towards the end of the toolbar, or select "Run" from the "Process" Menu. This will start the LDAP Proxy service (the dsproxy program) and will load your configuration. Output from dsproxy will be displayed in the log area at the bottom of the dsgui window. The log area will only appear once you have started the service. If dsproxy is unable to start for some reason, an error dialog will pop-up to notify you of the problem. If everything is as it should be, your log area should contain lines that look similar to the following:

Starting LDAP Proxy.

tb7c616c0 8a91:19e ECONF_LISTEN_OK f3a listen on port=9990 fd=3

tb7c616c0 8a91:19e ECONF_LISTEN_OK f32 listen on port=3890 fd=4

These messages indicate that LDAP Proxy has successfully started and is listening on two ports: the port that you have specified for your listener, and the default administration port used by LDAP Proxy.

4.8 Troubleshooting
If you see a different message when you start LDAP Proxy, something must have gone wrong. The following problems are commonly encountered problems.

If in the log window you see a message such as:

tb7bfc6c0 8a91:18d EIOBIND d Unable to bind socket 4

(port=389): Permission denied (trying again in 2 secs)

tb7bfc6c0 8a91:193 EIOBIND d Unable to bind socket 4

(port=389): Permission denied (giving up)

This means that you have selected port 389 in your listener, however you are not logged in as the root user and therefore have no permission to bind to this port. On UNIX systems, listening on ports lower than 1024 is typically reserved for the root user. As a remedy, go back to your listener and choose a port higher than 389 (for example, 3890), and make sure that this port is not in use. Save your configuration, and stop and re-run LDAP Proxy. Stopping LDAP Proxy can be done by either clicking on the "Stop" icon in the toolbar, or by choosing "Stop" from the "Process" menu within dsgui.

If you see an error message such as:

Starting LDAP Proxy.

tb7ca86c0 8a91:19e ECONF_LISTEN_OK f39 listen on port fd=3

tb7ca86c0 8a91:18d EIOBIND 62 Unable to bind socket 4

(port=3890): Address already in use (trying again in 2 secs)

tb7ca86c0 8a91:193 EIOBIND 62 Unable to bind socket 4

(port=3890): Address already in use (giving up)

This shows that one of your ports was successfully associated, but the other one is used by some other process. This means that the port that you have chosen for LDAP Proxy is already in use. Go back to your Listener and configure a different port that is not already in use.

In order to get a list of all ports currently in use by other programs on your UNIX system, you can type the following command:

netstat -an | grep LISTEN | grep tcp

In Windows, you can do the same by entering the following command at the command prompt within a cmd window:

netstat -an | find /i "LISTENING" | find /i "TCP"

This will list all ports that are currently in use.

4.9 Step 7: Test the configuration with an LDAP browser

At this point, your new LDAP Proxy configuration should be up and running. You can now connect to LDAP Proxy with an LDAP client, using the port number that you've specified in the listener. The LDAP Proxy GUI has an integrated LDAP browser that you may consider using - it makes it very simple to browse and change data in your LDAP servers. A very convenient way to test configurations, is to have two LDAP Browser windows open - one pointing to your LDAP back-end server(s), and the other one pointing to LDAP Proxy.

To start the integrated LDAP Browser, select "LDAP Browser" from the "Extras" menu or click the "Browser" button on the toolbar. Alternatively, the LDAP Browser can be started from the contextual menu of your automatic server group node, by right clicking on your defined Server Group.

When you start the integrated LDAP Browser, a window will appear that will require you to enter the details for the server that you would like to connect to:

Host name or IP Address of your LDAP server
Port on which your LDAP Server is listening
Root Suffix - DN on which the LDAP Browser should start
Bind DN (if required) - credential for authentication
Password (if required) - Password to be used for authenticating with the credential

Fig-9: Entering LDAP Server Parameters

Start by entering the details of your back-end LDAP server (not LDAP Proxy). This is because you should make sure that you can connect to your LDAP back-end server first - if this is not possible, then LDAP Proxy will most likely not be able to work with your current configuration and there will likely be errors in the logging area of the dsgui window.

At the top of the window, there is a pull-down combo-box which offers shortcuts to servers that you frequently connect to. You can configure the list of servers in this combo-box by editing the node "LDAP Browser Preferences" in dsgui's Preferences. If you have populated this list of servers in the application's preferences, you can select the shortcut to your LDAP server. If you do not have any predefined servers listed in the combo-box you will need to fill in the details for your LDAP back-end server (not LDAP Proxy) below and click the "Test" button.

Hint: If you will frequently access a server, it is worth defining a shortcut for this server in the Preferences.

The LDAP Browser will try to connect to the server, and either return a dialog indicating success or a dialog indicating an error, if the connection fails. If the test was successful, click OK and a new window will appear to allow you to browse the tree of your LDAP server.

Now, without closing the LDAP Browser that you've opened, start another LDAP browser in the same way that you started the first one. Return to the main dsgui window and start a new LDAP Browser. When the pop-up window appears to provide the server details, fill in the details in order to connect to LDAP Proxy. In its current configuration, it effectively acts as if it were an LDAP server. As such, we should be able to use the LDAP browser to connect directly to the Input Listener that we have defined for this instance of LDAP Proxy.

Fig-10: Entering Parameters to connect to Proxy

Fill in the hostname field by using either localhost or 127.0.0.1 (unless you've specifically configured a Listen address in the listener - in which case, you will have to enter the IP address that you have entered there). Fill in the same port that you have used in the listener. In our example, this was port 3890. If you need to authenticate to access your backend LDAP server, fill in the Bind DN and password that you would use on the backend server. Then fill in the Root Suffix, or alternatively click the "Suffixes" button and select a root suffix from the list that will pop up.

The Two Browser Windows

Fig-11: The two Browser Windows

You should now see an identical view of your LDAP tree as the one provided by your LDAP server. However this view of the tree is being provided by LDAP Proxy. Since you have not configured any mapping, these views should effectively be exactly similar. Congratulations! You've built and run your first, simple configuration with LDAP Proxy.

You can now go through the samples chapter in LDAP Proxy GUI's Guide and Reference Manual to learn how to configure additional functionality to the simple configuration that you have just created within dsgui. These tutorials will assume that you have loaded the sample test data that is contained in the data subdirectory of the samples directory of your installation.

About Symlabs

Symlabs focuses on Identity Management. We offer "standards based" software components like the Symlabs Virtual Directory Server, Symlabs LDAP Proxy and the Symlabs Federated Identity Suite. We also offer software support, training and professional services.