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 VDS.

2 Assumptions

1. VDS is installed and configured properly; VDS is currently running.

2. Directory 1 & 2 are both installed and accessible from the computer on which VDS 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 VDS 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 VDS 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 VDS 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 VDS 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 VDS 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.

VDS 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 VDS (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 VDS 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. VDS 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 VDS 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 VDS.

2 Assumptions

1. VDS 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 VDS 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.

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 VDS 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 Server Group button near the bottom of the screen.

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

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

   
   Fig-4: Configure the second Server Group for RDBMS

5. Verify that the Protocol is set to Relational Database.

6. Set the Database Type to MySQL.

7. Enter the hostname/IP address, port number and database name in the Connection String field, in the following format: hostname:port:dbname

8. Enter the Username and Password for the user that has appropriate access to the MySQL database. Remember that if your VDS instance is running on a separate server to your MySQL install, your MySQL server and user must be configured to accept connections from outside (e.g. MySQL must be bound to an externally accessible IP address, and a user should have been created so that the user is able to access the MySQL database from the VDS server IP address.

9. Enter a Destination Tree that the MySQL data will be accessible through. This will be a DN within your normal LDAP tree. In our example, this is ou=db,dc=testsymlabs,dc=com

10. Finally, map the "users" table to an RDN so that we can query it using LDAP. In the DB Table/View column of the table, enter "users", which is the name of the table that we wish to map. In the Relative DN column, enter "ou=users". In the Naming Attr column, we will enter the table column that we wish to use as the attribute name by which we will reference each entity in the database table. In this case, we have used the "uid" field. Finally, if your database schema conforms to an LDAP schema, you can enter the objectclass in the last field of the table. Our database table does not conform to any particular schema, so we will use the extensibleobject objectclass.

11. 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-5: 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-6: 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-7: 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-8: 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-9: 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-10: 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-11: Use the LDAP Browser to test the running VDS 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-12: 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 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 VDS 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. VDS is installed and configured properly; VDS is currently running.

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

3. A MySQL database is installed, configured, and accessible from the computer on which VDS 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 VDS 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=db,dc=tamuz,dc=xplode,dc=org.

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	<-->	givenname
   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 VDS 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 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 VDS instance. With some basic setup steps, it is possible for an administrator to work directly on a VDS 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 VDS 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 VDS 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 VDS 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. VDS 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 VDS 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 VDS 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 VDS Host and Configure RAS

Depending on the Operating System that the Remote VDS Host is using, you will need to determine how best to access the Remote VDS 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 VDS 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 VDS 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 will need to initially run the RAS startup script manually on the command line. After this has been done, the RAS Service will be registered as a normal Windows Service and will be accessible in the Services Control Panel on the Remote VDS Host, listed with the name Directory Extender. On Unix and Linux systems, the daemon or service will need to be started manually from the shell.
   
   

   For Windows systems, you can start the RAS service by opening a command prompt. Changing to the root directory of your VDS installation (usually, C:\Program Files\Symlabs\DE\R4.0.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 VDS 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 VDS Host and Create a New Configuration

You will now be able to connect to the Remote VDS 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 VDS Host that you have specified in your Preferences. Click OK.

   
   Fig-3: Select the VDS 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.