Tutorial #1 - Merge Users From Multiple Directories

Tutorial #1 - Merge Users From Multiple Directories

1 Overview

There can be many reasons why an organization would need to take users from many systems and present them as a single tree. In many large enterprises, some users may exist in one database or directory while another group of users exists on a separate system. For example, a lot of HR systems will contain employee records only. These systems frequently exclude contractors and temporary employees. However, there are applications, such as address books, that require information about users contained in all of the systems in an organization. Most of these applications are designed to only read from a single source repository. The Virtual Directory Server (VDS) solves this problem by presenting users from multiple systems on a single virtual tree accessible from one system. In this tutorial, the users from multiple directories are going to appear to exist in a single directory branch accessible from the Virtual Directory Server.

2 Assumptions

1. Virtual Directory Server is installed and configured properly; VDS is currently running.

2. Directory 1 & 2 are both installed and accessible from the computer on which Virtual Directory Server is installed.

3. Both of your directories are populated with users.

4. None of the users in Directory 1 exist in Directory 2 and vice versa.

5. Directory 1 & 2 are both accessible on port 389 (default ldap port)

6. You have a good understanding of the DIT structure of your directories.

7. Port 3890 is available on the computer in which Virtual Directory Server is installed.

3 Create a New Configuration

1. Click File on the menu bar, then click New.

2. Click the OK button to select the option to create a Local configuration.

3. Enter MergeTreesTutorial for the filename when prompted, then click the Save button and the following will appear:

   
   
   Fig-1: Create a new configuration

4 Server Group Configuration

Server Groups are the directories and / or databases where your user information is stored. Examples include Active Directory, Sun Directory Server and Oracle database. For this tutorial we will be creating two Server Groups, one for Directory 1 and another for Directory 2.

4.1 Add Directory 1

1. Click on the Output button on the left-hand side of the application and the following will appear:

   
   
   Fig-2: Click on the Output node to Add a Server Group

2. Click on the New Server Group button near the bottom of the screen.

3. Enter Directory 1 for your new Server Group and leave the Server Group Type as Automatic and then click the Okay button.

4. Click on the Directory 1 node in the navigator tree on the left-hand side of the screen and the following will appear:

   
   
   Fig-3: Configure the first Server Group

5. Verify that the Protocol is set to ldap.

6. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 1.

7. Click on the Connection Pooling tab and check the Use Connection Pooling checkbox. The following will appear:

   
   
   Fig-4: Configure Connection Pooling for the first Server Group

8. Click on the Use Fixed Credentials radio button then enter the Bind DN and Password for the user that has appropriate access to Directory 1.

9. Change the number of Pool Connections from 10 to 2.

10. Click the OK button near the top of the application to save the Directory 1 Server Group Configuration.

4.2 Add Directory 2

1. Click on the Output button on the left-hand side of the application and the following will appear:

   
   
   Fig-5: Click on the Output button to Add a second Server Group

2. Click on the New Server Group button near the bottom of the screen.

3. Enter Directory 2 for your new Server Group and leave the Server Group Type as Automatic and then click the Okay button.

4. Click on the Directory 2 node in the navigator tree on the left-hand side of the screen and the following will appear:

   
   
   Fig-6: Configure the second Server Group

5. Verify that the Protocol is set to ldap.

6. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 2.

7. Click on the Connection Pooling tab and check the Use Connection Pooling checkbox. The following will appear:

   
   
   Fig-7: Configure the Connection Pooling for the second Server Group

8. Click on the Use Fixed Credentials radio button then enter the Bind DN and Password for the user that has appropriate access to Directory 2.

9. Change the number of Pool Connections from 10 to 2.

10. Click the OK button near the top of the application to save the Directory 2, Server Group Configuration.

5 Processing Configuration

At this point, we are ready to configure the Virtual Directory Server instance to provide the functionality that we want. In order to do this, we will set up a "Processing Stage" where all packets moving through Virtual Directory Server can be analysed to see whether particular functionality should be applied. In any single VDS deployment, you can have multiple Processing Stages that implement different functionality depending on the PDUs that pass through the system. In this tutorial, however, we will be implementing a single Stage. This stage is going to utilize a default plugin that will merge users from two directories into one virtual directory. This plugin is called the Merge Trees plugin and is provided by the Virtual Directory Server to allow you to quickly and easily implement the functionality that you're looking for.

1. Click on the Processing button on the left-hand side of the application and the following will appear:

   
   
   Fig-8: Click on the Processing node

2. Click on the New Stage button near the bottom of the screen.

3. Enter Merge Users as the name of the new stage and leave the stage type as Automatic and then click the Okay button.

4. Click on the "stage=Merge Users" node on the left-hand side of the screen.

5. Click on the Add Plugin button and the following will appear:

   
   
   Fig-9: Add the Merge Trees plugin

6. Scroll to the bottom of the list, click on Merge Trees and click the OK button.

7. Click the Merge Trees node in the navigator on the left-hand side of the screen and the following will appear:

   
   
   Fig-10: Configure the Merge Trees plugin

8. Under the Merge Tree Configuration section, double-click the blank box under Server Group and select Directory 1 from the drop-down menu.

9. Under the Merge Tree Configuration section, double-click the blank box under DN of Tree to merge and enter the DN(s) of the tree(s) in Directory 1 that you'd like to have merged into the VDS (e.g. cn=AllUsers,dc=company,dc=com).

10. Repeat steps 8 & 9 for Directory 2.

11. Under the Merge Tree Configuration section, enter the DN for your new VDS in the Joined Tree DN text box. This will be the DN that contains all of your users from both Directory 1 and 2 that you have decided to merge in steps 8-10 above. This will also be the Base DN you specify when configuring a LDAP browser or application to connect to the VDS.

12. Under the Condition section, enter the DN for your new VDS in the BaseDN text box. Note that this DN should be identical to the Joined Tree DN specified in the step above.

13. Click the OK button near the top of the application to save the Processing Configuration.

6 Listener Configuration

1. Click on the Input button on the left-hand side of the application and the following will appear:

   
   
   Fig-11: Click on the Input node to add a Listener

2. Click on the New Listener button near the bottom of the screen.

3. Enter Merge Users for the new input / listener and then click the Okay button.

4. Click on the listener=Merge Users button on the left-hand side of the screen and the following will appear:

   
   
   Fig-12: Configure the new Listener

5. Under the Main Listener Properties tab, make sure the Protocol is set to ldap.

6. Under the Main Listener Properties tab, set the port to 3890.

7. Under the Main Listener Properties tab, select Directory 1 from the dropdown box to the right of Default Server Group.

8. Click on the Attached Stages tab and the following will appear:

   
   
   Fig-13: Attach the Processing Stages to the Listener

9. Double-click where it shows to do so and click on "stage=Merge Users" in the dropdown box.

10. Click the OK button near the top of the screen to save the Listener configuration.

7 Save Configuration

When you created the new configuration you were prompted to enter a filename for your configuration. The file type for this file is ldif. The configuration must be saved before the VDS can be launched for the first time. Also, the configuration must be saved and the VDS re-launched before changes to the configuration will take effect.

1. Click on the File button on the menu bar.

2. Click Save and your configuration will then be ready to launch.

8 Launch and Test Configuration

1. Click the Process button on the menu bar.

2. Click Run on the drop-down menu. At this point the VDS is running and is ready to accept LDAP requests.

3. Click the Extras button on the menu bar.

4. Click LDAP Browser on the drop-down menu and the following will appear:

   
   
   Fig-14: Use the LDAP Browser to connect to your running Virtual Directory Server instance

5. In the Name textbox, enter Merge Users.

6. In the Hostname textbox, enter the IP Address of the computer that VDS is installed on.

7. In the Port textbox, enter 3890.

8. In the Root Suffix textbox, enter the Joined Tree DN you specified during the Processing Configuration section of this tutorial.

9. In the Bind DN textbox, enter the DN of the user that has appropriate access Root Suffix / Joined Tree DN in the step above.

10. Enter the Password twice for the user specified in the step above.

11. Click the Test button to verify that you can properly bind to the Joined Tree DN.

12. Assuming you entered the correct information, a Test Successful! message will appear. Click the OK button.

13. Click the OK button on the next page and you will be asked if you would like to save Merge Users. Click the Yes button and the Joined Tree DN you specified will appear.

14. You can now browse the newly created branch and verify that users from both Directory 1 and 2 are included in the branch.

    
    
    Fig-15: You can see the Virtual DN displays users from both servers

Tutorial #2 - Fragmented Identities

Tutorial #2 - Fragmented Identities

1 Overview

Many organizations have multiple Identity Stores (including LDAP directories, relational databases and other repositories), each of which contain fragments of identity data. This distribution of data is problematic for applications that need to access identity information for authorization, verification or other reasons.

Virtual Directory Server can solve this issue by providing a unified view of the fragmented identities, effectively collecting all the pieces from the different Identity Stores and presenting them as a single identity to multiple applications. This is done using the "Join" module that comes with Virtual Directory Server (see the Processing Configuration section below).

In our tutorial, we will assume that our organization has two separate directories containing different information about our users. In Directory 1 is information required to authenticate users, while in Directory 2 there is contact information about the users. Our new intranet application requires a single datastore against which it can authenticate users, but against which it is also able to query contact information for users within the organization. We will set up a Virtual Directory Server instance that will join the information from the separate data repositories, so that the intranet application can access all of this information in a single place.

2 Assumptions

1. Virtual Directory Server is installed and configured properly; VDS is currently running.

2. Directory 1 and 2 are installed and accessible from the computer on which VDS is installed.

3. Multiple users exist in both directories and share a common attribute value.

4. Both directories are accessible on port 389 (default ldap port)

5. You have a good understanding of the DIT structure of your directories.

6. Port 3890 is available on the computer in which Virtual Directory Server is installed.

3 Create a New Configuration

1. Click File on the menu bar, then click New.

