U.S. +1 (312) 214 3570  |  E.U +34 (91) 656-9266
Contact Us

Tutorials

Tutorial #1 - Load Balancing

Tutorial #1 - Load Balancing

Click here to download this tutorial as a PDF file.

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:

    LDAP Proxy New configuration
    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:

    Add a server group
    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.

    Configure the server group
    Fig-3: Configure the server group

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

    Enable Load Balancing
    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:

    Add an LDAP Proxy Listener
    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:

    LDAP Proxy Listener configuration
    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:

    LDAP Proxy Health monitoring configuration
    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.

    LDAP Proxy Launch and test configuration
    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:

    The LDAP Browser Connection Window
    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.

TOP

Tutorial #2 - Fail-over

Tutorial #2 - Fail-over

Click here to download this tutorial as a PDF file.

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.

TOP

Tutorial #3 - Merging Organizational Units in Active Directory

Tutorial #3 - Merging Active Directory Trees

Click here to download this tutorial as a PDF file.

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.

Active Directory can group users in different Organizational Units
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.

    Configure a Server Group for your Active Directory server
    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.

    Configure a Listener for LDAP Proxy
    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.

    Add a Processing Stage for each plugin that you use
    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.

    Attach the Add Entries plugin to the stage
    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".

    Click on the Add Entries plugin to create a New Virtual Entry
    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.

    Configure the allusers entry for the virtual tree
    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.

    Add the Merge Trees Plugin to the new Processing Stage
    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.

    Configure the Merge Trees Plugin
    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.

    Attach the Processing Stages to the Listener
    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

    Enter the details to connect to LDAP Proxy into the LDAP Browser
    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.

    The allusers DN should now show all of the users from the merged DNs
    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.

TOP

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