2. Click the OK button when asked which server you want to create the new configuration in (the default server is Local.

3. Enter JoinTutorial for the filename when prompted, then click the Save button and the following will appear:

   
   
   Fig-1: Create a new configuration

4 Server Group Configuration

Server Groups are the directories and / or databases where your user information is stored. Examples include Active Directory, Sun Directory Server and Oracle database. For this tutorial we will be creating two Server Groups, one for Directory 1 and another for Directory 2.

4.1 Add Directory 1

1. Click on the Output node in the navigator tree on the left-hand side of the application.

2. Click on the New Server Group button near the bottom of the screen.

3. Enter Directory 1 for your new Server Group and leave the Server Group Type as Automatic and then click the Okay button.

4. Click on the Directory 1 node in the navigator tree on the left-hand side of the screen and the following will appear:

   
   
   Fig-2: Configure the first Server Group

5. Verify that the Protocol is set to ldap.

6. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 1.

7. Click on the Connection Pooling tab and check the Use Connection Pooling checkbox. The following will appear:

   
   
   Fig-3: Configure the Connection Pooling for the first Server Group

8. Click on the Use Fixed Credentials radio button then enter the Bind DN and Password for the user that has appropriate access to Directory 1.

9. Change the number of Pool Connections from 10 to 2.

10. Click the OK button near the top of the application to save the Directory 1 Server Group Configuration.

4.2 Add Directory 2

1. Click on the Output node in the navigator tree on the left-hand side of the application and the following will appear:

   
   
   Fig-4: Click on the Output node

2. Click on the New Server Group button near the bottom of the screen.

3. Enter Directory 2 for your new Server Group and leave the Server Group Type as Automatic and then click the Okay button.

4. Click on the Directory 2 node in the navigator tree on the left-hand side of the screen and the following will appear:

   
   
   Fig-5: Configure the second Server Group

5. Verify that the Protocol is set to ldap.

6. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 2.

7. Click on the Connection Pooling tab and check the Use Connection Pooling checkbox. The following will appear:

   
   
   Fig-6: Configure the Connection Pooling for the second Server Group

8. Click on the Use Fixed Credentials radio button then enter the Bind DN and Password for the user that has appropriate access to Directory 2.

9. Change the number of Pool Connections from 10 to 2.

10. Click the OK button near the top of the application to save the Directory 2, Server Group Configuration.

5 Processing Configuration

In this tutorial we will be implementing a single Stage. This stage is going to utilize a default plugin that will merge users from two directories into one virtual directory. This plugin is called the Join Trees default plugin and is provided by the VDS to allow you to quickly and easily implement the functionality that you're looking for.

The Join module uses one attribute as the "join key" in order to match entries across different Identity Stores. This join key is an attribute that is used as the common link between several identities from multiple Identity Stores. The join key attribute values must be unique in every repository to ensure that the joins occur successfully.

1. Click on the Processing node in the navigator tree on the left-hand side of the application and the following will appear:

   
   
   Fig-7: Click on the Processing node

2. Click on the New Stage button near the bottom of the screen.

3. Enter Join Users as the name of the new stage and leave the stage type as Automatic and then click the Okay button.

4. Click on the stage=Join Users node in the navigator tree on the left-hand side of the screen.

5. Click on the Add Plugin button and the following will appear:

   
   
   Fig-8: Add the Join Entries plugin

6. Scroll to the bottom of the list, click on Join Entries and click the OK button.

7. Click the JoinEntries node in the navigator tree on the left-hand side of the screen and the following will appear:

   
   
   Fig-9: Configure the Join Entries plugin

8. Under the Condition section, enter the DN for your new VDS in the Base DN text box. This will be the DN that contains all of the attributes for your users that exist in Directory 1 and 2. This will also be the Base DN you specify when configuring a LDAP browser or application to connect to the VDS.

9. Under the Join Entries Main Configuration section, enter an attribute in the Primary Join Attribute textbox. In our example, we know that the uid attribute is commonly used in both Directories. This means that we can use this attribute to join our two datastores.

10. Under the Join Entries Main Configuration section, uncheck the checkbox if the attribute is not part of the RDN otherwise leave it checked (default).

11. Click the OK button near the top of the screen to save the Main Entry configuration.

12. Click on the New Foreign Data Group button and enter Directory 2 for the name of the new foreign data group then click the OK button.

13. Click on Directory 2 on the left-hand side of the screen and the following will appear:

    
    
    Fig-10: Configure the Foreign Data Group

14. Enter the appropriate attribute in the Primary Key Attribute: section. In our case, we are joining the data based on the uid which we know is common in both Directories.

15. Uncheck the checkbox if the Primary Key Attribute is not part of the RDN otherwise leave it checked (default).

16. Click on Directory 2 in the dropdown box when asked which Server Group the information should be fetched from.

17. Enter the Base DN where information should be fetched from.

18. Click the OK button near the top of the screen to save the Foreign Data Group configuration.

6 Listener Configuration

1. Click on the Input node in the navigator tree on the left-hand side of the application and the following will appear:

   
   
   Fig-11: Click on the Input node

2. Click on the New Listener button near the bottom of the screen.

3. Enter Join Users for the new input / listener and then click the Okay button.

4. Click on the listener=Join Users node in the navigator tree on the left-hand side of the screen and the following will appear:

   
   
   Fig-12: Configure the Listener

5. Under the Main Listener Properties tab, make sure the Protocol is set to ldap.

6. Under the Main Listener Properties tab, set the port to 3890.

7. Under the Main Listener Properties tab, set the Default Server Group to Directory 1 by selecting it from the dropdown box.

8. Click on the Attached Stages tab.

9. Double-click where it shows to do so and click on stage=Join Users in the dropdown box.

   
   
   Fig-13: Attach the Processing Stage to the Listener

10. Click the OK button near the top of the screen to save the Listener configuration.

7 Save Configuration

When you created the new configuration you were prompted to enter a filename for your configuration. The file type for this file is ldif. The configuration must be saved before the VDS can be launched for the first time. Also, the configuration must be saved and the VDS re-launched before changes to the configuration will take effect.

1. Click on the File button on the menu bar.

2. Click Save and your configuration will then be ready to launch.

8 Launch and Test Configuration

1. Click the Process button on the menu bar.

2. Click Run on the drop-down menu. At this point the VDS is running and is ready to accept LDAP requests.

3. Click the Extras button on the menu bar.

4. Click LDAP Browser on the drop-down menu and the following will appear:

   
   
   Fig-14: Use the LDAP Browser to test the running VDS instance

5. In the Name textbox, enter Join Users.

6. In the Hostname textbox, enter the IP Address of the computer that VDS is installed on.

7. In the Port textbox, enter 3890.

8. In the Root Suffix textbox, enter the Base DN from the Condition section of the Main Entry Configuration you specified during the Processing Configuration section of this tutorial.

9. In the Bind DN textbox, enter the DN of the user that has appropriate access to the Root Suffix / Bind DN in the step above.

10. Enter the Password twice for the user specified in the step above.

11. Click the Test button to verify that you can properly bind to the Bind DN.

12. Assuming you entered the correct information, a Test Successful! message will appear. Click the OK button.

13. Click the OK button on the next page and you will be asked if you would like to save Join Users. Click the Yes button and the Bind DN you specified will appear.

14. You can now browse the newly created branch and verify that attributes of users from both Directory 1 and 2 are included in the branch.

    In our example, Directory 2 contained contact information including Address and Email data, while Directory 1 was used primarily as an authentication database. In the image below, you can see that the VDS instance is displaying Address information from Directory 2, along with the data stored in Directory 1. Most significantly, you will notice two mail addresses listed. This is because a mail entry existed in both repositories. The Directory 1 entry has precedence.

    
    
    Fig-15: Data from the two Directories has been merged into a single entry using VDS

Tutorial #3 - Integrating RDBMS into an LDAP Environment

1 Overview

In the previous tutorial, we noted that organizations may store user data in multiple repositories. Up until now, we have assumed that these repositories are of the same type, using the same protocol and nomenclature. However, things become a little more complicated when data is stored in different repository types. For instance, imagine a situation where a web application stores data in a relational database, while the rest of your applications query an LDAP directory like Active Directory. It is not implausible that you would like applications that query your Active Directory to also be able to access information in a relational database.

In this tutorial, we will assume that our organization has a single LDAP directory containing some information about our users, while a MySQL database is used to contain further information about users that is accessible via a web interface. For now, we will simply work toward providing a means for LDAP-ready applications to access data within the MySQL database used by our web application. This is easily achieved using Virtual Directory Server.

2 Assumptions

1. Virtual Directory Server is installed and configured properly; VDS is currently running.

2. An LDAP directory such as Active Directory is already installed and accessible from the computer on which Virtual Directory Server is installed.

3. A MySQL database server is already installed and accessible from the computer on which VDS is installed.

4. A MySQL database called "test" has been created, and contains a table called "users" with a schema that contains the following items:
   
   `uid` varchar(25) NOT NULL,

`password` varchar(40) NOT NULL,

`Title` varchar(255) default '',

`FirstName` varchar(255) default '',

`LastName` varchar(255) default '',

`Company` varchar(255) default '',

`EmailDisplayName` varchar(255) default '',

`EmailAddress` varchar(255) default ''



5. The MySQL table called "users" is populated with at least one entry.Select the table and a naming attribute

6. The LDAP directory is accessible on port 389 (default ldap port) and the MySQL server is accessible on port 3306 (default mysql port).

7. Port 3890 is available on the computer in which Virtual Directory Server is installed.

3 Create a New Configuration

1. Click File on the menu bar, then click New.

2. Click the OK button to create a Local configuration.

3. Enter RDBMSTutorial for the filename when prompted, then click the Save button and the following will appear:

   
   
   Fig-1: Create a new configuration

4 Server Group Configuration

Server Groups are the directories and / or databases where your user information is stored. For this tutorial we will be creating two Server Groups, one for our LDAP Directory (Directory 1) and another for our MySQL database (RDBMS).

4.1 Add Directory 1

1. Click on the Output node in the navigator tree on the left-hand side of the application.

2. Click on the New Server Group button near the bottom of the screen.

3. Enter Directory 1 for your new Server Group and leave the Server Group Type as Automatic and then click the OK button.

4. Click on the Directory 1 node in the navigator tree on the left-hand side of the screen and the following will appear:

   
   
   Fig-2: Configure the first Server Group

5. Verify that the Protocol is set to ldap.

6. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 1.

7. Click the OK button near the top of the application to save the Directory 1 Server Group Configuration.

4.2 Add the RDBMS Server Group

1. Click on the Output node in the navigator tree on the left-hand side of the application and the following will appear:

   
   
   Fig-3: Click on the Output node

2. Click on the "New database connection" button near the bottom of the screen to open the Database Wizard.

3. Select the appropriate driver for your database. In this example we will be using the MySQL driver. Note, that in order to use the wizard, you will need to copy the driver files into the appropriate directory for your installation, as explained in the user guide.

   
   
   Fig-4: Select the appropriate database driver

4. Enter the connection details to access the backend database. Note that the options that appear here will differ depending on the driver that you are using.

   
   
   Fig-5: Enter connection details

5. Provide a mount point DN that will be used to access the data from the database table within the LDAP tree. Usually, the DN that you enter here will appear as a node within the tree presented by your default ServerGroup, or Virtual Tree.

   
   
   Fig-6: Enter a mount point DN for the table data

6. Select the table that you wish to append to the LDAP tree, and choose a field to be used as the naming attribute within the branch. You also have the option to choose a password attribute here if you wish to perform LDAP authentication against data held within the database table.

   
   
   Fig-7: Select the table and a naming attribute

7. Finally, provide an RDN for the table. Usually the default tablename as an organizational unit should be sufficient. And click Next to view the final configuration, where you will be able to exit out of the wizard.

   
   
   Fig-8: Choose an RDN for the table

8. When you have completed the wizard, you will find that a new servergroup has been added to your configuration and that it looks something like this:
   
   

   
   
   Fig-9: RDBMS Servergroup configuration screen
   
   

9. Click the OK button near the top of the application to save the RDBMS Server Group Configuration.

5 Processing Configuration

In this tutorial we will be implementing a single Stage. This stage is going to utilize a default plugin that will make it possible to see the virtual RDBMS tree mapping in an LDAP browser. This plugin is called the Add Entries plugin.

1. Click on the Processing node in the navigator tree on the left-hand side of the application and the following will appear:

   
   
   Fig-10: Click on the Processing node

2. Click on the New Stage button near the bottom of the screen.

3. Enter Add Entry as the name of the new stage and leave the stage type as Automatic and then click the Okay button.

4. Click on the stage=Add Entry node in the navigator tree on the left-hand side of the screen.

5. Click on the Add Plugin button and the following will appear:

   
   
   Fig-11: Select the Add Entries plugin

6. Scroll to the bottom of the list, click on Add Entries and click the OK button.

7. Click the AddEntries node in the navigator tree on the left-hand side of the screen.

8. Click the New Virtual Entry button near the bottom of the screen, and enter "db" in the dialog that pops up.

9. Click on the "db" node in the navigator tree on the left of the screen.

10. In the Entry DN field, enter the DN that you have used to attach your RDBM data, in the Destination Tree field earlier.

    
    
    Fig-12: Configure the db Entry in the Add Entries plugin

11. You will now need to provide some attributes for the virtual DN that you are creating. In the Attribute Type column of the table, create an attribute type called "objectclass". In the Attribute Values column, enter a value of "top" and a second value of "organizationalunit".

12. Create a second Attribute type called "ou" and assign it the value "db".

6 Listener Configuration

1. Click on the Input node in the navigator tree on the left-hand side of the application and the following will appear:

   
   
   Fig-13: Click on the Input node

2. Click on the New Listener button near the bottom of the screen.

3. Enter RDBMS Listener for the new input / listener and then click the OK button.

4. Click on the listener=RDBMS Listener node in the navigator tree on the left-hand side of the screen and the following will appear:

   
   
   Fig-14: Configure the Listener

5. Under the Main Listener Properties tab, make sure the Protocol is set to ldap.

6. Under the Main Listener Properties tab, set the port to 3890.

7. Under the Main Listener Properties tab, set the Default Server Group to Directory 1 by selecting it from the dropdown box.

8. Click on the Attached Stages tab.

9. Double-click where it shows to do so and click on stage=Add Entry in the dropdown box.

   
   
   Fig-15: Attach the Processing Stage to the Listener

10. Click the OK button near the top of the screen to save the Listener configuration.

7 Save Configuration

When you created the new configuration you were prompted to enter a filename for your configuration. The file type for this file is ldif. The configuration must be saved before the VDS can be launched for the first time. Also, the configuration must be saved and the VDS re-launched before changes to the configuration will take effect.

1. Click on the File button on the menu bar.

2. Click Save and your configuration will then be ready to launch.

8 Launch and Test Configuration

1. Click the Process button on the menu bar.

2. Click Run on the drop-down menu. At this point the Virtual Directory Server is running and is ready to accept LDAP requests.

3. Click the Extras button on the menu bar.

4. Click LDAP Browser on the drop-down menu and the following will appear:

   
   
   Fig-16: Use the LDAP Browser to test the running Virtual Directory Server instance

5. In the Name textbox, enter RDBMS Tutorial.

6. In the Hostname textbox, enter the IP Address of the computer that VDS is installed on.

7. In the Port textbox, enter 3890.

8. In the Root Suffix textbox, enter the Base DN of your LDAP Directory.

9. In the Bind DN textbox, enter the DN of the user that has appropriate access to the Root Suffix / Bind DN in the step above.

10. Enter the Password twice for the user specified in the step above.

11. Click the Test button to verify that you can properly bind to the Bind DN.

12. Assuming you entered the correct information, a Test Successful! message will appear. Click the OK button.

13. Click the OK button on the next page and you will be asked if you would like to save RDBMS Tutorial. Click the Yes button and the Bind DN you specified will appear.

14. You can now browse the your LDAP Directory as usual, however you will notice a new tree with the RDN "ou=db" attached to your Directory. This is visible thanks to the Add Entries plugin.

    Browsing down the ou=db tree, you will discover that you are able to view data within your MySQL database inside of the LDAP tree.

    
    
    Fig-17: Data from the MySQL database is visible in the LDAP tree using VDS

A final note about using Relational Databases within VDS as backend repositories. Unlike most directory servers, Relational Databases do not often follow standardized schemas. This means that LDAP applications that are very schema-specific may have trouble relating to the attribute types returned by VDS on behalf of a relational database. This is not so much a problem with the implementation of VDS as the data is returned accurately, but is more of a problem with the non-standard way that browsers and some other LDAP applications relate to schemas. Ideally, a browser should not perform any schema checking, as this not only slows down the browser but also results in limitations of the browser itself. However, we do not live in a perfect world, if you find that your LDAP applications are not working properly with your relational database, you may find that you need to redefine your table schema to conform to an LDAP schema or that you need to perform some complex attribute mapping.

Tutorial #4 - Integrating an RDBMs Into an LDAP Tree

Tutorial #4 - Integrating an RDBMS Into an LDAP Tree

1 Overview

Building on the previous Virtual Directory Server tutorials, we will now try to build a complex solution based on a fairly difficult use-case scenario. We will begin by assuming that our organization has user data stored within an RDBMS and that the organization also stores user data within an LDAP directory. To make matters more complicated, a certain amount of the data stored in the RDBMS overlaps with the data stored in the LDAP directory. Finally, the data is stored in the RDBMS in a way in which the field names (or attribute types) do not correlate with the schema used within the LDAP directory. When users change their details using Directory tools, the changes should also be reflected in the RDBMS, so that the organization's web-based intranet application continues to function properly. Furthermore, when the RDBMS is updated via the web application, you want these changes to be reflected in the Directory. Not surprisingly, this is a common problem for many organizations. By using the information provided in the previous tutorials, we should be able to create a solution using Virtual Directory Server to merge all of this data so that it works in a relatively seamless way.

In our tutorial, we will assume that our organization has a single LDAP directory containing some information about our users, while a MySQL database is used to contain information about users that is accessible via a web interface. Using the configuration from the previous tutorial, we will now use the Join Entries plugin and the Map Attributes plugin to make the data in the MySQL database visible to applications that are currently accessing a particular tree in the LDAP server. In this way, LDAP applications will be able to update data within the RDBMS, and will be able to present changes to the RDBMS as if these changes had been made within the LDAP directory.

2 Assumptions

1. Virtual Directory Server is installed and configured properly; VDS is currently running.

2. An LDAP Directory is installed and accessible from the computer on which Virtual Directory Server is installed.

3. A MySQL database is installed, configured, and accessible from the computer on which Virtual Directory Server is installed.

4. The configuration from Tutorial 3 (Integrating RDBMS into an LDAP Environment) has been completed and is available for modification.

5. Port 3890 is available on the computer in which Virtual Directory Server is installed.

3 Open the Existing Configuration from Tutorial 3

1. Click File on the menu bar, then click Open, and then click on Open Local Config.

2. Click on RDBMSTutorial in the local configuration menu, and then click on the Open Config button

3. The configuration from the previous tutorial should be loaded and you will be able to begin editing the configuration.

   
   
   Fig-1: Open the RDBMSTutorial configuration

4 Add Processing Stages

At this point, our configuration is already capable of integrating an RDBMS and LDAP directory into a single environment presented as an LDAP server accessible on port 3890 of the local server. In the previous tutorial, we created a Processing Stage to host the Add Entries plugin, so that data from the RDBMS would be visible to LDAP browsers. Now, we will add two further Processing Stages that will host the Join Entries plugin and the Map Attributes plugin, so that we can present the data within a single tree that follows the schema already being used by the LDAP server. In this way, LDAP applications will be able to access and update information stored in the RDBMS as if it was part of the expected LDAP environment.

4.1 Add Join Entries stage

The Join Entries module uses one attribute as the "join key" in order to match entries across different Identity Stores. This join key is an attribute that is used as the common link between several identities from multiple Identity Stores. The join key attribute values must be unique in every repository to ensure that the joins occur successfully.

1. Click on the Processing node in the navigator tree on the left-hand side of the application and the following will appear:

   
   
   Fig-2: Click on the Processing node

2. Click on the New Stage button near the bottom of the screen.

3. Enter Join Entries as the name of the new stage and leave the stage type as Automatic and then click the Okay button.

4. Click on the stage=Join Entries node in the navigator tree on the left-hand side of the screen.

5. Click on the Add Plugin button and the following will appear:

   
   
   Fig-3: Add the Join Entries plugin

6. Scroll to the bottom of the list, click on Join Entries and click the OK button.

7. Click the JoinEntries node in the navigator tree on the left-hand side of the screen and the following will appear:

   
   
   Fig-4: Configure the Join Entries plugin

8. Under the Condition section, enter the DN that is used to store user data, in your LDAP Directory, in the Base DN text box. We will join data from the MySQL database into this DN, so that although the data presented will be a combination from both repositories, your LDAP applications will relate to the data as if it has come only from the LDAP repository. The Join will only be applied when any application makes a request for this DN.

9. Under the Join Entries Main Configuration section, enter an attribute in the Primary Join Attribute textbox. In our example, we know that the uid attribute is commonly used in both Directories. This means that we can use this attribute to join our two datastores. You are able to use two differently named attributes to perform the join on, in this field, you would enter the attribute name for the attribute in the LDAP directory that we are joining MySQL data to.

10. Under the Join Entries Main Configuration section, uncheck the checkbox if the attribute is not part of the RDN otherwise leave it checked (default).

11. In the Aggregated Attributes list, enter the 'mail' attribute on one line, so that it is possible to have multiple email addresses stored either in LDAP or in the MySQL database.

12. Click the OK button near the top of the screen to save the Main Entry configuration.

13. Click on the New Foreign Data Group button and enter RDBMS for the name of the new foreign data group then click the OK button.

14. Click on RDBMS on the left-hand side of the screen and the following will appear:

    
    
    Fig-5: Configure the Foreign Data Group

15. Enter the appropriate attribute in the Primary Key Attribute: section. In our case, we are joining the data based on the uid which we know is common in both Directories. If the attribute is named differently, you would enter the name of the attribute in the MySQL database that we will use to perform the join against.

16. Uncheck the checkbox if the Primary Key Attribute is not part of the RDN otherwise leave it checked (default). Note that in order to be able to perform ADD writes to the joined server groups, the Primary Key Attribute must also be used for the RDN.

17. Click on RDBMS in the dropdown box when asked which Server Group the information should be fetched from.

18. Enter the Base DN where information should be fetched from. In our example, this would be from: ou=users,ou=MYSQL,dc=my_organization,dc=com.

19. Because we are writing data across two different environments, it is worthwhile specifying which attributes should be written to the database. Click on the WRITE Operation Paramaters tab.

20. Ensure that all of the different WRITE operations are enabled, and select the option to include only the following attributes for all WRITE operations. In the list, we will specify the attributes that we wish to use within the database. Because we intend to use attribute mapping to resolve the differences in schemas, we can choose to use the attributes from our LDAP schema, that we intend to map onto the database schema.

    
    
    Fig-6: Configure the WRITE options

21. In our example, the attributes that we wish to copy into the database are as follows:

    uid

    mail

    userpassword

    company

    displayname

    givenname

    sn

22. Click the OK button near the top of the screen to save the Foreign Data Group configuration.

4.2 Add Map Attributes Stage

The Map Attributes module is able to map attributes from one identity store onto attribute types for another identity store. Effectively, you are able to define alias attributes on the fly, so that column/field names from your MySQL database appear to follow the schema used by your LDAP server.

1. Click on the Processing node in the navigator tree on the left-hand side of the application and the following will appear:

   
   
   Fig-7: Click on the Processing node

2. Click on the New Stage button near the bottom of the screen.

3. Enter Map Attributes as the name of the new stage and leave the stage type as Automatic and then click the OK button.

4. Click on the stage=Map Attributes node in the navigator tree on the left-hand side of the screen.

5. Click on the Add Plugin button and the following will appear:

   
   
   Fig-8: Add the Map Attributes plugin

6. Scroll through the list in the plugin dialog, click on Map Attributes and click the OK button.

7. Click the MapAttributes node in the navigator tree on the left-hand side of the screen and the following will appear:

   
   
   Fig-9: Configure the Map Attributes plugin

8. Under the Condition section, enter the DN used to access the data in the database into the Base DN text box. Although there is a note on the GUI warning you not to enter a Base DN in the conditions section of the configuration, if you are doing attribute mapping from the server to the client, it is important that you ignore this, for this configuration, as the schemas from the Join are likely to conflict so heavily.

9. Under the Attribute Mapping Configuration section, we will need to define attribute mappings that work both ways (from client to server and vice versa). On the Attribute (server) side of the table, we will list the names of fields within our MySQL table. On the Attribute (client) side of the table, we will list the LDAP attributes that these fields will map onto.

   In our example, the table will end up looking something like this:

   EmailDisplayName	<-->	displayname
   password	<-->	userpassword
   FirstName	<-->	cn
   LastName	<-->	sn
   EmailAddress	<-->	mail

10. Click the OK button to save the changes.

5 Listener Configuration

1. Expand the Input node in the navigator tree on the left of the GUI; and click on listener=RDBMS Listener. The listener should be mostly configured from the previous tutorial.

   
   
   Fig-11: Click on the RDBMS Listener

2. Click on the Attached Stages tab.

3. Beneath the stage=Add Entry, double-click where it shows to do so and click on stage=Join Entry in the dropdown box. Repeat the step to add the stage= Map Attributes option to the stages pipeline.

   
   
   Fig-13: Attach the Processing Stages to the Listener

4. Click the OK button near the top of the screen to save the Listener configuration.

6 Save Configuration

Before you attempt to run the configuration, you will need to save all of the changes to file. To do this, follow the instructions below.

1. Click on the File button on the menu bar.

2. Click Save and your configuration will then be ready to launch.

7 Launch and Test Configuration

While Symlabs Virtual Directory Server comes with its own built-in LDAP browser, this browser is not adequate for WRITE testing in an LDAP environment. For this tutorial, we will use JXplorer, a 3rd Party LDAP Browser, to test our configuration properly. You can use an alternative browser for your own purposes, or install JXplorer according to the instructions provided on the JXplorer website. To begin with, we will need to start our configuration, so that we are able to access the data from both repositories.

1. Click the Process button on the menu bar.

2. Click Run on the drop-down menu. At this point the Virtual Directory Server is running and is ready to accept LDAP requests.

3. Open JXplorer, or an alternative LDAP browser, and configure it to connect to our VDS instance:

   
   
   Fig-12: Configure JXplorer to connect to the VDS instance

4. Connect to the VDS instance and expand the People DN in the navigation tree.

5. A list of users that are on the LDAP server should now be available. Details for any users that also exist in the MySQL database will be available to view for any user.

   
   
   Fig-13: Expand the People DN

6. Right click on the People node in the navigation tree, and select the New option from the dialog.

   Enter and RDN with uid=testuser in the Enter RDN field, and ensure that the inetOrgPerson, organizationalPerson, person and top Classes are selected. Click OK.

   
   
   Fig-14: Add a test user to the directory.

7. Assign compulsory values, such as the cn and sn attributes. And add values for the displayname, givenname and mail attributes. Click Submit.

8. If you have correctly configured your VDS instance, an entry for testuser should appear in your MySQL database as well as in your LDAP directory. Note that users already existing in the LDAP directory will not exist within the MySQL database automatically. However, once added, any changes made to the directory in VDS will be reflected in the MySQL database. In our current configuration, it is important to note that we have allowed the data in the LDAP directory to have precedence. This means that changes to the database will only be reflected in the VDS directory if no data already exists for the user in the LDAP directory. The order of precedence can easily be changed in the configuration, by clicking on the Join Entries node in the navigation panel of DSGUI, and shuffling the Order of Precedence on the Main Parameters tab.

   
   
   Fig-15: The user will appear in the DB node, which represents data stored in the MySQL database.

   We have also allowed for the mail attribute to be aggregated. This means that if the user changes the EmailAddress in the MySQL database, our VDS directory will provide the address stored in the LDAP directory, along with the Email address in the MySQL database.

Tutorial #5 - Working with Remote Configurations

Tutorial #5 - Working with Remote Configurations

1 Overview

Symlabs Virtual Directory Server (VDS) provides the option of working directly with remote configurations within a GUI environment on a local system. This facility is made available through the Remote Administration Server, a separate daemon or service that runs on the host system and is capable of interacting directly with configuration files on the server, as well as being able to initiate or stop a Virtual Directory Server instance. With some basic setup steps, it is possible for an administrator to work directly on a Virtual Directory Server host remotely, without requiring direct access to the host system. This provides a number of benefits to any enterprise environment. Firstly, it provides an additional layer of security in that administrators responsible for the maintenance of the VDS instance, do not need to be provisioned with any other form of access to the host system. Secondly, it massively eases configuration and maintenance tasks in environments where there are multiple Virtual Directory Server instances running, as the administrator only needs to open the GUI on his or her local system and connect to the VDS host that needs to be configured. Finally, and perhaps most importantly, systems running RAS do not need to have a graphical display available in order to configure and manage them. For Unix environments in particular, production servers rarely have an X server or windows environment installed. This helps to improve security and reduce unnecessary load on a production system. Using the RAS allows administrators to configure and manage Virtual Directory Server instances with the convenience of a GUI without requiring a windows environment to be loaded on the VDS host.

This tutorial will set out to explain how to configure the Remote Administration Server (RAS) on a host, how to start it, and how to connect to it using a locally installed graphical user interface. Once the host is accessible via RAS, an administrator should be able to configure the Virtual Directory Server instance on the remote host as if it were a local configuration. At this point, any of the other tutorials (or customized configurations) can be followed with the only variation being that the configuration will be created or edited remotely.

2 Assumptions

1. Virtual Directory Server is installed and configured properly; VDS is currently running.

2. The Administrator following this tutorial has access to the system that will run the VDS instance (from now on, referred to as the Remote VDS Host).

3. The Administrator has installed the Virtual Directory Server GUI on a separate system that has network access to the Remote VDS Host. This system will be referred to from now on as the Local VDS Controller.

4. Port 9443 is available on the Remote Virtual Directory Server Host.

5. The Local VDS Controller is able to communicate with the Remote VDS Host on port 9443 (i.e. there are no firewall restrictions for this port).

3 Connect to the Remote Virtual Directory Server Host and Configure RAS

Depending on the Operating System that the Remote Virtual Directory Server Host is using, you will need to determine how best to access the Remote Virtual Directory Server Host. For Microsoft Windows environments, this might be done using Terminal Services. Unix and Linux environments can be accessed using SSH. Alternatively, you may find it easier to work directly on the Remote Virtual Directory Server Host locally, to perform the initial RAS configuration. In this section, we will assume that regardless of the Operating System, you are able to access the system and perform the tasks required.

1. The RAS configuration parameters are stored in an LDIF file within the admrem folder or subdirectory within the root folder for the VDS installation. On Windows, this is likely to be in the path C:\Program Files\Symlabs\DE\R4.0.0. While on Unix and Linux platforms, this is likely to be in the path, /opt/ds/std/.

   Using your preferred editor, open the file named admconf.ldif in the admrem directory.

2. Within this file, regardless of the Operating System, are the following lines:

   dn: cn=administrator,o=dsproxyremote
   
   user: demanager
   
   passwd: admin123

3. The user and passwd lines specify the credentials that are used to access the RAS instance. In production environments, we highly recommend that you change the user and password credentials for the RAS service, as this facility allows full control of any VDS instance running on the Remote VDS Host. In our example tutorial we will only change the passwd value, and we will set it to 'symlabs123'.

4. Save the edited admconf.ldif file, and close it.

4 Start the RAS service on the Remote VDS Host

The RAS service will essentially run as its own unique Virtual Directory Server instance and will intercept requests from the Local VDS Controller that are directed to port 9443, and will act on them as required. Incidentally, it is possible to run the RAS service on a different port, by editing the admRemServer.ldif configuration file (also within the admrem folder in the root of your installation). However, we do not recommend that you edit this file unless absolutely necessary.

Now that the RAS service has been configured, you will need to start it on the Remote VDS Host.

1. Start the RAS service.
   
   

   In Windows environments you can now start the RAS service by running the RAS Monitor will be listed in the Start menu (under Symlabs > DE > VDS > R4.5.0). When the RAS Monitor is started for the first time, the RAS Service will be registered as a regular Windows Service with the name "Symlabs DE VDS RAS" and can be controlled either using the RAS Monitor applet, or by using the Windows Services environment. Right clicking on the RAS Monitor applet will present you with a menu that will allow you to control the RAS service.
   
   
   
   
   
   
   
   Fig-1: The Windows RAS Monitor.

   
   
   The Windows RAS Monitor directly interacts with a batch script that is responsible for controlling how the RAS system functions. You can alternately start the RAS service by opening a command prompt. Changing to the root directory of your Virtual Directory Server installation (usually, C:\Program Files\Symlabs\VDS\R4.5.0) and typing:

   init-admrem.bat start
   

   For Unix or Linux systems, you can start the RAS service by opening a shell and changing to the root directory of your Virtual Directory Server installation (usually, \opt\ds\std) and typing:

   ./init-admrem start
   

The Remote VDS Host should now be running the RAS service and should be accessible remotely.

5 Configure the Local VDS Controller

Now open the DSGUI application on your Local VDS Controller system. We will configure the GUI to be able to connect to our RAS instance, so that it can be controlled using the local system across the network.

1. Click on File in the File menu at the top of the GUI, and select Preferences from the dropdown menu.

2. In the Preferences dialog, select the Administration Server Preferences option from the navigation panel on the left.

   
   
   Fig-1: Select the Admin Server Preferences option

3. Click on the Add button at the bottom of the screen. In the dialog that pops up, you will need to enter the details for the Remote VDS Host. In the Name field, enter a short name that will be used to reference the remote host (in our example, we have simply called the instance RemoteHost). In the Hostname field, you can enter a hostname that is resolvable by DNS, or simply enter the IP address of the Remote VDS Host. Finally, in the password fields, enter the password that we defined in the RAS configuration file. In this case, we changed it to 'symlabs123'.

   
   
   Fig-2: Define the parameters required to connect to the Remote VDS Host

4. Click the Test button to ensure that you are able to connect to the RAS service. A dialog should pop up to tell you if the connection was successful.

5. Click the OK button.

6. In the Preferences screen, click the OK button at the top of the screen, and then in the File menu at the top of the screen select the option to Save your preferences.

7. Close the Preferences screen.

6 Connect to the Remote Virtual Directory Server Host and Create a New Configuration

You will now be able to connect to the Remote Virtual Directory Server Host that you have defined in your preferences, and create a new configuration.

1. Click on the File button on the menu bar, and select New->New Remote Config. A dialog will pop-up allowing you to select the Remote Virtual Directory Server Host that you have specified in your Preferences. Click OK.

   
   
   Fig-3: Select the Virtual Directory Server Host that you wish to connect to.

2. Provide a filename for your configuration. In our example, we have assigned the name RasTest. Click the New Config button.

   
   
   Fig-4: Create a new remote config.

The configuration will be saved by default in the confs folder in the root of the installation of the VDS software on the Remote VDS Host.

You will now be able to work with this configuration as if you were interacting with a local configuration. Changes will be saved on the Remote VDS Host. Any attempt to start or stop the configuration, will execute the appropriate action on the Remote VDS Host. Logging to STDOUT performed by the configuration will be returned via RAS to the Local VDS Controller to be displayed in the GUI logging window.

Tutorial #1 - Load Balancing

Tutorial #1 - Load Balancing

1 Overview

In this tutorial we will be demonstrating load balancing in a round-robin fashion between two directories, Directory 1 and 2. LDAP requests that come to the LDAP Proxy will be sent in a round-robin fashion first to Directory 1, then to Directory 2, then to Directory 1, then to Directory 2 and so on.

2 Assumptions

1. LDAP Proxy is installed and configured properly; LDAP Proxy is currently running.

2. Directory 1 & 2 are both installed and accessible from the computer on which LDAP Proxy is installed.

3. Both of your directories are populated with users.

4. Directory 1 & 2 are replicating with or are nearly identical to one another.

5. Directory 1 & 2 are both accessible on port 389 (default ldap port)

6. You have a good understanding of the DIT structure of your directories.

7. Port 3890 is available on the computer in which LDAP Proxy is installed.

8. You have the ability to view the proper logs in Directory 1 and 2.

3 Create a New Configuration

1. Click File on the menu bar, then click New.

2. Click the OK button when asked which server you want to create the new configuration on (the default server is Local).

3. Enter LoadBalancingTutorial for the filename when prompted, then click the Save button and the following will appear:

   
   
   Fig-1: LDAP Proxy New configuration

3.1 Server Group Configuration

Server Groups are the directories where your user information is stored. Examples include Active Directory, Sun Directory Server and Oracle Internet Directory. For this tutorial we will be creating one Server Group that contains two directories, Directory 1 and Directory 2.

1. Click on the Output button on the left-hand side of the application and the following will appear:

   
   
   Fig-2: Add a Server Group

2. Click on the New Server Group button near the bottom of the screen.

3. Enter ReplicatedDirectories for your new Server Group and leave the Server Group Type as Automatic and then click the Okay button.

4. Verify that the Protocol is set to ldap.

5. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 1.

6. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 2.

   
   
   Fig-3: Configure the server group

7. Click on the Reliability/Performance tab and click on the Load-Balancing radio button.

   
   
   Fig-4: Enable Load Balancing

8. Click the OK button near the top of the application to save the ReplicatedDirectories Server Group Configuration.

3.2 Listener Configuration

1. Click on the Input button on the left-hand side of the application and the following will appear:

   
   
   Fig-5: Add an LDAP Proxy Listener

2. Click on the New Listener button near the bottom of the screen.

3. Enter LoadBalancing for the new input / listener and then click the Okay button.

4. Click on the listener=LoadBalancing button on the left-hand side of the screen and the following will appear:

   
   
   Fig-6: LDAP Proxy Listener configuration

5. Under the Main Listener Properties tab, make sure the Protocol is set to ldap.

6. Under the Main Listener Properties tab, set the port to 3890.

7. Under the Main Listener Properties tab, select ReplicatedDirectories from the dropdown box to the right of Default Server Group.

8. Click the OK button near the top of the screen to save the Listener configuration.

4 Health Monitoring Configuration

Health Checking is an important feature of Directory Extender. You will need it whenever you are using load-balancing or fail-over in server groups. The principle is simple: LDAP Proxy will periodically check every server by sending simple requests to it. Whenever LDAP Proxy notices that a server has gone down or come back up, the server status will change respectively. LDAP Proxy makes use of this state information for deciding where to send each next request.

1. Click on the Health Monitoring button on the left-hand side of the screen and the following will appear:

   
   
   Fig-7: LDAP Proxy Health monitoring configuration

2. Make sure the Enable Health Checking box is checked and set the Interval to 5 seconds (for testing purposes only).

3. In the Operation for Health Checking section, make sure the BIND radio-button is selected. Set the Timeout to 5 seconds and the Number of Iterations to 3.

4. In the Debug Level section, select Warning, Info and Trace.

5. In the Health Checking Parameters section, enter the appropriate information for the Bind DN and Password fields. These credentials are used to determine if the directories are up and running.

5 Save Configuration

When you created the new configuration you were prompted to enter a filename for your configuration. The file type for this file is ldif. The configuration must be saved before the LDAP Proxy can be launched for the first time. Also, the configuration must be saved and the LDAP Proxy re-launched before changes to the configuration will take effect.

1. Click on the File button on the menu bar.

2. Click Save and your configuration will then be ready to launch.

6 Launch and Test Configuration

1. Click the Process button on the menu bar.

2. Click Run on the drop-down menu. At this point the LDAP Proxy is running and is ready to accept LDAP requests.

   
   
   Fig-8: LDAP Proxy Launch and test configuration

3. Click the Extras button on the menu bar.

4. Click LDAP Browser on the drop-down menu and the following will appear:

   
   
   Fig-9: The LDAP Browser Connection Window

5. In the Name textbox, enter Load Balancing.

6. In the Hostname textbox, enter the IP Address of the computer that LDAP Proxy is installed on.

7. In the Port textbox, enter 3890.

8. In the Root Suffix textbox, enter the DN you'd like to be the root of your LDAP request.

9. In the Bind DN textbox, enter the DN of the user that has appropriate access to both Directory 1 and 2.

10. Enter the Password twice for the user specified in the step above.

11. Click the Test button.

12. Assuming you entered the correct information, a Test Successful! message will appear. Click the OK button. At this point, the LDAP Proxy routed a Bind request to either Directory 1 or 2 which you can verify by viewing the logs for Directory 1 and 2.

13. Click the Test button again.

14. Again, a Test Successful! message will appear. Click the OK button. At this point, the LDAP Proxy routed another Bind request to either Directory 1 or 2. This time however, the Bind request went to the directory that it did not go last time. Again, this can be verified by viewing the logs for Directory 1 and 2.

15. You can continue testing the connection or viewing entries in the LDAP browser and you can verify that the LDAP operations are alternating between the two directories by viewing the logs for Directory 1 and 2.

Tutorial #2 - Fail-over

Tutorial #2 - Fail-over

1 Overview

In this tutorial we will be demonstrating fail-over with fail-back. We have two directories, Directory 1 and 2 that are replicating with one another. Directory 1 is the default which receives all of LDAP requests from the LDAP Proxy until it becomes unavailable. Once Directory 1 becomes unavailable, all LDAP requests get temporarily routed to Directory 2 until Directory 1 goes back online.

2 Assumptions

1. LDAP Proxy is installed and configured properly; LDAP Proxy is currently running.

2. Directory 1 & 2 are both installed and accessible from the computer on which LDAP Proxy is installed.

3. Both of your directories are populated with users.

4. Directory 1 & 2 are replicating with or are nearly identical to one another.

5. Directory 1 & 2 are both accessible on port 389 (default ldap port)

6. You have a good understanding of the DIT structure of your directories.

7. Port 3890 is available on the computer in which LDAP Proxy is installed.

8. You have the ability to view the proper logs in Directory 1 and 2.

3 Create a New Configuration

1. Click File on the menu bar, then click New.

2. Click the OK button when asked which server you want to create the new configuration in (the default server is Local).

3. Enter FailoverTutorial for the filename when prompted, then click the Save button.

3.1 Server Group Configuration

Server Groups are the directories where your user information is stored. Examples include Active Directory, Sun Directory Server and Oracle Internet Directory. For this tutorial we will be creating one Server Group that contains two directories, Directory 1 and Directory 2.

1. Click on the Output button on the left-hand side of the application to begin to configure a servergroup.

2. Click on the New Server Group button near the bottom of the screen.

3. Enter ReplicatedDirectories for your new Server Group and leave the Server Group Type as Automatic and then click the Okay button.

4. Click on the ReplicatedDirectories button on the left-hand side of the screen.

   
   
   Fig-1: Configuring a Server Group in DSGUI

5. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 1.

6. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 2.

7. Click on the Reliability/Performance tab and verify that the Failover radio button is checked.

8. In the Fail-over Algorithm section, verify that the default is selected, First available Server, with Fail-back.

9. Click the OK button near the top of the application to save the ReplicatedDirectories Server Group Configuration.

3.2 Listener Configuration

1. Click on the Input button on the left-hand side of the application.

2. Click on the New Listener button near the bottom of the screen.

3. Enter Failover for the new input / listener and then click the Okay button.

4. Click on the listener=Failover button on the left-hand side of the screen to begin configuring the listener.

   
   
   Fig-2: Configuring a Listener

5. Under the Main Listener Properties tab, make sure the Protocol is set to ldap.

6. Under the Main Listener Properties tab, set the port to 3890.

7. Under the Main Listener Properties tab, select ReplicatedDirectories from the dropdown box to the right of Default Server Group.

8. Click the OK button near the top of the screen to save the Listener configuration.

4 Health Monitoring Configuration

Health Checking is an important feature of Directory Extender. You will need it whenever you are using load-balancing or fail-over in server groups. The principle is simple: LDAP Proxy will periodically check every server by sending simple requests to it. Whenever LDAP Proxy notices that a server has gone down or come back up, the server status will change respectively. LDAP Proxy makes use of this state information for deciding where to send each next request.

1. Click on the Health Monitoring button on the left-hand side of the screen.

2. Make sure the Enable Health Checking box is checked and set the Interval to 5 seconds (for testing purposes only).

3. In the Operation for Health Checking section, make sure the BIND radio-button is selected. Set the Timeout to 5 seconds and the Number of Iterations to 3.

4. In the Debug Level section, select Warning, Info and Trace.

5. In the Health Checking Parameters section, enter the appropriate information for the Bind DN and Password fields. These credentials are used to determine if the directories are up and running.

   
   
   Fig-3: Configure Health Monitoring 6

5 Save Configuration

When you created the new configuration you were prompted to enter a filename for your configuration. The file type for this file is ldif. The configuration must be saved before the LDAP Proxy can be launched for the first time. Also, the configuration must be saved and the LDAP Proxy re-launched before changes to the configuration will take effect.

1. Click on the File button on the menu bar.

2. Click Save and your configuration will then be ready to launch.

6 Launch and Test Configuration

1. Click the Process button on the menu bar.

2. Click Run on the drop-down menu. At this point the LDAP Proxy is running and is ready to accept LDAP requests.

3. Click the Extras button on the menu bar.

4. Click LDAP Browser on the drop-down menu and enter the details required to connect to the listener that you have configured:

   
   
   Fig-4: Enter the details required to connect to the listener

5. In the Name textbox, enter Failover.

6. In the Hostname textbox, enter the IP Address of the computer that LDAP Proxy is installed on.

7. In the Port textbox, enter 3890.

8. In the Root Suffix textbox, enter the DN you'd like to be the root of your LDAP request.

9. In the Bind DN textbox, enter the DN of the user that has appropriate access to both Directory 1 and 2.

10. Enter the Password twice for the user specified in the step above.

11. Click the Test button.

12. Assuming you entered the correct information, a Test Successful! message will appear. Click the OK button. At this point, the LDAP Proxy routed a Bind request to Directory 1 which you can verify by viewing the logs for Directory 1.

13. Click the Test button again.

14. Again, a Test Successful! message will appear. Click the OK button. At this point, the LDAP Proxy routed another Bind request to Directory 1. Again, this can be verified by viewing the logs for Directory 1.

15. Take Directory 1 offline and wait for approximately 1 minute.

16. Click the Test button again.

17. Again, a Test Successful! message will appear. Click the OK button. At this point, the LDAP Proxy routed a Bind request to Directory 2. This can be verified by viewing the logs for Directory 2.

Tutorial #3 - Merging Organizational Units in Active Directory

Tutorial #3 - Merging Active Directory Trees

1 Overview

A common problem faced by users of Active Directory arises when users are stored within the Directory in separate organisational units, and a client application is only able to search a single tree for user data. For instance your Active Directory may be split up into the organisational units: Sales, Marketing, Accounts and Support. Users within each department are stored within their respective organisational units. Unfortunately, many applications will only use a single tree to perform a search for user data. If an application is authenticating against data stored in Active Directory, you may find that the application can only authenticate users from one department, as it is unable to recursively search through all of the other trees.

Symlabs LDAP Proxy is able to overcome this problem easily, using the Merge Trees plugin. Using the LDAP Proxy, you are able to merge all of the trees on the fly, so that a client application can be configured to search a virtual tree that includes all of the users from each organisational unit.

Fig-1: Active Directory can group users in different Organizational Units

2 Assumptions

1. LDAP Proxy is installed and configured properly; LDAP Proxy is currently running.

2. Active Directory is installed and is currently running and accessible to LDAP Proxy.

3. Active Directory is configured in such a way that there are a number of different organisational units and that each unit has been populated with differing userdata.

4. Port 3890 is available on the computer in which LDAP Proxy is installed.

3 Create a New Configuration

1. Click File on the menu bar, then click New.

2. Click the OK button when asked which server you want to create the new configuration in (the default server is Local).

3. Enter MergeTreesTutorial for the filename when prompted, then click the Save button.

3.1 Server Group Configuration

Server Groups are the directories where your user information is stored. For this tutorial we will be creating one Server Group that contains a single directory pointing to your Active Directory server.

1. Click on the Output button on the left-hand side of the application to begin to configure a servergroup.

2. Click on the New Server Group button near the bottom of the screen.

3. Enter ActiveDirectory for your new Server Group and leave the Server Group Type as Automatic and then click the Okay button.

4. Click on the ActiveDirectory button on the left-hand side of the screen.

   
   
   Fig-2: Configure a Server Group for your Active Directory server

5. Under the Servers tab, enter the Hostname / IP Address and the Port of your Active Directory server.

6. Click OK to save the change.

3.2 Listener Configuration

1. Click on the Input button on the left-hand side of the application.

2. Click on the New Listener button near the bottom of the screen.

3. Enter ActiveListener for the new input / listener and then click the OK button.

4. Click on the listener=ActiveListener button on the left-hand side of the screen to begin configuring the listener.

   
   
   Fig-3: Configure a Listener for LDAP Proxy

5. Under the Main Listener Properties tab, make sure the Protocol is set to ldap.

6. Under the Main Listener Properties tab, set the port to 3890.

7. Under the Main Listener Properties tab, select ActiveDirectory from the dropdown box to the right of Default Server Group.

8. Due to the varied way in which various browsers and servers present attribute information, it is good practice to make use of Canonicalization on Attribute Names to avoid incompatibilities down the line. Check all of the boxes in the Attribute Names window area.

9. Click the OK button near the top of the screen to save the Listener configuration.

4 Add Processing Stages

In this tutorial, we will also make use of the Add Entries plugin so that our merged trees are visible to browsers searching higher up in the tree, as the Merge Trees plugin will only come into action when the virtual tree that we create is requested. As a result, it will make sense to create two separate Processing Stages to hold these plugins.

1. Click on Processing in the Navigator on the left.

2. Click on the New Stage button, and name the stage AddEntry.

   
   
   Fig-4: Add a Processing Stage for each plugin that you use

3. Click on the AddEntry node that has been created in the Navigator tree, and click on the Add Plugin button.

4. A pop-up dialog will appear. Scroll through the list of plugins and select the Add Entries plugin. Click OK.

   
   
   Fig-5: Attach the Add Entries plugin to the stage

5. Click on the Add Entries plugin listed in the Navigator Tree.

6. Click on the New Virtual Entry button and name the new entry "allusers".

   
   
   Fig-6: Click on the Add Entries plugin to create a New Virtual Entry

    

7. Click on the "allusers" node in the Navigator tree.

8. In the Entry Dn field, provide the DN that you wish to use to refer to the virtual tree. In our example, we will use ou=allusers,ou=LiveOffice,dc=testsymlabs,dc=com. In order to keep our configuration consistent, and because we are using canonicalization, note that all of the Attribute Names in the DN are entered in lower case.

   
   
   Fig-7: Configure the allusers entry for the virtual tree

    

9. You will now need to provide some attributes for the virtual DN that you are creating. In the Attribute Type column of the table, create an attribute type called "objectclass". In the Attribute Values column, enter a value of "top" and a second value of "organizationalunit".

10. Create a second Attribute type called "ou" and assign it the value "allusers".

11. Click on the Processing node in the Navigator panel again, and then on the New Stage button. Name the new stage MergeTrees, as this stage will contain the Merge Trees plugin.

12. Click on the Add Plugins button and scroll through the list of plugins until you can select the Merge Trees plugin. Click OK.

    
    
    Fig-8: Add the Merge Trees Plugin to the new Processing Stage

     

13. Click on the Merge Trees plugin node in the Navigator panel.

14. In the Condition section of the panel on the right, add a rule to only process if the Base DN matches our virtual tree DN. So in our example, we will enter ou=allusers,ou=LiveOffice,dc=testsymlabs,dc=com. Once again, note that all of the Attribute Names that make up the DN are specified in lowercase in order to take advantage of canonicalization.

15. In the Joined Tree DN field, enter the DN for the virtual tree that you intend to create. Once again, in our example, we will enter ou=allusers,ou=LiveOffice,dc=testsymlabs,dc=com. And again we have specified all Attribute Names in lower case.

16. Finally, in the table, enter the DNs for each of the trees that you wish to merge. So, for our example, we will add the following entries:
    
    ou=Accounts,ou=LiveOffice,dc=testsymlabs,dc=com
    
    ou=Sales,ou=LiveOffice,dc=testsymlabs,dc=com
    
    ou=Marketing,ou=LiveOffice,dc=testsymlabs,dc=com
    
    ou=Support,ou=LiveOffice,dc=testsymlabs,dc=com
    
    And for each of these entries we will use the Server Group, VirtualDirectory which we created earlier.

    
    
    Fig-9: Configure the Merge Trees Plugin

     

17. Click OK to save this part of the configuration.

5 Attach the Processing Stages to the Listener

1. Now go back to the Listener node in the Navigator panel, and click on the ActiveListener that we created earlier.

2. Click on the Attached Stages tab.

   
   
   Fig-10: Attach the Processing Stages to the Listener

    

3. In the Stages list, double click on the first line and select the AddEntry stage.

4. A new line will appear, double click on it and select the MergeTrees stage.

5. Click OK to save this change.

6. Finally click on the Save button in the toolbar, or choose the option to Save Config from the File menu.

6 Testing the configuration.

You should now have completed configuring an instance of LDAP Proxy that will be able to merge different trees within Active Directory to present them as a single virtual tree. To test the new configuration, we will start the LDAP Proxy instance and then connect to it using an LDAP browser. Using the browser, we will be able to see the RDN ou=allusers listed, because the Add Entries plugin will make this available to the browser. When we actually browse this portion of the tree, all of the users that are listed in the other trees will be listed as users within the ou=allusers RDN, because the Merge Trees plugin will make this information available on the fly. Once you are certain that everything is working as expected, you will be able to configure your application to query this virtual tree to access the details of users in all of the DNs that you have configured to be merged by the Merge Trees plugin.

1. Click on the Start button in the toolbar, to launch an instance of LDAP Proxy using the current configuration.

2. Once the configuration is running, click on the LDAP Browser icon in the toolbar to launch the LDAP Browser. You could test this using another LDAP Browser if you have a preference, but the built-in browser will let you quickly determine whether your configuration is working as expected.

3. In the dialog that opens up, enter the relevant details to access the instance of LDAP Proxy that you have just configured. So, in our example, we will enter:
   
   Hostname: localhost
   
   Port: 3890
   
   Root Suffix: DC=testsymlabs,DC=com
   
   Bind DN: CN=Administrator,CN=Users,DC=testsymlabs,DC=com
   
   Password: secret

   
   
   Fig-11: Enter the details to connect to LDAP Proxy into the LDAP Browser

4. Click the Test Connection button.

5. If the test connection was succesful, click OK.

6. Use the browser to navigate your way through the tree until you have opened the DN that should contain your virtual tree. In our example, this would be: ou=LiveOffice,dc=testsymlabs,dc=com.You should now see the virtual tree listed in the browser. This is available to browse because the Add Entries plugin has inserted the DN into the tree.

7. Expand the virtual tree (ou=allusers,ou=LiveOffice,dc=testsymlabs,dc=com) and you will now see all of the users listed from the original DNs that have been merged.

   
   
   Fig-12: The allusers DN should now show all of the users from the merged DNs

8. You can now confidently configure your application to search this new virtual tree in the LDAP Proxy to find all users.

Tutorial #1 - Load Balancing

Tutorial #1 - Load Balancing

1 Overview

In this tutorial we will be demonstrating load balancing in a round-robin fashion between two directories, Directory 1 and 2. LDAP requests that come to the LDAP Proxy will be sent in a round-robin fashion first to Directory 1, then to Directory 2, then to Directory 1, then to Directory 2 and so on.

2 Assumptions

1. LDAP Proxy is installed and configured properly; LDAP Proxy is currently running.

2. Directory 1 & 2 are both installed and accessible from the computer on which LDAP Proxy is installed.

3. Both of your directories are populated with users.

4. Directory 1 & 2 are replicating with or are nearly identical to one another.

5. Directory 1 & 2 are both accessible on port 389 (default ldap port)

6. You have a good understanding of the DIT structure of your directories.

7. Port 3890 is available on the computer in which LDAP Proxy is installed.

8. You have the ability to view the proper logs in Directory 1 and 2.

3 Create a New Configuration

1. Click File on the menu bar, then click New.

2. Click the OK button when asked which server you want to create the new configuration on (the default server is Local).

3. Enter LoadBalancingTutorial for the filename when prompted, then click the Save button and the following will appear:

   
   
   Fig-1: LDAP Proxy New configuration

3.1 Server Group Configuration

Server Groups are the directories where your user information is stored. Examples include Active Directory, Sun Directory Server and Oracle Internet Directory. For this tutorial we will be creating one Server Group that contains two directories, Directory 1 and Directory 2.

1. Click on the Output button on the left-hand side of the application and the following will appear:

   
   
   Fig-2: Add a Server Group

2. Click on the New Server Group button near the bottom of the screen.

3. Enter ReplicatedDirectories for your new Server Group and leave the Server Group Type as Automatic and then click the Okay button.

4. Verify that the Protocol is set to ldap.

5. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 1.

6. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 2.

   
   
   Fig-3: Configure the server group

7. Click on the Reliability/Performance tab and click on the Load-Balancing radio button.

   
   
   Fig-4: Enable Load Balancing

8. Click the OK button near the top of the application to save the ReplicatedDirectories Server Group Configuration.

3.2 Listener Configuration

1. Click on the Input button on the left-hand side of the application and the following will appear:

   
   
   Fig-5: Add an LDAP Proxy Listener

2. Click on the New Listener button near the bottom of the screen.

3. Enter LoadBalancing for the new input / listener and then click the Okay button.

4. Click on the listener=LoadBalancing button on the left-hand side of the screen and the following will appear:

   
   
   Fig-6: LDAP Proxy Listener configuration

5. Under the Main Listener Properties tab, make sure the Protocol is set to ldap.

6. Under the Main Listener Properties tab, set the port to 3890.

7. Under the Main Listener Properties tab, select ReplicatedDirectories from the dropdown box to the right of Default Server Group.

8. Click the OK button near the top of the screen to save the Listener configuration.

4 Health Monitoring Configuration

Health Checking is an important feature of Directory Extender. You will need it whenever you are using load-balancing or fail-over in server groups. The principle is simple: LDAP Proxy will periodically check every server by sending simple requests to it. Whenever LDAP Proxy notices that a server has gone down or come back up, the server status will change respectively. LDAP Proxy makes use of this state information for deciding where to send each next request.

1. Click on the Health Monitoring button on the left-hand side of the screen and the following will appear:

   
   
   Fig-7: LDAP Proxy Health monitoring configuration

2. Make sure the Enable Health Checking box is checked and set the Interval to 5 seconds (for testing purposes only).

3. In the Operation for Health Checking section, make sure the BIND radio-button is selected. Set the Timeout to 5 seconds and the Number of Iterations to 3.

4. In the Debug Level section, select Warning, Info and Trace.

5. In the Health Checking Parameters section, enter the appropriate information for the Bind DN and Password fields. These credentials are used to determine if the directories are up and running.

5 Save Configuration

When you created the new configuration you were prompted to enter a filename for your configuration. The file type for this file is ldif. The configuration must be saved before the LDAP Proxy can be launched for the first time. Also, the configuration must be saved and the LDAP Proxy re-launched before changes to the configuration will take effect.

1. Click on the File button on the menu bar.

2. Click Save and your configuration will then be ready to launch.

6 Launch and Test Configuration

1. Click the Process button on the menu bar.

2. Click Run on the drop-down menu. At this point the LDAP Proxy is running and is ready to accept LDAP requests.

   
   
   Fig-8: LDAP Proxy Launch and test configuration

3. Click the Extras button on the menu bar.

4. Click LDAP Browser on the drop-down menu and the following will appear:

   
   
   Fig-9: The LDAP Browser Connection Window

5. In the Name textbox, enter Load Balancing.

6. In the Hostname textbox, enter the IP Address of the computer that LDAP Proxy is installed on.

7. In the Port textbox, enter 3890.

8. In the Root Suffix textbox, enter the DN you'd like to be the root of your LDAP request.

9. In the Bind DN textbox, enter the DN of the user that has appropriate access to both Directory 1 and 2.

10. Enter the Password twice for the user specified in the step above.

11. Click the Test button.

12. Assuming you entered the correct information, a Test Successful! message will appear. Click the OK button. At this point, the LDAP Proxy routed a Bind request to either Directory 1 or 2 which you can verify by viewing the logs for Directory 1 and 2.

13. Click the Test button again.

14. Again, a Test Successful! message will appear. Click the OK button. At this point, the LDAP Proxy routed another Bind request to either Directory 1 or 2. This time however, the Bind request went to the directory that it did not go last time. Again, this can be verified by viewing the logs for Directory 1 and 2.

15. You can continue testing the connection or viewing entries in the LDAP browser and you can verify that the LDAP operations are alternating between the two directories by viewing the logs for Directory 1 and 2.

Tutorial #2 - Fail-over

Tutorial #2 - Fail-over

1 Overview

In this tutorial we will be demonstrating fail-over with fail-back. We have two directories, Directory 1 and 2 that are replicating with one another. Directory 1 is the default which receives all of LDAP requests from the LDAP Proxy until it becomes unavailable. Once Directory 1 becomes unavailable, all LDAP requests get temporarily routed to Directory 2 until Directory 1 goes back online.

2 Assumptions

1. LDAP Proxy is installed and configured properly; LDAP Proxy is currently running.

2. Directory 1 & 2 are both installed and accessible from the computer on which LDAP Proxy is installed.

3. Both of your directories are populated with users.

4. Directory 1 & 2 are replicating with or are nearly identical to one another.

5. Directory 1 & 2 are both accessible on port 389 (default ldap port)

6. You have a good understanding of the DIT structure of your directories.

7. Port 3890 is available on the computer in which LDAP Proxy is installed.

8. You have the ability to view the proper logs in Directory 1 and 2.

3 Create a New Configuration

1. Click File on the menu bar, then click New.

2. Click the OK button when asked which server you want to create the new configuration in (the default server is Local).

3. Enter FailoverTutorial for the filename when prompted, then click the Save button.

3.1 Server Group Configuration

Server Groups are the directories where your user information is stored. Examples include Active Directory, Sun Directory Server and Oracle Internet Directory. For this tutorial we will be creating one Server Group that contains two directories, Directory 1 and Directory 2.

1. Click on the Output button on the left-hand side of the application to begin to configure a servergroup.

2. Click on the New Server Group button near the bottom of the screen.

3. Enter ReplicatedDirectories for your new Server Group and leave the Server Group Type as Automatic and then click the Okay button.

4. Click on the ReplicatedDirectories button on the left-hand side of the screen.

   
   
   Fig-1: Configuring a Server Group in DSGUI

5. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 1.

6. Under the Servers tab, enter the Hostname / IP Address and the Port of Directory 2.

7. Click on the Reliability/Performance tab and verify that the Failover radio button is checked.

8. In the Fail-over Algorithm section, verify that the default is selected, First available Server, with Fail-back.

9. Click the OK button near the top of the application to save the ReplicatedDirectories Server Group Configuration.

3.2 Listener Configuration

1. Click on the Input button on the left-hand side of the application.

2. Click on the New Listener button near the bottom of the screen.

3. Enter Failover for the new input / listener and then click the Okay button.

4. Click on the listener=Failover button on the left-hand side of the screen to begin configuring the listener.

   
   
   Fig-2: Configuring a Listener

5. Under the Main Listener Properties tab, make sure the Protocol is set to ldap.

6. Under the Main Listener Properties tab, set the port to 3890.

7. Under the Main Listener Properties tab, select ReplicatedDirectories from the dropdown box to the right of Default Server Group.

8. Click the OK button near the top of the screen to save the Listener configuration.

4 Health Monitoring Configuration

Health Checking is an important feature of Directory Extender. You will need it whenever you are using load-balancing or fail-over in server groups. The principle is simple: LDAP Proxy will periodically check every server by sending simple requests to it. Whenever LDAP Proxy notices that a server has gone down or come back up, the server status will change respectively. LDAP Proxy makes use of this state information for deciding where to send each next request.

1. Click on the Health Monitoring button on the left-hand side of the screen.

2. Make sure the Enable Health Checking box is checked and set the Interval to 5 seconds (for testing purposes only).

3. In the Operation for Health Checking section, make sure the BIND radio-button is selected. Set the Timeout to 5 seconds and the Number of Iterations to 3.

4. In the Debug Level section, select Warning, Info and Trace.

5. In the Health Checking Parameters section, enter the appropriate information for the Bind DN and Password fields. These credentials are used to determine if the directories are up and running.

   
   
   Fig-3: Configure Health Monitoring 6

5 Save Configuration

When you created the new configuration you were prompted to enter a filename for your configuration. The file type for this file is ldif. The configuration must be saved before the LDAP Proxy can be launched for the first time. Also, the configuration must be saved and the LDAP Proxy re-launched before changes to the configuration will take effect.

1. Click on the File button on the menu bar.

2. Click Save and your configuration will then be ready to launch.

6 Launch and Test Configuration

1. Click the Process button on the menu bar.

2. Click Run on the drop-down menu. At this point the LDAP Proxy is running and is ready to accept LDAP requests.

3. Click the Extras button on the menu bar.

4. Click LDAP Browser on the drop-down menu and enter the details required to connect to the listener that you have configured:

   
   
   Fig-4: Enter the details required to connect to the listener

5. In the Name textbox, enter Failover.

6. In the Hostname textbox, enter the IP Address of the computer that LDAP Proxy is installed on.

7. In the Port textbox, enter 3890.

8. In the Root Suffix textbox, enter the DN you'd like to be the root of your LDAP request.

9. In the Bind DN textbox, enter the DN of the user that has appropriate access to both Directory 1 and 2.

10. Enter the Password twice for the user specified in the step above.

11. Click the Test button.

12. Assuming you entered the correct information, a Test Successful! message will appear. Click the OK button. At this point, the LDAP Proxy routed a Bind request to Directory 1 which you can verify by viewing the logs for Directory 1.

13. Click the Test button again.

14. Again, a Test Successful! message will appear. Click the OK button. At this point, the LDAP Proxy routed another Bind request to Directory 1. Again, this can be verified by viewing the logs for Directory 1.

15. Take Directory 1 offline and wait for approximately 1 minute.

16. Click the Test button again.

17. Again, a Test Successful! message will appear. Click the OK button. At this point, the LDAP Proxy routed a Bind request to Directory 2. This can be verified by viewing the logs for Directory 2.

Tutorial #3 - Merging Organizational Units in Active Directory

Tutorial #3 - Merging Active Directory Trees

1 Overview

A common problem faced by users of Active Directory arises when users are stored within the Directory in separate organisational units, and a client application is only able to search a single tree for user data. For instance your Active Directory may be split up into the organisational units: Sales, Marketing, Accounts and Support. Users within each department are stored within their respective organisational units. Unfortunately, many applications will only use a single tree to perform a search for user data. If an application is authenticating against data stored in Active Directory, you may find that the application can only authenticate users from one department, as it is unable to recursively search through all of the other trees.

Symlabs LDAP Proxy is able to overcome this problem easily, using the Merge Trees plugin. Using the LDAP Proxy, you are able to merge all of the trees on the fly, so that a client application can be configured to search a virtual tree that includes all of the users from each organisational unit.

Fig-1: Active Directory can group users in different Organizational Units

2 Assumptions

1. LDAP Proxy is installed and configured properly; LDAP Proxy is currently running.

2. Active Directory is installed and is currently running and accessible to LDAP Proxy.

3. Active Directory is configured in such a way that there are a number of different organisational units and that each unit has been populated with differing userdata.

4. Port 3890 is available on the computer in which LDAP Proxy is installed.

3 Create a New Configuration

1. Click File on the menu bar, then click New.

2. Click the OK button when asked which server you want to create the new configuration in (the default server is Local).

3. Enter MergeTreesTutorial for the filename when prompted, then click the Save button.

3.1 Server Group Configuration

Server Groups are the directories where your user information is stored. For this tutorial we will be creating one Server Group that contains a single directory pointing to your Active Directory server.

1. Click on the Output button on the left-hand side of the application to begin to configure a servergroup.

2. Click on the New Server Group button near the bottom of the screen.

3. Enter ActiveDirectory for your new Server Group and leave the Server Group Type as Automatic and then click the Okay button.

4. Click on the ActiveDirectory button on the left-hand side of the screen.

   
   
   Fig-2: Configure a Server Group for your Active Directory server

5. Under the Servers tab, enter the Hostname / IP Address and the Port of your Active Directory server.

6. Click OK to save the change.

3.2 Listener Configuration

1. Click on the Input button on the left-hand side of the application.

2. Click on the New Listener button near the bottom of the screen.

3. Enter ActiveListener for the new input / listener and then click the OK button.

4. Click on the listener=ActiveListener button on the left-hand side of the screen to begin configuring the listener.

   
   
   Fig-3: Configure a Listener for LDAP Proxy

5. Under the Main Listener Properties tab, make sure the Protocol is set to ldap.

6. Under the Main Listener Properties tab, set the port to 3890.

7. Under the Main Listener Properties tab, select ActiveDirectory from the dropdown box to the right of Default Server Group.

8. Due to the varied way in which various browsers and servers present attribute information, it is good practice to make use of Canonicalization on Attribute Names to avoid incompatibilities down the line. Check all of the boxes in the Attribute Names window area.

9. Click the OK button near the top of the screen to save the Listener configuration.

4 Add Processing Stages

In this tutorial, we will also make use of the Add Entries plugin so that our merged trees are visible to browsers searching higher up in the tree, as the Merge Trees plugin will only come into action when the virtual tree that we create is requested. As a result, it will make sense to create two separate Processing Stages to hold these plugins.

1. Click on Processing in the Navigator on the left.

2. Click on the New Stage button, and name the stage AddEntry.

   
   
   Fig-4: Add a Processing Stage for each plugin that you use

3. Click on the AddEntry node that has been created in the Navigator tree, and click on the Add Plugin button.

4. A pop-up dialog will appear. Scroll through the list of plugins and select the Add Entries plugin. Click OK.

   
   
   Fig-5: Attach the Add Entries plugin to the stage

5. Click on the Add Entries plugin listed in the Navigator Tree.

6. Click on the New Virtual Entry button and name the new entry "allusers".

   
   
   Fig-6: Click on the Add Entries plugin to create a New Virtual Entry

    

7. Click on the "allusers" node in the Navigator tree.

8. In the Entry Dn field, provide the DN that you wish to use to refer to the virtual tree. In our example, we will use ou=allusers,ou=LiveOffice,dc=testsymlabs,dc=com. In order to keep our configuration consistent, and because we are using canonicalization, note that all of the Attribute Names in the DN are entered in lower case.

   
   
   Fig-7: Configure the allusers entry for the virtual tree

    

9. You will now need to provide some attributes for the virtual DN that you are creating. In the Attribute Type column of the table, create an attribute type called "objectclass". In the Attribute Values column, enter a value of "top" and a second value of "organizationalunit".

10. Create a second Attribute type called "ou" and assign it the value "allusers".

11. Click on the Processing node in the Navigator panel again, and then on the New Stage button. Name the new stage MergeTrees, as this stage will contain the Merge Trees plugin.

12. Click on the Add Plugins button and scroll through the list of plugins until you can select the Merge Trees plugin. Click OK.

    
    
    Fig-8: Add the Merge Trees Plugin to the new Processing Stage

     

13. Click on the Merge Trees plugin node in the Navigator panel.

14. In the Condition section of the panel on the right, add a rule to only process if the Base DN matches our virtual tree DN. So in our example, we will enter ou=allusers,ou=LiveOffice,dc=testsymlabs,dc=com. Once again, note that all of the Attribute Names that make up the DN are specified in lowercase in order to take advantage of canonicalization.

15. In the Joined Tree DN field, enter the DN for the virtual tree that you intend to create. Once again, in our example, we will enter ou=allusers,ou=LiveOffice,dc=testsymlabs,dc=com. And again we have specified all Attribute Names in lower case.

16. Finally, in the table, enter the DNs for each of the trees that you wish to merge. So, for our example, we will add the following entries:
    
    ou=Accounts,ou=LiveOffice,dc=testsymlabs,dc=com
    
    ou=Sales,ou=LiveOffice,dc=testsymlabs,dc=com
    
    ou=Marketing,ou=LiveOffice,dc=testsymlabs,dc=com
    
    ou=Support,ou=LiveOffice,dc=testsymlabs,dc=com
    
    And for each of these entries we will use the Server Group, VirtualDirectory which we created earlier.

    
    
    Fig-9: Configure the Merge Trees Plugin

     

17. Click OK to save this part of the configuration.

5 Attach the Processing Stages to the Listener

1. Now go back to the Listener node in the Navigator panel, and click on the ActiveListener that we created earlier.

2. Click on the Attached Stages tab.

   
   
   Fig-10: Attach the Processing Stages to the Listener

    

3. In the Stages list, double click on the first line and select the AddEntry stage.

4. A new line will appear, double click on it and select the MergeTrees stage.

5. Click OK to save this change.

6. Finally click on the Save button in the toolbar, or choose the option to Save Config from the File menu.

6 Testing the configuration.

You should now have completed configuring an instance of LDAP Proxy that will be able to merge different trees within Active Directory to present them as a single virtual tree. To test the new configuration, we will start the LDAP Proxy instance and then connect to it using an LDAP browser. Using the browser, we will be able to see the RDN ou=allusers listed, because the Add Entries plugin will make this available to the browser. When we actually browse this portion of the tree, all of the users that are listed in the other trees will be listed as users within the ou=allusers RDN, because the Merge Trees plugin will make this information available on the fly. Once you are certain that everything is working as expected, you will be able to configure your application to query this virtual tree to access the details of users in all of the DNs that you have configured to be merged by the Merge Trees plugin.

1. Click on the Start button in the toolbar, to launch an instance of LDAP Proxy using the current configuration.

2. Once the configuration is running, click on the LDAP Browser icon in the toolbar to launch the LDAP Browser. You could test this using another LDAP Browser if you have a preference, but the built-in browser will let you quickly determine whether your configuration is working as expected.

3. In the dialog that opens up, enter the relevant details to access the instance of LDAP Proxy that you have just configured. So, in our example, we will enter:
   
   Hostname: localhost
   
   Port: 3890
   
   Root Suffix: DC=testsymlabs,DC=com
   
   Bind DN: CN=Administrator,CN=Users,DC=testsymlabs,DC=com
   
   Password: secret

   
   
   Fig-11: Enter the details to connect to LDAP Proxy into the LDAP Browser

4. Click the Test Connection button.

5. If the test connection was succesful, click OK.

6. Use the browser to navigate your way through the tree until you have opened the DN that should contain your virtual tree. In our example, this would be: ou=LiveOffice,dc=testsymlabs,dc=com.You should now see the virtual tree listed in the browser. This is available to browse because the Add Entries plugin has inserted the DN into the tree.

7. Expand the virtual tree (ou=allusers,ou=LiveOffice,dc=testsymlabs,dc=com) and you will now see all of the users listed from the original DNs that have been merged.

   
   
   Fig-12: The allusers DN should now show all of the users from the merged DNs

8. You can now confidently configure your application to search this new virtual tree in the LDAP Proxy to find all users.