Tutorial #1 - Merge Users From Multiple Directories

Click here to download this tutorial as a PDF file.

Overview

There can be many reasons why an organization would need to take user data stored across multiple 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. Symlabs Virtual Directory Server (VDS) solves this problem by presenting users from multiple systems on a single virtual tree accessible from one system.

There is more than one way to achieve this functionality. One option is to create a Virtual Tree and then map data stored in different repositories onto branches within the Virtual Tree. An alternative approach is to make use of the Merge Trees plugin bundled with Virtual Directory Server, to merge data stored in separate branches on separate repositories, so that it appears as if all of this data is stored within a single directory branch accessible from the VDS. In this tutorial, we will work with the Merge Trees plugin.

Before you begin

Before you start working on this tutorial, make sure that you have properly installed Symlabs Virtual Directory Server and that you can at least create a functioning pass-thru proxy configuration, as per the QuickStart guide included with the product.

This tutorial will show how it is possible to merge data from two separate LDAP repositories. This means that you should have two LDAP directories set up and running. The directories should each contain a branch of similarly stored data (e.g. a 'users' branch) that you may want to merge to appear as if it is stored in a single branch on one server. You should also make sure that neither of the directories contains users with duplicate naming attributes. Although this is not critical, data from on of your directories will be given precedence, and in the merge process, the data for the duplicate user will not appear in the virtual directory.

It should be fairly obvious, but both directories should be accessible to the system running Virtual Directory Server. Make sure that there are no firewall rules preventing access. If you have already set up a successful pass-thru proxy configuration, you should already be aware of any likely network hinderances.

Since this product is mostly directed toward people who work with directories frequently, we assume that you already have a fair understanding of some basic LDAP concepts and are used to finding your way around a directory tree without too many problems.

Finally, this tutorial is largely based around the demonstration environment that we have set up for this purpose. Your environment is likely to differ considerably, so the presentation here will need to be adapted to your systems as you move through the tutorial. Obviously, IP addresses and hostnames will need to change, and more than likely the DNs that are used will differ from those in your own directories. Keep aware of the differences and adapt them to suit your environment. So let's begin.

Create a New Configuration

Open DSGUI, or the Virtual Directory Server Administration Console, and click on File in the menu bar, and click on New to select the New Local Config option.

Give your configuration a relevant name, when prompted, and click on the Save button. This will create a new configuration file and you should see a screen that looks something like this:

Fig: Create a new configuration

Server Group Configuration

The first step to getting a working configuration is to configure the Server Groups within the Output part of the configuration. Server Groups are configuration containers that group together replica Directory servers, and provide various useful functions such as Load Balancing, Failover and Connection Pooling facilities. In this case, since we are not working with replica servers, we will be creating two separate Server Groups, each containing one of the backend Directories that we wish to connect to.

Create the first Server Group

Click on the Output node in the navigation panel on the left-hand side of the application. The configuration panel on the right hand side should update to give you the option to create a New Server Group or a New Database Connection:

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

Click on the New Server Group button, and a popup dialog box will appear for you to provide a name for the Server Group. Enter a useful name, such as the Directory name that you will be connecting to. And click OK.

You will see the new Server Group, that you have configured, appear in the navigation panel on the left. By clicking on it, you can update the configuration panel, on the right, to show the configuration options available to set up your Server Group.

Fig: Configure the first Server Group

You will need to enter the hostname or IP address of the backend directory that you want to connect to, and you will need to enter the port number that the server is listening on (usually 389 for most LDAP servers).

Next, click on the Connection Pooling tab and check the Use Connection Pooling checkbox. Connection pooling will open a number of connections to the backend directory and will keep them open and ready for request routing. This is prevents a new connection from being opened for each request that is processed by the VDS instance, and helps to improve efficiency.

Fig: Configure Connection Pooling for the first Server Group

Click on the Use Fixed Credentials radio button and enter the Bind DN and Password for the user that has appropriate access to this directory server. For this tutorial situation, we will not need to create a large pool of open connections, so you may want to change the number of Pool Connections from 10 to 2.

Finally, click the OK button near the top of the application to store your changes for this Server Group.

Create the second Server Group

Once again, click on the Output node in the navigation panel and click on the New Server Group button. Provide an appropriate name for your second Server Group and click OK.

Once the second Server Group has been created, you will be able to select it in the navigation panel to configure it for your second LDAP directory.

Fig: Configure the second Server Group

Verify that the Protocol is set to ldap. Under the Servers tab, enter the hostname or IP Address and the listener port for your second directory.

Click on the Connection Pooling tab and check the Use Connection Pooling checkbox. Click on the Use Fixed Credentials radio button then enter the Bind DN and Password for the user that has appropriate access to your second Directory, and change the number of connections in your Connection Pool to something more suitable for a testing environment.

Fig: Configure the Connection Pooling for the second Server Group

Note that although we have configured Connection Pooling in this configuration, for the purpose of improving performance by maintaining open connections, it is not necessary to configure this facility at all. The Virtual Directory is capable of opening connections to the backend using the credentials of the user connecting to the VDS Listener.

Click the OK button near the top of the application to store the changes to this Server Group Configuration.

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.

Click on the Processing node in the navigation panel, and in the configuration panel, click on the button that allows you to create a New Stage. You will be prompted to enter a name for the Stage, and you will have an option to select between an Automatic or Manual stage. Choose a useful name, like "Merge Trees", and leave the stage type as Automatic, since you will be making use of a bundled plugin. Click OK and your processing stage will appear in the Navigation panel on the left.

When you click on an Automatic processing stage in the navigation panel, you will be presented with the option to Add Plugin in the configuration panel. Clicking on this button will bring up the Plugins dialog. You can scroll through the options here to find a plugin suitable for the functionality that you want to build into your solution. In this case, look for the Merge Trees plugin.

Fig: Add the Merge Trees plugin

Once you have added the plugin, it should appear as a node in the navigation panel connected beneath your processing stage. If you click on it, you will be able to access the configuration options for the plugin.

Fig: Configure the Merge Trees plugin

All plugins have some common configuration options. At the top of the plugin configuration panel, you will see that you are able to define different conditions for which the plugin will be triggered. For now, we can leave these empty.

There is also an option to set the Debug Level for the plugin. This will control how verbose the debug reporting for the plugin is in the STDOUT log file. For now, we can leave the debug level at its lowest setting.

Finally, there are the options specific to the plugin that you are configuring. The first option here is the Joined Tree DN. In this box, you should enter a non-existent RDN for a branch attached to the Base DN of the Directory that you want the merged users to appear on. So, for instance, in the screenshot you can see that we have specified 'ou=allusers,dc=my_organization,dc=com'. The 'ou=allusers' branch does not exist within the 'dc=my_organization,dc=com' tree on the SunDSEE server where this domain is located.

Beneath this field, are a set of checkboxes, which allow you to control various behaviours, including whether the merged tree should support BIND functionality or not. The default options here should suffice for this tutorial.

Below these options is a table, where you can specify the DN of the Tree to merge and the Server Group that contains it. You can also specify whether the Server Group should return the base entry of the merged branch if a search is done to the joined tree DN with a scope 'base'.Generally it is a good idea to enable this. You will notice, in the screenshot, that we have entries here for a number of branches located in each of our directories, which we intend to merge together to appear as a set of entries stored within our virtual branch.

Listener Configuration

The final part of our configuration will be to define how a client application can connect to the Virtual Directory. In the Input part of the configuration, we will define a Listener that can accept client connections.

Click on the Input node in the navigation panel, and click on the New Listener button near the bottom of the screen. You will be prompted for a name for your listener, which you can choose to your liking. You can change this at any point in the future, if you need to.

Once the Listener has been created, it will appear as a node in the navigation panel. Click on the Listener node to access its configuration panel.

Fig: Configure the new Listener

Under the Main Listener Properties tab, although there are many options here, we only need to make a small number of changes. Firstly, make sure the Protocol is set to ldap, so that the Listener only accepts LDAP requests. Next, set the Listen Port to 3890 (which will prevent any conflict with locally hosted LDAP servers, and will ensure that you have permission to run this software as a TCP service). Finally, set the Default Server Group by clicking on the dropdown box and selecting the Server Group that hosts the Base DN that you used in your Joined Tree DN inside the Merge Trees plugin.

Now click on the Attached Stages tab. Here you can specify which processing stages should be attached to the Listener, and in what order they should be invoked. In more complex solutions, you may want to use multiple Listeners that have different processing functionality attached in different orders.

Fig: Attach the Processing Stages to the Listener

In this situation, we only have a single processing stage defined, so in the table, double-click on the first row, and select the processing stage from the dropdown box. Click OK, to store the changes to your Listener configuration, and finally save the configuration.

Launch and Test Configuration

At this point, you should have a working configuration. All that remains is for you to start it up and test it. Click on the Run button, or select the Run option from the Process menu in the menu bar. If everything goes well, the VDS instance should start up and will listen for LDAP requests on its Listener interface. It will also open a set of connections to your backend directories, as defined by your Connection Pool settings.

To test the configuration and to see the Merge Trees functionality in action, open up Symlabs LDAP Browser by clicking on the Launch LDAP Browser button or by selecting it from the Extras menu in the menu bar.

Configure a connection to connect to the locally hosted VDS instance.

Fig: Use the LDAP Browser to connect to your running VDS instance

In the Host field, type either 'localhost' or '127.0.0.1'. In the Port field, specify the port number that you defined for the Listener, '3890'. For the User id and Password fields, specify BIND credential appropriate for the directory that is your default Server Group. And finally, in the Suffixes field, specify the DN that you used for the Joined Tree DN in the Merge Trees plugin. Finally click Connect.

You can now browse the newly created branch and verify that users from both directories are included in the branch.

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

TOP

Tutorial #2 - Fragmented Identities

Click here to download this tutorial as a PDF file.

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 Entries" plugin that comes bundled with Symlabs Virtual Directory Server.

This tutorial will demonstrate how an organization that has fragmented identity data stored across two separate directories can present this in a consolidated way using the Join Entries plugin. In our example, we have a general LDAP directory which is used to store employee user accounts and other basic information, and we have a second directory that stores employee accounting data for payroll purposes. The only reliable attribute common to the entries stored in each of these directories is the 'mail' attribute that holds a fixed email address for each employee. Using the Join Entries plugin, we will merge the data stored for each entry where the value of the 'mail' attribute matches.

This functionality helps you to define views of your data that links together data stored in different directories, so that it is possible to view the relationships between entries that are stored in different repositories.

Before you begin

Before you start working on this tutorial, make sure that you have properly installed Symlabs Virtual Directory Server and that you can at least create a functioning pass-thru proxy configuration, as per the QuickStart guide included with the product.

This tutorial will show how it is possible to join data for independent entries stored on separate branches within two separate LDAP repositories. This means that you should have two LDAP directories set up and running. The directories should each contain a branch of entries that have at least one common attribute, that should preferably be unique and which can be used to define a join relationship. This process is similar to performing a SQL-style join, where a common identifier is used to present related data stored across two different tables.

It should be fairly obvious, but both directories should be accessible to the system running Virtual Directory Server. Make sure that there are no firewall rules preventing access. If you have already set up a successful pass-thru proxy configuration, you should already be aware of any likely network hinderances.

Since this product is mostly directed toward people who work with directories frequently, we assume that you already have a fair understanding of some basic LDAP concepts and are used to finding your way around a directory tree without too many problems.

Finally, this tutorial is largely based around the demonstration environment that we have set up for this purpose. Your environment is likely to differ considerably, so the presentation here will need to be adapted to your systems as you move through the tutorial. Obviously, IP addresses and hostnames will need to change, and more than likely the DNs that are used will differ from those in your own directories. Keep aware of the differences and adapt them to suit your environment. So let's begin.

Create a New Configuration

Open DSGUI, or the Virtual Directory Server Administration Console, and click on File in the menu bar, and click on New to select the New Local Config option.

Give your configuration a relevant name, when prompted, and click on the Save button. This will create a new configuration file and you should see a screen that looks something like this:

Fig: Create a new configuration

Server Group Configuration

The first step to getting a working configuration is to configure the Server Groups within the Output part of the configuration. Server Groups are configuration containers that group together replica Directory servers, and provide various useful functions such as Load Balancing, Failover and Connection Pooling facilities. In this case, since we are not working with replica servers, we will be creating two separate Server Groups, each containing one of the backend Directories that we wish to connect to.

Create the first Server Group

Click on the Output node in the navigation panel on the left-hand side of the application. The configuration panel on the right hand side should update to give you the option to create a New Server Group or a New Database Connection.

Click on the New Server Group button, and a popup dialog box will appear for you to provide a name for the Server Group. Enter a useful name, such as the Directory name that you will be connecting to. And click OK.

You will see the new Server Group, that you have configured, appear in the navigation panel on the left. By clicking on it, you can update the configuration panel, on the right, to show the configuration options available to set up your Server Group.

Fig: Configure the first Server Group

You will need to enter the hostname or IP address of the backend directory that you want to connect to, and you will need to enter the port number that the server is listening on (usually 389 for most LDAP servers).

Next, click on the Connection Pooling tab and check the Use Connection Pooling checkbox. Connection pooling will open a number of connections to the backend directory and will keep them open and ready for request routing. This is prevents a new connection from being opened for each request that is processed by the VDS instance, and helps to improve efficiency.

Fig: Configure Connection Pooling for the first Server Group

Click on the Use Fixed Credentials radio button and enter the Bind DN and Password for the user that has appropriate access to this directory server. For this tutorial situation, we will not need to create a large pool of open connections, so you may want to change the number of Pool Connections from 10 to 2.

Finally, click the OK button near the top of the application to store your changes for this Server Group.

Create the second Server Group

Once again, click on the Output node in the navigation panel and click on the New Server Group button. Provide an appropriate name for your second Server Group and click OK.

Once the second Server Group has been created, you will be able to select it in the navigation panel to configure it for your second LDAP directory.

Fig: Configure the second Server Group

Verify that the Protocol is set to ldap. Under the Servers tab, enter the hostname or IP Address and the listener port for your second directory.

Click on the Connection Pooling tab and check the Use Connection Pooling checkbox. Click on the Use Fixed Credentials radio button then enter the Bind DN and Password for the user that has appropriate access to your second Directory, and change the number of connections in your Connection Pool to something more suitable for a testing environment.

Fig: Configure the Connection Pooling for the second Server Group

Note that although we have configured Connection Pooling in this configuration, for the purpose of improving performance by maintaining open connections, it is not necessary to configure this facility at all. The Virtual Directory is capable of opening connections to the backend using the credentials of the user connecting to the VDS Listener.

Click the OK button near the top of the application to store the changes to this Server Group Configuration.

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 plugin called the Join Entries plugin and is provided by the VDS to allow you to quickly and easily implement the functionality that you're looking for. The Join Entries plugin 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.

Click on the Processing node in the navigation panel, and in the configuration panel, click on the button that allows you to create a New Stage. You will be prompted to enter a name for the Stage, and you will have an option to select between an Automatic or Manual stage. Choose a useful name, like "Join Entries", and leave the stage type as Automatic, since you will be making use of a bundled plugin. Click OK and your processing stage will appear in the Navigation panel on the left.

When you click on an Automatic processing stage in the navigation panel, you will be presented with the option to Add Plugin in the configuration panel. Clicking on this button will bring up the Plugins dialog. You can scroll through the options here to find a plugin suitable for the functionality that you want to build into your solution. In this case, look for the Join Entries plugin.

Fig: Add the Join Entries plugin

Once you have added the plugin, it should appear as a node in the navigation panel connected beneath your processing stage. If you click on it, you will be able to access the configuration options for the plugin.

Fig: Configure the Join Entries plugin

All plugins have some common configuration options. At the top of the plugin configuration panel, you will see that you are able to define different conditions for which the plugin will be triggered. In this case, we only want the plugin to be triggered when a client requests data from a particular branch within our directory tree. In our example, this will be for data stored within the 'ou=People,dc=my_organization,dc=com' branch. So we enter this into the Base DN field in the Conditions table. This will mean that the plugin is only invoked when a client queries any entry stored within this branch.

There is also an option to set the Debug Level for the plugin. This will control how verbose the debug reporting for the plugin is in the STDOUT log file. For now, we can leave the debug level at its lowest setting.

The final section is a tabbed panel that allows you to configure the parameters specific to the Join Entries plugin. On the Main Parameters tab, enter an attribute in the Primary Join Attribute textbox. In our example, we know that the 'mail' attribute is commonly used in both Directories. This means that we can use this attribute to join our two datastores. There is also a checkbox that allows you to specify whether or not the attribute is part of the RDN (i.e. is a naming attribute). In our example, the 'mail' attribute is not part of the RDN so we ensure that it is not checked. If your joining attribute is a naming attribute, you should leave this box checked (default). Click on the OK button to store your changes.

A table titled 'Aggregated Attributes' allows you to define which attributes should be aggregated as 'multi-valued' attributes during the join process. This is useful where the two directories may have conflicting or additional information for an attribute. In our example, we have determined that frequently telephone numbers in the two directories differ, and we would like the client application to present the phone numbers from both of the two directories. You can do this with any multi-valued attribute.

Toward the bottom of the Main Parameters tab is a button labelled New Foreign Data Group. Click on this button, and enter a name for the second directory store that you will use to extract data from. In our case, we are going to extract the additional data from an OpenDS directory dedicated to the accounting department, so we have named the data group 'OpenDS-accounting'.

When you have created a New Foreign Data Group, it will appear as a node within the navigation tree, just beneath the Join Entries plugin. Click on this node, to access the configuration panel.

Fig: Configure the Foreign Data Group

Foreign Data Groups are used to define the alternate location that should be searched to extract additional information to be included in the virtual entry that is eventually returned to the client application. Since the joining attribute may be named differently on another directory (e.g. the attribute may be named 'email' instead of 'mail'), you are able to define the name of the joining key attribute for each foreign data group. Enter the appropriate attribute in the Primary Key Attribute section. In our case, we are joining the data based on the 'mail' attribute which we know is common in both Directories. Once again, uncheck the checkbox if the Primary Key Attribute is not part of the RDN on this system, otherwise leave it checked.

In the drop-down box titled Server where information should be fetched from, click on the appropriate Server Group. In our case, the additional data is stored in the accounting server which we set up in the OpenDS Server Group.

Finally enter the Base DN where information should be fetched from. In our case, the additional accounting data that we wish to present within each entry is stored within the Base DN: "ou=employees,o=accounting,dc=mycompany.org".

Click the OK button near the top of the screen to store the changes to the Foreign Data Group configuration.

Listener Configuration

The final part of our configuration will be to define how a client application can connect to the Virtual Directory. In the Input part of the configuration, we will define a Listener that can accept client connections.

Click on the Input node in the navigation panel, and click on the New Listener button near the bottom of the screen. You will be prompted for a name for your listener, which you can choose to your liking. You can change this at any point in the future, if you need to.

Once the Listener has been created, it will appear as a node in the navigation panel. Click on the Listener node to access its configuration panel.

Fig: Configure the new Listener

Under the Main Listener Properties tab, although there are many options here, we only need to make a small number of changes. Firstly, make sure the Protocol is set to ldap, so that the Listener only accepts LDAP requests. Next, set the Listen Port to 3890 (which will prevent any conflict with locally hosted LDAP servers, and will ensure that you have permission to run this software as a TCP service). Finally, set the Default Server Group by clicking on the dropdown box and selecting the Server Group that hosts the Base DN where you store the majority of your user data. In our case, this is the common employee user account directory, which is contained in the SunDSEE Server Group.

Now click on the Attached Stages tab. Here you can specify which processing stages should be attached to the Listener, and in what order they should be invoked. In more complex solutions, you may want to use multiple Listeners that have different processing functionality attached in different orders.

Fig: Attach the Processing Stages to the Listener

In this situation, we only have a single processing stage defined, so in the table, double-click on the first row, and select the processing stage from the dropdown box. Click OK, to store the changes to your Listener configuration, and finally save the configuration.

Launch and Test Configuration

At this point, you should have a working configuration. All that remains is for you to start it up and test it. Click on the Run button, or select the Run option from the Process menu in the menu bar. If everything goes well, the VDS instance should start up and will listen for LDAP requests on its Listener interface. It will also open a set of connections to your backend directories, as defined by your Connection Pool settings.

To test the configuration and to see the Join Entries functionality in action, open up Symlabs LDAP Browser by clicking on the Launch LDAP Browser button or by selecting it from the Extras menu in the menu bar.

Configure a connection to connect to the locally hosted VDS instance.

Fig: Use the LDAP Browser to connect to your running VDS instance

In the Host field, type either 'localhost' or '127.0.0.1'. In the Port field, specify the port number that you defined for the Listener, '3890'. For the User id and Password fields, specify BIND credential appropriate for the directory that is your default Server Group. And finally, in the Suffixes field, specify the DN that you used for the Base DN in the Conditions section of the Join Entries plugin. Finally click Connect.

You can now browse the directory and verify that the data for each user includes attributes from both directories. In the screenshot for our example, you can see that the entry contains some attributes such as the mycompTaxNumber, mycompDepartment and mycompTitle. This attributes have been retrieved from the OpenDS accounting directory. You can also see that the entry has two telephone numbers listed, this is because we have aggregated this attribute to show both the number listed in the SunDSEE directory and the number listed on the OpenDS directory.

Fig: You can see that entries contain data extracted from both directories

TOP

Tutorial #3 - Integrating RDBMS into an LDAP Environment

Tutorial #3 - Integrating RDBMS into an LDAP Environment

Click here to download this tutorial as a PDF file.

Overview

Most organizations store user data in multiple repositories. Frequently when thinking about Virtual Directory Servers it is easy to assume that these repositories are of the same type, using the same protocol and nomenclature. However, in reality data is more often 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.

Before you begin

Before you start working on this tutorial, make sure that you have properly installed Symlabs Virtual Directory Server and that you can at least create a functioning pass-thru proxy configuration, as per the QuickStart guide included with the product.

This tutorial will show how it is possible to present data stored within a MySQL database table (you can use an alternative RDBMS if you wish) as a set of entries listed on a virtual branch attached to a standard LDAP Server. This means that you will require at least one LDAP server, and one relational database (preferably MySQL if you wish to follow this tutorial in a strict fashion). While, at this point, it does not matter what data is stored within your MySQL table, you may find it useful to include a table that may be useful if presented through LDAP. For example, if you have a table of User information, including a username and password, you could set this up to handle BIND requests. In our solution, we will attach a table that contains 'Leave' or vacation data related to users that happen to be stored in our LDAP directory.

It should be fairly obvious, but the directory and database servers should be accessible to the system running Virtual Directory Server. Make sure that there are no firewall rules preventing access. If you have already set up a successful pass-thru proxy configuration, you should already be aware of any likely network hinderances.

Since this product is mostly directed toward people who work with directories frequently, we assume that you already have a fair understanding of some basic LDAP concepts and are used to finding your way around a directory tree without too many problems. We will also be covering some very basic relational database concepts, so you should also be familiar with these systems to make sense of this tutorial.

Finally, this tutorial is largely based around the demonstration environment that we have set up for this purpose. Your environment is likely to differ considerably, so the presentation here will need to be adapted to your systems as you move through the tutorial. Obviously, IP addresses and hostnames will need to change, and more than likely the DNs that are used will differ from those in your own directories. Keep aware of the differences and adapt them to suit your environment. So let's begin.

Create a New Configuration

Open DSGUI, or the Virtual Directory Server Administration Console, and click on File in the menu bar, and click on New to select the New Local Config option.

Give your configuration a relevant name, when prompted, and click on the Save button. This will create a new configuration file that you can begin working with immediately.

Server Group Configuration

The first step to getting a working configuration is to configure the Server Groups within the Output part of the configuration. Server Groups are configuration containers that group together either directories or relational databases that may contain data that you want to present through the Virtual Directory Server interface. For this tutorial we will be creating two Server Groups, one for our LDAP Directory and another for our MySQL database.

Create the first Server Group

Click on the Output node in the navigation panel on the left-hand side of the application. The configuration panel on the right hand side should update to give you the option to create a New Server Group or a New Database Connection.

Click on the New Server Group button, and a popup dialog box will appear for you to provide a name for the Server Group. Enter a useful name, such as the Directory name that you will be connecting to. And click OK.

You will see the new Server Group, that you have configured, appear in the navigation panel on the left. By clicking on it, you can update the configuration panel, on the right, to show the configuration options available to set up your Server Group.

Fig: Configure the first Server Group

You will need to enter the hostname or IP address of the backend directory that you want to connect to, and you will need to enter the port number that the server is listening on (usually 389 for most LDAP servers).

Next, click on the Connection Pooling tab and check the Use Connection Pooling checkbox. Connection pooling will open a number of connections to the backend directory and will keep them open and ready for request routing. This is prevents a new connection from being opened for each request that is processed by the VDS instance, and helps to improve efficiency.

Fig: Configure Connection Pooling for the first Server Group

Click on the Use Fixed Credentials radio button and enter the Bind DN and Password for the user that has appropriate access to this directory server. For this tutorial situation, we will not need to create a large pool of open connections, so you may want to change the number of Pool Connections from 10 to 2.

Finally, click the OK button near the top of the application to store your changes for this Server Group.

Create the RDBMS Server Group

Click on the Output node in the navigator tree on the left-hand side of the application and click on the New Database Connection button near the bottom of the screen. This will open a wizard which will guide you through the process of setting up the basic connection variables required for the configuration.

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: Select the appropriate database driver

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: Enter connection details

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: Enter a mount point DN for the table data

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. In our example, we will not be using the data within the database for BIND purposes, so we can leave this empty.

Fig: Select the table and a naming attribute

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: Choose an RDN for the table

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: RDBMS Servergroup configuration screen

Note that if you want to add more tables from your configuration to the virtual LDAP branch, you can click on the LDAP Info tab to edit the options here. The information already specified in this panel relates to the configuration information that you completed in the wizard, so it should be fairly easy to see how you could go about adding another table.

Fig: Configure virtual LDAP branches for RDBMS

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

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 and will allow us to define a virtual entry that will be returned when a sub search is performed on the directory from a parent node.

Click on the Processing node in the navigation panel, and in the configuration panel, click on the button that allows you to create a New Stage. You will be prompted to enter a name for the Stage, and you will have an option to select between an Automatic or Manual stage. Choose a useful name, like "Add Entries", and leave the stage type as Automatic, since you will be making use of a bundled plugin. Click OK and your processing stage will appear in the Navigation panel on the left.

When you click on an Automatic processing stage in the navigation panel, you will be presented with the option to Add Plugin in the configuration panel. Clicking on this button will bring up the Plugins dialog. You can scroll through the options here to find a plugin suitable for the functionality that you want to build into your solution. In this case, look for the Add Entries plugin.

Fig: Add the Add Entries plugin

Once you have added the plugin, it should appear as a node in the navigation panel connected beneath your processing stage. If you click on it, you will be able to access the configuration options for the plugin.

Fig: Configure the Add Entries plugin

All plugins have some common configuration options. At the top of the plugin configuration panel, you will see that you are able to define different conditions for which the plugin will be triggered. For now we can leave these options empty.

There is also an option to set the Debug Level for the plugin. This will control how verbose the debug reporting for the plugin is in the STDOUT log file. For now, we can leave the debug level at its lowest setting.

Click the New Virtual Entry button near the bottom of the screen, and enter "mysql" or some other relevant name in the dialog that pops up. This will create a 'virtual entry' node in the navigation panel, which you can click on to configure.

In the Entry DN field, enter the DN that you have used to attach your RDBM data, in the wizard earlier. In our case, this was: "ou=MySQL,dc=my_organization,dc=com".

Fig: Configure a Virtual Entry in the Add Entries plugin

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

Create a second Attribute type called "ou" and assign it the value "mysql" to match your naming attribute.

Listener Configuration

The final part of our configuration will be to define how a client application can connect to the Virtual Directory. In the Input part of the configuration, we will define a Listener that can accept client connections.

Click on the Input node in the navigation panel, and click on the New Listener button near the bottom of the screen. You will be prompted for a name for your listener, which you can choose to your liking. You can change this at any point in the future, if you need to.

Once the Listener has been created, it will appear as a node in the navigation panel. Click on the Listener node to access its configuration panel.

Fig: Configure the new Listener

Under the Main Listener Properties tab, although there are many options here, we only need to make a small number of changes. Firstly, make sure the Protocol is set to ldap, so that the Listener only accepts LDAP requests. Next, set the Listen Port to 3890 (which will prevent any conflict with locally hosted LDAP servers, and will ensure that you have permission to run this software as a TCP service). Finally, set the Default Server Group by clicking on the dropdown box and selecting the Server Group that hosts the LDAP Directory. In our case, this is the common employee user account directory, which is contained in the SunDSEE Server Group.

Now click on the Attached Stages tab. Here you can specify which processing stages should be attached to the Listener, and in what order they should be invoked. In more complex solutions, you may want to use multiple Listeners that have different processing functionality attached in different orders.

Fig: Attach the Processing Stages to the Listener

In this situation, we only have a single processing stage defined, so in the table, double-click on the first row, and select the processing stage from the dropdown box. Click OK, to store the changes to your Listener configuration, and finally save the configuration.

Launch and Test Configuration

At this point, you should have a working configuration. All that remains is for you to start it up and test it. Click on the Run button, or select the Run option from the Process menu in the menu bar. If everything goes well, the VDS instance should start up and will listen for LDAP requests on its Listener interface. It will also open a set of connections to your backend directories, as defined by your Connection Pool settings.

To test the configuration and to see the RDBMS table attached to the virtual branch that you have created, open up Symlabs LDAP Browser by clicking on the Launch LDAP Browser button or by selecting it from the Extras menu in the menu bar.

Configure a connection to connect to the locally hosted VDS instance.

Fig: Use the LDAP Browser to connect to your running VDS instance

In the Host field, type either 'localhost' or '127.0.0.1'. In the Port field, specify the port number that you defined for the Listener, '3890'. For the User id and Password fields, specify BIND credential appropriate for the directory that is your default Server Group. And finally, in the Suffixes field, specify the Base DN for your LDAP directory. Finally click Connect.

You can now browse the directory to see that all of your usual data is available. You will also notice that a new 'ou=mysql' branch has been added to the tree. If you expand this branch you will be able to see that your database table has been listed as a child node to this branch. Finally, expanding this node will allow you to view entries that are directly located within the table, as if they were standard LDAP entries.

Fig: 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.

TOP

Tutorial #4 - Integrating an RDBMs Into an LDAP Tree

Collating RDBMS Data Into an LDAP Tree

Click here to download this tutorial as a PDF file.

Overview

In the previous tutorial, we explored how Symlabs Virtual Directory Server is capable of presenting data from a relational database as if it were stored in a branch on an LDAP directory tree. Once data can be presented within a directory tree, it is possible to apply a range of functionality within the VDS to manipulate how the data is presented to a client application. In this tutorial, we will explore how information stored in a table on a relational database can be collated using the Join Entries plugin, so that data common to a single identity is presented as a consolidated entry.

Building on the configuration in the previous tutorial, we will present a fairly complex scenario that will be solved easily using Virtual Directory Server. Consider that while we have attached a directory and a relational database to the virtual tree, there is no common attribute that we can use to associate the data. Let's assume that there is a second LDAP directory that is used to store accounting records for each user stored within our directory infrastructure. The database stores records related to each user's leave or vacation time within an organization, and these records contain an employee identity number. This can be related to the employee identity number used to store records in the accounting directory. Finally, data in the accounting directory can be related to employee data stored within the primary user directory based on the email address used within the company, because we know that the mail address is unique to each user, and is stored in both directories.

In order to present a single consolidated view of each user's identity information, we will use the Join Entries plugin twice. First, we will join the data for each entry in the accounting directory to the corresponding entry in the primary user directory, using the 'mail' attribute as a join key. Then we will join corresponding records in the relational database to the entries in the accounting directory using the employee id as a common attribute.

Before you begin

This tutorial builds directly on top of the configuration used in the previous tutorial, titled Tutorial #3 - Integrating RDBMS into an LDAP Environment. This means that you should ensure that you are able to build a solution similar to this and that it is actually working, before you continue.

In this tutorial, we will be adding a second LDAP directory to the solution. Of course, this directory needs to be running and should be accessible to the Virtual Directory Server system. Furthermore, we will be performing two join functions within the tutorial. These functions will be based on an attribute that is common to entries in your primary LDAP directory, and on an attribute that is common to a field for records in your relational database table.

While your environment is likely to differ considerably, and the presentation here will need to be adapted to your systems as you move through the tutorial, keep in mind that in order for this to work you will need to be able to find commonly used attributes. If your environment does not match this scenario perfectly, please feel free to contact Symlabs to obtain the data that will allow you to set up a similar demonstration environment, or to chat about an alternate approach to solving a similar problem within your own environment.

Open the Existing Configuration from Tutorial 3

Click File on the menu bar, then click Open, and then click on Open Local Config. The local configuration menu will open, which will allow you to select the configuration from the previous tutorial.

If you did not complete the previous tutorial, please go back and ensure that you create a working configuration that looks similar to it before you continue.

Configure an additional ServerGroup

In our existing configuration, we already have two ServerGroups defined under the Output section. One of these contains our primary LDAP server, onto which we have attached data from the RDBMS. The second ServerGroup is used to define the connection to the database, and to determine which tables should be mapped onto the directory tree.

Now we need to configure an additional LDAP ServerGroup to connect our second LDAP directory to the solution. Click on the Output node in the navigation tree, and then click on the New Server Group button. Name the new ServerGroup appropriately, so that it is easy to identify later. Ensure that the ServerGroup is set to Automatic, and click OK. The new ServerGroup will appear under the Output node in the navigation panel. Click on it, to begin editing the configuration parameters.

On the Servers tab, enter the IP address or hostname for the second LDAP server where your accounting data is stored. And specify the port number on which the LDAP server is listening. In our example, on our demo system, the OpenDS directory is running on the same system as the VDS so the hostname is entered at 'localhost' and the port number is '3892'. Remember, that in your own environment, this is likely to differ.

Fig: Configure the secondary LDAP Server Group

Now click on the Connection Pooling tab and check the Use Connection Pooling checkbox. Connection pooling will open a number of connections to the backend directory and will keep them open and ready for request routing. This is prevents a new connection from being opened for each request that is processed by the VDS instance, and helps to improve efficiency.

Fig: Configure Connection Pooling for the secondary LDAP Server Group

Click on the Use Fixed Credentials radio button and enter the Bind DN and Password for the user that has appropriate access to this directory server. For this tutorial situation, we will not need to create a large pool of open connections, so you may want to change the number of Pool Connections from 10 to 2.

Finally, click the OK button near the top of the application to store your changes for this Server Group.

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 each hosting a Join Entries plugin. The first stage will be used to join data from entries in the second LDAP server, to the data presented for primary LDAP directory. We will use the 'mail' attribute as a join key. The second stage will be used to join data stored in the records of the RDBMS, into the entries returned by the secondary 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.

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. In this case, we will be joining data from the secondary LDAP directory to data in the primary LDAP directory, and we have identified the 'mail' attribute as being common to both directories, and containing unique data for each user.

Click on the Processing node in the navigator tree, and then click on the New Stage button near the bottom of the screen. You will need to provide a relevant name for this stage, so choose something that will be easily identifiable later. In this case, we have chosen to label the stage 'Join LDAP Entries'. Leave the stage type as Automatic, and click the OK button.

The new stage will appear in the navigation tree under Processing. Click on it, and then click on the Add Plugin button. This will bring up a dialog listing all of the available plugins. Scroll through the plugins, until you see the Join Entries plugin and click OK.

Fig: Add the Join Entries plugin

The new plugin will appear as a node, called 'JoinEntries', listed under your processing stage. Click on it to begin configuring the parameters required to use this functionality.

Fig: Configure the Join Entries plugin

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 second LDAP directory 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 from a single LDAP directory. The Join will only be applied when any application makes a request for this DN.

Under the Join Entries Main Configuration section, enter an attribute in the Primary Join Attribute textbox. In our example, we know that the 'mail' 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 primary LDAP directory. If the attribute is not used as the RDN (or naming attribute) uncheck the checkbox, otherwise leave it checked. In our case, the 'mail' attribute is not used in the RDN, so we have unchecked this option.

In the Aggregated Attributes list, you are able specify attributes that you may wish to aggregate from the two directories. For instance, it is possible that the secondary directory contains one or more different telephone numbers for a user, that differ from the numbers stored from the same user in the Primary directory. In order to ensure that all numbers are preserved during the join, we will aggregate the 'telephonenumber' attribute. For attributes that are not aggregated, the value of the attribute in the directory that is given precedence will be displayed. You can change which directory is given precedence in the Order of Precedence field on the right.

Click the OK button near the top of the screen to store the configuration parameters that you have set so far, and then click on the New Foreign Data Group button. A dialog will appear, allowing you to enter a name for the foreign data group. Enter a meaningful name here, such as the name of the ServerGroup where your secondary data is stored.

The Foreign Data Group that you have created will appear in the navigation panel under the JoinEntries plugin. If you click on this node, you can start to configure the parameters to join data from the secondary LDAP directory.

Fig: Configure the Foreign Data Group

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.

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. In this case, we will accept that this solution would be implemented for a read-only scenario.

In the Server Group drop-down box, select the secondary ServerGroup to determine where the additional information should be fetched from. And finally, Enter the Base DN where information should be fetched from. This is obviously the DN where the user entries are stored in the Directory, for which you are performing the join.

You will notice that some other configuration tabs are available here. For READ operations, you are able to specify exactly which attributes should be accessible within the secondary directory. This can help to limit access to more sensitive data, and can also be used to control which attributes are used in the join. You are also able to insert 'virtual attributes' and values. This can be used in a variety of ways, including using virtual attributes to indicate that an entry consists of attributes retrieved from more than one directory. Since we are not implementing this solution for WRITE operations, you needn't edit the configuration here, needless to say that in an alternate solution, you could use this tab to control which attributes were actually modifiable on the secondary LDAP server.

Fig: It is possible to configure controls over which attributes are accessible in the final solution.

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

Add a Second Join Entries Stage

In the previous configuration step, we added the first Join Entries stage, which will ensure that when a client makes a request for an entry in the primary directory, the VDS will also query the secondary directory and will use the Join attribute ('mail') to add data stored in the secondary directory into the result that will be returned to the client.

We also want to include data that is stored in the MySQL database, in the final result. In order to achieve this, we will create a second Join Entries stage. This stage will intercept queries on the secondary directory, and will use the 'mycompemployeeid' attribute to join records in the MySQL database table with a matching 'eid'. Since the MySQL table is already connected to the solution and expressed as an LDAP branch, this process should hardly differ from the previous step.

Click on the Processing node in the navigator tree, and then click on the New Stage button near the bottom of the screen. You will need to provide a relevant name for this stage, so choose something that will be easily identifiable later. In this case, we have chosen to label the stage 'Join MySQL'. Leave the stage type as Automatic, and click the OK button.

The new stage will appear in the navigation tree under Processing. Click on it, and then click on the Add Plugin button. This will bring up a dialog listing all of the available plugins. Scroll through the plugins, until you see the Join Entries plugin and click OK.

The new plugin will appear as a node, called 'JoinEntries', listed under your processing stage. Click on it to begin configuring the parameters required to use this functionality.

Fig: Configure the second Join Entries plugin

Under the Condition section, enter the DN that is used to store user data, in the secondary 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, it will appear as if it has come only from the LDAP repository. Since this processing stage will appear after the first Join, when the first Join plugin requests data from the secondary LDAP directory this processing stage will come into effect and will present results that include the MySQL data.

Under the Join Entries Main Configuration section, enter an attribute in the Primary Join Attribute textbox. In our example, we know that the 'mycompemployeeid' attribute matches the 'eid' field in the database. This means that we can use this attribute to join our two datastores. In this case, the attribute is used as the RDN, so we can leave the checkbox checked. Click the OK button near the top of the screen to store the Main Entry configuration.

Click on the New Foreign Data Group button and enter a name for the new foreign data group (e.g. Mysql) and then click the OK button. The newly created foreign data group will appear in the navigation panel under the Join Entries plugin.

Fig: Configure the Foreign Data Group for MySQL

Enter the appropriate attribute in the Primary Key Attribute: section. In our case, we are joining the data based on the 'eid' which maps onto the 'mycompemployeeid'. Once again, this value is actually used as the RDN, so we can leave the checkbox checked.

In the Server Group drop-down, you can select the ServerGroup that you set up to contain the relational database. And finally, select the Base DN where the information should be fetched from. This DN is the same as the one that the MySQL table is mapped to, so in our example this would be: 'ou=employee_data,ou=MySQL,dc=my_organization,dc=com'

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

Listener Configuration

We're almost done with the configuration now. All that we need to do is attach the new processing stages to the Listener in the order that we want them to be executed.

Expand the Input node in the navigator tree on the left of the GUI; and click on listener that we defined in the previous tutorial. It should be mostly configured from the work we did previously, so we should only need to go to the Attached Stages tab and edit the list of attached stages.

Beneath the 'AddEntries' stage that we added previously, double-click where it shows to do so and click on the 'Join LDAP Entries' stage in the dropdown box. Repeat the step to add the 'Join Mysql' option to the stages pipeline.

Fig: Attach the Processing Stages to the Listener

Click the OK button near the top of the screen to store the Listener configuration. Finally, click on the Save button to make sure that all of your changes have been saved to file and will be read by the proxy engine when you start the configuration.

Launch and Test Configuration

At this point, you should have a working configuration. All that remains is for you to start it up and test it. Click on the Run button, or select the Run option from the Process menu in the menu bar. If everything goes well, the VDS instance should start up and will listen for LDAP requests on its Listener interface.

To test the configuration and to see that the Join plugins are working as expected, open up Symlabs LDAP Browser by clicking on the Launch LDAP Browser button or by selecting it from the Extras menu in the menu bar.

Configure a connection to connect to the locally hosted VDS instance.

Fig: Use the LDAP Browser to connect to your running VDS instance

In the Host field, type either 'localhost' or '127.0.0.1'. In the Port field, specify the port number that you defined for the Listener, '3890'. For the User id and Password fields, specify BIND credential appropriate for the directory that is your default Server Group. And finally, in the Suffixes field, specify the Base DN for your LDAP directory. Finally click Connect.

You can now browse the directory to see that all of your usual data is available. If you expand the branch where you have configured your join and click on one of the entries, you should notice that additional attributes appear under the entry. Check that the attributes contain the data that you expect to retrieve from the secondary LDAP server and from the MySQL database.

Fig: Data from the MySQL database is joined to the data for a user Entry using VDS

As already mentioned, the attributes that have been added to this result have names that may not appear in the schema reported by the default ServerGroup. If this was a problem for the application that was accessing the data, we could approach it in a number of ways. The most simple approach would be to use the Attribute Mapping plugin to simply map the attribute names onto something unused within the existing schema. A more complex solution could involve dynamically editing the results returned in a schema query to include the new attributes.

TOP

Tutorial #5 - Working with Remote Configurations

Click here to download this tutorial as a PDF file.

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

Virtual Directory Server is installed and configured properly; VDS is currently running.
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).
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.
Port 9443 is available on the Remote Virtual Directory Server Host.
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.

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.
Within this file, regardless of the Operating System, are the following lines:
dn: cn=administrator,o=dsproxyremote user: demanager passwd: admin123
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'.
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.

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 ﬁrst 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.

Click on File in the File menu at the top of the GUI, and select Preferences from the dropdown menu.
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
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
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.
Click the OK button.
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.
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.

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

TOP

Tutorial #6 - Sharepoint Integration with Symlabs Enabled Identity Stores

Sharepoint Integration with Symlabs Enabled Identity Stores

Click here to download this tutorial as a PDF

Overview

Symlabs Virtual Directory Server and LDAP Proxy can be used to facilitate the integration of Sharepoint Portal, or MOSS (Microsoft Office Sharepoint Server), within an environment that includes more than one Active Directory identity store where trust relationships have not been established between different domain controllers. Symlabs LDAP Proxy will allow Sharepoint Portal to integrate with any LDAP identity store, while Symlabs Virtual Directory Server can be used to all Sharepoint Portal to integrate with relational database backend repositories.

Sharepoint Portal is capable of using one of three authentication modes: Windows, Forms and Web SSO. Traditional intranet deployments use the default Windows authentication mode, which allows authenticated Windows domain users to access the Sharepoint Portal linked to that domain without being challenged for credentials. To give access to users from different domains, the Sharepoint administrator will need to extend the web application to a different zone (usually to the "extranet") and will usually make use of the Forms authentication mode for that zone. The administrator will need to select a 'Membership and Role Provider'. Microsoft provides two such implementations: a AspNetSqlProvider and the LdapProvider. These implementations work as advertised but have the constraint that they can only use one identity store.

In this document we explain how it is possible to extend Microsoft's LdapProvider Membership and Role Provider implementation, so that it is capable of integrating with more than one identity store, by using the Symlabs Virtual Directory Server product to aggregate identity stores so that they look like one to Sharepoint. It is important to note, that this solution is also achievable using Symlabs LDAP Proxy, but you will be limited to working only with LDAP data stores.

Configuring Virtual Directory Server

In order to allow Microsoft LdapProvider to use multiple backend identity stores, including RDBMS servers, we will need to configure Symlabs Virtual Directory Server in such a way that data from all of the different backend repositories is presented as belonging to a single tree.

Let's consider that we need to give Sharepoint access to users stored in two external Active Directory instances, that are not already linked as the local Active Directory store that Sharepoint is already using. These two ADs belong to two independent domains, partnerone.com and partnertwo.com. Users for both ADs are stored in the CN=Users branch on each directory. We will configure Virtual Directory Server to aggregate the data stored in each of these branches using the MergeTrees plugin that comes bundled with the software.

Plugins are useful components that are bundled with Symlabs products to encapsulate commonly used functionality. These plugins can be configured using the graphical interface within the DSGUI configuration and management tool, without requiring an administrator or developer to write a single line of code.

The MergeTrees plugin is capable of aggregating the entries stored in different branches on different servers and mapping them onto a single "mount point" entry or node within an existing directory. To keep this example configuration simple, we will use the local Active Directory to create a mount point entry that can be used by the MergeTrees plugin. Simply open your local "Active Directory Users and Computers" and create two organizational units under the root. To do this, right click the root node and select "New => Organizational Unit". Name the first node "AllUsers", and the second node "AllGroups". The local Active Directory instance is now ready to interact with the Virtual Directory to present a unified set of Users and Groups from each of your backend Active Directory instances.

Fig-1: Setting up mount points in Active Directory

Open the DSGUI Management Console and create a new Virtual Directory Server local configuration. This will open a new configuration with the Input, Processing and Output nodes on the left, in the navigation panel.

Under the "Output" node, you will need to add three server groups. One for each external AD (partnerone.com and partnertwo.com) and the third one for the local AD (mycompany.com). For each server group, you will need to provide the IP address or hostname of each Active Directory server and the port number (usually 389) on which the AD instance is listening.

Fig-2: Create three server groups in the output configuration

Under the "Input" node of the configuration, you will need to add a new listener. The listener will be the interface on the Virtual Directory Server instance that the Microsoft LdapProvider, for your Sharepoint Portal, connects to. As you are running a local instance of Active Directory, it is likely that you will need to set the Listener port to something other than the port being used by Active Directory (try setting it to 3890). You should also select a default Server Group that should be used to route all incoming traffic to. In this case, select the server group that you configured for the local Active Directory instance within the Output part of your configuration.

Fig-3: Set the default server group in the Listener

Now we are ready to add the MergeTrees plugin. Under the Processing node in the configuration, you will need to add a new 'Automatic' stage, which you can name something useful like "Aggregation". Once you have added the stage, you will be able to click on the Add Plugin button in the configuration panel and select the Merge Trees plugin. Rename the plugin entry in your configuration to something relevant to its use, something like 'Allusers'.

The plugin configuration panel offers a variety of configuration options. In order to limit the plugin functionality to requests for entries from the DN "ou=allusers,dc=mycompany,dc=com", you will need to enter this DN within the BaseDN field in the Conditions section of the panel. You also need to enter this DN into the Joined Tree DN field in the Merge Trees Configuration section of the configuration panel. You will notice that this DN points to the the "AllUsers" OU that we created on the local AD instance.

Beneath the Joined Tree DN field, you will notice three checkboxes. All three boxes should be checked. By default, two of these boxes will already be checked, and as we will be using the new branch for authentication purposes, you should also check the BIND Support option.

Fig-4: Configure the MergeTrees plugin to aggregate all users

Finally, you are able to select the branches that you wish to aggregate from each of the external server groups that you wish to be able to use with the LdapProvider. So, add the DN for the users stored on the first external AD instance, "cn=users,dc=partnerone,dc=com" and select the servergroup that contains this entry from the list of server groups that you created in the Output configuration. Now add an entry for the second external AD, "cn=users,dc=partnertwo,dc=com" and select the appropriate servergroup that contains this entry from the list of server groups that you created in the output configuration.

This configuration will now be capable of merging all of the users from your external Active Directories into a branch accessible within a virtual representation of your local Active Directory instance. However, in order for Sharepoint to function properly, you will also need to aggregate Group information. To do this, you simply need to add another Merge Trees plugin to the same processing stage that you have already created. Rename it to something like "Allgroups".

Now you will need to limit the plugin functionality to requests for entries from the DN "ou=allgroups,dc=mycompany,dc=com", by entering this DN within the BaseDN field in the Conditions section of the panel. You also need to enter this DN into the Joined Tree DN field in the Merge Trees Configuration section of the configuration panel.

Now select the "group" branches that you wish to aggregate from each of the external server groups that you wish to be able to use with the LdapProvider. So, add the DN for the groups stored on the first external AD instance, "cn=groups,dc=partnerone,dc=com" and select the servergroup that contains this entry from the list of server groups that you created in the Output configuration. Now add an entry for the second external AD, "cn=groups,dc=partnertwo,dc=com" and select the appropriate servergroup that contains this entry from the list of server groups that you created in the output configuration.

Fig-5: Configure the MergeTrees plugin to aggregate all groups

At this point, the configuration of your Virtual Directory Server instance is almost complete. However, as most Active Directory configurations will not allow anonymous searches, we may need to cater for the fact that in many cases, the searches originating from Sharepoint will be anonymous. Note that Sharepoint with Service Pack 1 allows for authenticated searches but this only works where there is just one LDAP server, in which case a virtual directory is generally not needed. To handle this constraint we can add a "Connection Pool" to each server group. The connection pool can be configured to use fixed credentials, which will ensure that all anonymous connections are authenticated using the specified credentials. Connection Pools can be configured on the Connection Pool tab for each server group that you have in the Output configuration.

An alternative, and cleaner, approach to this problem is to make use of the AddCredentials plugin. In this case, you will simply need to create a second 'Automatic' processing stage within your configuration. You could call this stage something like 'binding', and then add the AddCredentials plugin to it. In the AddCredentials configuration panel, change the name to BindMyCompany, fill the Base DN field in the Conditions section with "dc=mycompany,dc=com" and then provide the BIND credentials that should be used in the Add Credentials Configuration section. Under the same stage you will need to add another AddCredentials plugin for each of the external AD instances, partnerone.com and partnertwo.com.

Fig-6: Configure the AddCredentials plugin to provide BIND credentials to authenticate anonymous Sharepoint access

Make sure to attach the stages to the listener defined earlier, save, and start the configuration.

Fig-7: Don't forget to attach your processing stages

Configuring and Testing Sharepoint

In the Central Administration page of your Sharepoint installation extend the application, that you wish to share with your partners, to the extranet zone. By default the extranet zone uses Windows authentication. To change that go to the list of Authentication Providers for the application you have just extended, select the extranet zone, and change the authentication type to Forms. In the "Membership provider name" enter SymlabsLDAPMembership and in the "Role manager name" enter SymlabsLDAPRole (these names can be anything as long as they match the names in the web.config files described next).

Fig-8: Membership Provider and Role Manager Names

To complete the configuration you will need to edit the web.config files for the Administration, internal and external site. Under the <PeoplePickerWildcards> node of these web.config files add the following keys:

 <PeoplePickerWildcards> <clear /> ...... <add key="SymlabsLDAPMembership" value="*" /> <add key="SymlabsLDAPRole" value="*" /> </PeoplePickerWildcards>

These are necessary so that searches can be done against users and groups, as happens when giving access rights to users or roles.

Edit the web.config of the Administration site so that the <membership> and <roleManager> provider entries (inside the <system.web> node) look similar to this:

 <system.web> ............ <membership> <providers> <add name="SymlabsLDAPMembership" type="Microsoft.Office.Server.Security.LDAPMembershipProvider, Microsoft.Office.Server, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71E9BCE111E9429C" server="svds.mycompany.com" port="3890" useSSL="false" userDNAttribute="distinguishedName" useDNAttribute="false" userNameAttribute="userPrincipalName" userContainer="ou=allusers,dc=mycompany,dc=com" userObjectClass="person" userFilter="(ObjectClass=person)" scope="Subtree" otherRequiredUserAttributes="sn,givenName,cn" /> </providers> </membership> <roleManager enabled="true" defaultProvider="AspNetWindowsTokenRoleProvider"> <providers> <remove name="AspNetSqlRoleProvider" /> <add name="SymlabsLDAPRole" type="Microsoft.Office.Server.Security.LDAPRoleProvider, Microsoft.Office.Server, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71E9BCE111E9429C" server="svds.mycompany.com" port="3890" useSSL="false" dnAttribute="distinguishedName" groupNameAttribute="cn" groupMemberAttribute="member" userNameAttribute="userPrincipalName" groupContainer="ou=allgroups,dc=mycompany,dc=com" groupObjectClass="group" groupFilter="(ObjectClass=group)" scope="Subtree" /> </providers> </roleManager> ............ </system.web>

Note that we have specified the servername and portnumber that the Virtual Directory Server instance is running on. You will, no doubt, need to change these settings to match your own configured environment.

Similarly edit the web.config of the internal and external sites with the following entries (inside the <system.web> node):

 <system.web> ............ <membership defaultProvider="SymlabsLDAPMembership"> <providers> <add name="SymlabsLDAPMembership" type="Microsoft.Office.Server.Security.LDAPMembershipProvider, Microsoft.Office.Server, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71E9BCE111E9429C" server="svds.mycompany.com" port="3890" useSSL="false" userDNAttribute="distinguishedName" useDNAttribute="false" userNameAttribute="userPrincipalName" userContainer="ou=allusers,dc=mycompany,dc=com" userObjectClass="person" userFilter="(ObjectClass=person)" scope="Subtree" otherRequiredUserAttributes="sn,givenName,cn" /> </providers> </membership> <roleManager defaultProvider="SymlabsLDAPRole" enabled="true" cacheRolesInCookie="false" cookieName=".PeopleDCRole"> <providers> <add name="SymlabsLDAPRole" type="Microsoft.Office.Server.Security.LDAPRoleProvider, Microsoft.Office.Server, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71E9BCE111E9429C" server="svds.mycompany.com" port="3890" useSSL="false" dnAttribute="distinguishedName" groupNameAttribute="cn" groupMemberAttribute="member" userNameAttribute="userPrincipalName" groupContainer="ou=allgroups,dc=mycompany,dc=com" groupObjectClass="group" groupFilter="(ObjectClass=group)" scope="Subtree" /> </providers> </roleManager> ............ </system.web>

Once again, note that we have specified the servername and portnumber that the Virtual Directory Server instance is running on. You will, no doubt, need to change these settings to match your own configured environment.

In the above configuration files we chose userPrincipalName, which looks like an e-mail address, as the userNameAttribute. This means that users should use their userPrincipalName (say, john@partnerone.com) as their login account. We could equally have chosen the usual sAMAccountName but since users from different ADs can have the same sAMAccountName that choice might have been prone to problems.

When you have finished editing these files and making changes to your configuration, you will need to restart IIS before the changes will become apparent. Once you have restarted IIS, you should test your configuration by giving access rights to users and groups (roles) and trying to login as such users or users of such groups. For instance, ask your partners to create accounts for John and Mary (say, john@partnerone.com and mary@partnertwo.com). Ask PartnerTwo to create the group PartnersUsers and add Mary to it. Ask the administrator of your internal Sharepoint site to give access to user john@partnerone.com and to group PartnersUsers. Once this has been done, you should see the names being resolved and that these appear underlined. By hovering the mouse over the resolved names, you will be able to confirm that the LDAP Membership and Role providers are being used.

Fig-9: Giving LDAP Based Role Access Right to a Group

Finally, try to login as john@partnerone.com and mary@partnertwo.com. In the first case you will be given access on an individual basis. In the second case the access is given on a role basis.

Conclusion

With the configuration suggested in this document, it should be clear that by using Symlabs Virtual Directory Server, you are able to quickly add further external Active Directory instances to the VDS configuration to rapidly provision access to your Sharepoint portal without needing to configure trust relationships between your domains, and with little impact on the existing infrastructure.

For questions and help in integrating Sharepoint with multiple Active Directory and LDAP server instances, or to enable authentication against identity information stored within relational databases, please contact support@symlabs.com.

TOP

Tutorial #7 - Create a unified login resource for two different Active Directory instances

Tutorial #7 - Create a unified login resource for two different Active Directory instances using a Virtual Tree

Click here to download this tutorial as a PDF file.

1 Overview

While it is possible to provide a single authentication resource for multiple Active Directory instances, using only Active Directory, doing so requires that you configure complex trust relationships between the different Active Directory instances that you would like to pool together. Often this can be time consuming and difficult to administer, particularly if all you require is the ability to allow users to authenticate regardless of which Domain they belong to. Furthermore the trust relationship between Domains might have some implications that you want to avoid, when the only real requirement is to have a single place to access the user information of all the Domains. In this tutorial we will explore how you are able to use Symlabs Virtual Directory Server to unify the data stored in two different domains without any need to configure trust relationships between the domains. To do this, we will create a Virtual Tree that can present data from either of the backend Active Directory servers. This solution is highly scalable and can accommodate as many branches and Active Directory instances as required.

In this tutorial, we have set up two domains running on different Active Directory instances hosted on Windows 2003 Servers. The first instance is for a domain called MyCompany, while the second is for a domain called PartnerComp. The MyCompany domain contains users within an organizational unit branch called Managers, while the PartnerComp users are stored across a number of different branches within the Directory. The goal of this tutorial will be to create a virtual tree that contains all of the users stored in each of the different branches on the two Active Directory instances.

Fig-1: Users in the MyCompany domain are stored in a single branch called Managers

Fig-2: Users in the Partnercomp domain are stored in a number of different branches, including Accounting, Sales, Managers and Development.

It is worthwhile noting that while this tutorial is presented for Virtual Directory Server, all of this functionality is available in Symlabs LDAP Proxy and an identical configuration could be used in this environment if required.

2 Create A New Configuration

We will begin by creating a new configuration and attaching the two Active Directories to it as two different ServerGroups.

Click File on the menu bar, then click New.
Click the OK button when asked which server you want to create the new configuration on (the default server is Local).
Enter AD-VirtTree for the filename when prompted, then click the Save button and the following will appear:

Fig-3: 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 two separate Server Groups that will contain each of our Active Directory instances.

Click on the Output button on the left-hand side of the application and then click on the New Server Group button near the bottom of the screen.
Label the first servergroup as 'MyCompany' and ensure that the ServerGroup type is set to Automatic.
Click on the MyCompany node in the Output section in the configuration navigator to enter the configuration panel for the new Server Group.

Fig-4: Configure the MyCompany server group
Verify that the Protocol is set to ldap.
Under the Servers tab, enter the Hostname / IP Address and the port number (389) for the Active Directory instance that hosts the MyCompany domain.
Click on the Connection Pooling tab and check the 'Use connection pooling' option.
Select the option to 'Use fixed credentials' and enter the Bind DN and password of a trusted user in the MyCompany domain.

Fig-5: Add Connection Pooling to the Server Group

Click OK and then click on the Output node to add another server group.
Label the second servergroup as 'PartnerComp' and ensure that the ServerGroup type is set to Automatic.
Click on the PartnerComp node in the Output section in the configuration navigator to enter the configuration panel for the new Server Group.

Fig-6: Enter the details for the PartnerComp Active Directory instance
Under the Servers tab, enter the Hostname / IP Address and the port number (389) for the Active Directory instance that hosts the PartnerComp domain.
Click on the Connection Pooling tab and check the 'Use connection pooling' option.
Select the option to 'Use fixed credentials' and enter the Bind DN and password of a trusted user in the PartnerComp domain.

Fig-7: Enter connection pooling details for the PartnerComp domain
Click the OK button near the top of the application to save the ServerGroup configuration to memory.

3.2 Listener Configuration

The listener will provide the interface that LDAP clients are able to connect to in order to have access to the virtual tree that we will create.

Click on the Input button on the left-hand side of the application, and then on the New Listener button near the bottom of the screen.
Enter VirtualTree for the new input / listener and then click the Okay button.
Click on the VirtualTree button on the left-hand side of the screen and the following will appear:

Fig-8: Listener configuration

Under the Main Listener Properties tab, make sure the Protocol is set to ldap.
Under the Main Listener Properties tab, set the port to 3890.
Under the Main Listener Properties tab, in the Routing Information box, select the Virtual Tree option.
Click the OK button near the top of the screen to save the Listener configuration.

4 Create a Virtual Tree

You will now need to define a Virtual Tree that will be attached to the listener that you have created. You can get started by clicking on the New Virtual Entry Root button in the Routing Information box on the Main Listener Properties tab of your new listener. This will prompt you for a name for the root entry of your Virtual Tree. This should be the base DN that you wish to use for your tree. In this example, we will use dc=virtcomp,dc=com.

Once you have created the root entry for your Virtual Tree, it should appear in the navigation panel on the left. Click on it, and you will be able to edit the attributes for the virtual entry. You should, at least, define an 'objectclass' attribute and specify the base naming attribute. The objectclass attribute, in this case, can have the values 'top' and 'domain'.

Fig-9: Editing the Virtual Entry Root

You are now able to create a virtual entry, within your Virtual Tree, by simply right-clicking on the root of your virtual tree and clicking on the New Virtual Entry option in the context menu. Use this to create an entry with the RDN 'ou=People'.
As with the root entry, you will need to edit the attributes for your virtual entry, creating an objectclass and a naming attribute. In this case, we are defining an 'organizationalunit' as the objectclass, and the naming attribute 'ou' will have the value 'People'.

Fig-10: Adding and editing a Virtual Entry or branch within your tree

Finally, it is also possible to create Virtual Mount Points within your tree. These mount points are used to create virtual branches where data stored in the backend directories can be attached to the tree. To do this, you can right-click on the virtual entry 'ou=People' in the virtual tree, and select the option to Add a Virtual Mount Point, from the context menu. In this example, we will create a mountpoint for each of the User branches in both of the Active Directory instances.
Provide an appropriate RDN for each new virtual mount point. We will create mountpoints with the following RDNs: 'ou=mycomp'; 'ou=accounting'; 'ou=development'; 'ou=managers'; and 'ou=sales'.
The mountpoint 'ou=mycomp' will be used to contain all of the users stored in the single branch in the MyCompany domain. If you click on the mountpoint that you have created, you will be able to specify the ServerGroup and the DN for the data that you wish to attach. In this case, the ServerGroup should be set to MyCompany, and the DN should be: ou=Managers, dc=mycompany,dc=local.

Fig-11: Setting up a virtual mountpoint to point to the Managers node in the MyCompany domain
For each of the other virtual mount points, we will be attaching the different user branches in the PartnerComp domain. To do this, click on each mountpoint and specify the PartnerComp servergroup as the source to obtain the data, and then specify the DN where the data is stored. For instance, for the Accounting users you would specify a DN of 'ou=accounting,dc=partnercomp,dc=local'. Do this for the remaining mountpoints, ensuring that you specify the correct DN for the location of the userdata that you wish to attach.

Fig-12: Setting up a virtual mountpoint to point to the Accounting node in the PartnerComp domain

Now click on the VirtualTree node in the navigation and click to the Virtual Tree tab. Here, you may want to define a Bind Exception, to forward particular BIND requests on to a backend Server Group. In the Bind Request Exceptions section of the configuration panel, add an entry for the administrative users for each domain (e.g. cn=Administrator,cn=Users,dc=MyCompany,dc=local) and select the server group for the administrator that you are configuring (e.g. MyCompany) as the default servergroup to handle bind requests for this user. While this step is not entirely necessary at this point, as the virtualtree will handle the routing of bind requests for users within the configured tree, you may wish to add these exceptions so that you have an easy way of troubleshooting in the future.

Fig-13: Define a Bind Request Exception for your Virtual Tree

5 Testing the VirtualTree

At this point, your VirtualTree is ready to work. Applications will be able to access user data from two separate Active Directory domains, even if no trust relationship has been established between these domains. You could potentially use this configuration for authentication, or for user management purposes. However, it is best that you test that the configuration is working properly and that you are able to access the data in each of branches of the VirtualTree.

Save the configuration, and then click on the Run button to start it. When the configuration has started, you can open an LDAP Browser, such as the one included with Virtual Directory Server, and test that you are able to connect and browse the Virtual Tree. Remember that you are connecting to the Virtual Directory Server instance, so you should enter the hostname that is being used to run the instance, the port number that you configured for the listener (3890) and the Base DN for the Virtual Tree (dc=virtcomp,dc=com). For the bind DN, use one of the Administrator accounts that you configured a Bind Exception for in the last step of the configuration.

Connect to the VDS instance using an LDAP browser

Fig-14: Connect to the Virtual Directory Server instance using an LDAP browser

Once you have connected, you should be able to expand the Virtual Tree to view the ou=People branch. Under this, you will find each of the mount points that you defined in your configuration. Expand each of these to ensure that they contain the appropriate user entries for each branch, and ensure that the user entries are readable.

Fig-15: Check that the Virtual Mount Points are working and that all of the users are accessible within your virtual tree

6 Grouping users together into a single branch

While the configuration, so far, may be adequate for use by many applications, some applications may expect all of your users to be contained within a single branch. This can be easily accommodated by making use of the Merge Trees plugin that is bundled with Virtual Directory Server.

To add this functionality, we will need to make a few minor modifications to the configuration, including the addition of an automatic processing stage.

First, let's create an entry within the Virtual Tree that we will use to attach the data returned by the Merge Trees plugin. Right click on the Root Node of the virtual tree, and click Add Virtual Entry. Name the entry: ou=allusers.
Click on the new virtual entry, and click the Edit button, to add some basic attributes. Enter an attribute name: 'ou' in the left column of the table, and the value 'allusers' on the right. Also enter an 'objectclass' in the left column, and on the right enter the values 'top' and 'organizationalunit'.

Fig-16: Edit the 'ou=allusers' Virtual Entry that you have created
Click on the Processing node within your configuration navigator and click on the 'New Stage' button to add a processing stage.
Name the processing stage 'MergeUsers' and ensure that it the 'automatic' stage option is set. Click OK.
Click on the MergeUsers stage that you have created, and then click on the Add Plugin button. Scroll through the listed plugins until you see the Merge Trees plugin. Click on it and then click OK.

Fig-17: Select the Merge Trees plugin from the plugin list

Now click on the MergeTrees node that appears under your processing stage.
In the configuration panel for the MergeTrees plugin, first define a condition to only trigger the plugin for requests on the 'ou=allusers,dc=virtcomp,dc=com' BaseDN.
In the Merge Trees part of the configuration, enter the Joined Tree DN as 'ou=allusers,dc=virtcomp,dc=com'
Check the Bind Support option.

Fig-18: Configure the Merge Trees Plugin
In the table, we can define the DN of each branch that we wish to merge, and the servergroup where that branch is hosted. So, first enter 'ou=Managers,dc=MyCompany,dc=local' and select the MyCompany servergroup. Then enter 'ou=accounting,dc=partnercomp,dc=local' and select the PartnerComp servergroup. Do the same for each of the other user branches on the PartnerComp servergroup, taking care to specify the correct DN for each branch.
When you have finished configuring the plugin, click on the VirtualTree listener that you created at the beginning of the configuration.
Click on the Attached Stages tab of the configuration panel, and then in the Pre Virtual Tree Stages table, add the MergeUsers processing stage that you have created.

Fig-19: Attach the Processing Stage to the VirtualTree listener
Now click on the VirtualTree tab in the configuration panel and check the box that says 'Skip PDU with destination'. This will allow the plugin to route the requests to the appropriate backend servers before they are intercepted by the Virtual Tree.

Fig-20: Check the Skip PDU with Destination box in the VitualTree tab

You have now successfully edited the configuration to merge all of your users into a single branch hosted on the virtual tree. Save the configuration. And start it up, so that you can begin testing it.

Open an LDAP browser and, once again, connect to the Virtual Directory Server instance using the configuration information that you used earlier. You should now see that the virtual tree contains an additional node for the organizational unit called 'allusers'. If you expand this node, you will be able to see that all of the users stored across both Active Directory instances have been merged into a single branch.

Fig-21: Open a browser and test that all of your users entries appear in the 'ou=allusers' branch on your virtual tree.

You can now use this virtual branch to act as a single authentication resource for users within both domains, even if the domains have no trust relationship established between them.
TOP

Tutorial #8 - Securing a backend connection with GSSAPI

Click here to download this tutorial as a PDF file.
Click here to view a video demo of this tutorial

1 Overview

Symlabs Virtual Directory Server offers full support for Kerberos backend systems via SASL/GSAPPI. This is particularly useful when you need to secure communications between your Virtual Directory and a Kerberos enabled backend such as Microsoft Active Directory. Although it is possible to encrypt communications using SSL, this requires that you enable SSL on your Active Directory backend, which is not only a cumbersome task, but also results in a measurable performance hit. Since Kerberos is the default authentication and encryption method used within Active Directory environments, it makes sense to ensure that your connections are protected using the native facility provided.

By protecting the connection to your Active Directory backend, you will be able to perform any operation permissable within Active Directory through your Virtual Directory, including the ability to modify password entries. This means that you will be able to enable standard LDAP applications to work perfectly with an Active Directory environment.

This tutorial will explain how to configure Symlabs Virtual Directory Server v5.5 to connect to a Kerberos protected Active Directory backend using GSSAPI. In order to show how this can work across platforms we will configure the Virtual Directory instance on a Linux system and will make use of the MIT Kerberos libraries and tools to authenticate the connection so that Virtual Directory Server can create a Kerberos protected connection pool.

2 Assumptions

VDS is installed on a Linux system and is configured properly.
The MIT Kerberos library packages are installed on the VDS host system.
The Administrator following this tutorial has shell access to the VDS host.
Active Directory is configured and running and is accessible to the VDS Host.

3 Configure the VDS instance

In this example, we will configure a simple pass-thru configuration with a standard LDAP listener to handle client requests on the frontend of the Virtual Directory. We will configure a backend ServerGroup that will contain the connection details for a single Active Directory server, that will service requests for the Virtual Directory. This ServerGroup will be configured to open a connection pool that will be protected using Kerberos through GSSAPI.

Create a new configuration instance, called GSSAPI_AD_Passthru.
In the Output part of the configuration, create a New Automatic ServerGroup and call it GSSAPI_AD.
In the Servers tab, provide the hostname or IP address of your Active Directory instance and set the port to 389.

Fig-1: The Servers Tab for GSSAPI_AD.
On the SASL tab, click the SASL Enabled checkbox to enable SASL/GSSAPI. You can leave the other settings at their default values for now.

Fig-2: The SASL Tab for GSSAPI_AD.
On the Connection Pooling tab, enable the Use Connection Pooling checkbox, and select the option to Use SASL.

Fig-3: The Connection Pooling Tab for GSSAPI_AD.
Finally, in the Input part of the configuration, create a New Listener, set its listening port and set the default ServerGroup to use GSSAPI_AD.

Fig-4: Create a new Listener for your VDS instance.
Save the configuration.

4 Configure Kerberos on the VDS host

Assuming that you have already installed the required MIT Kerberos libraries on the VDS host system, the only remaining configuration step is to ensure that a Kerberos configuration file exists and that it contains the details required to open a connection to the Active Directory instance. Usually this file is stored in/etc/krb5.conf and should look something like this:

[libdefaults]
default_realm = MYCOMPANY.LOCAL
[realms]
MYCOMPANY.LOCAL = {
kdc = ADServer.Mycompany.local
}
[domain_realm]
.mycompany.local = MYCOMPANY.LOCAL
mycompany.local = MYCOMPANY.LOCAL

You will note that this example file has three sections defined:
- libdefaults: sets defaults for Kerberos on your system, e.g.,default realm, default ticket lifetime
- realms: tells where to find the KDCs for each realm
- domain_realm: maps domains to realms
You can define further sections to describe where logging should take place etc, but in order for this to work, a basic configuration such as the example provided above should suffice.
The most notable setting here is the kdc in the realms definition, which describes which system should be connected to in order to obtain a valid Kerberos ticket. In this case, it is the Active Directory instance that will be used as our backend, and it is important that the hostname is specified to exactly match the hostname as it is defined for this within Active Directory. And the VDS host should be able to resolve this hostname to the correct IP address. If you are not certain that this can be done, you can put an entry in your/etc/hosts file to ensure that this works.
In the example configuration file, substitute the MYCOMPANY.LOCAL domain and Kerberos realms to match your own Active Directory domain name.

5 Use KINIT to authenticate against Active Directory, and start your VDS instance

Now that Kerberos is properly configured, the VDS host will need to obtain a TGT (Ticket Granting Ticket) in order to continue to secure its connections to the backend Active Directory Server. This is a fairly simple process, and simply requires that you use the kinit tool provided with MIT Kerberos, in order to authenticate with Active Directory.

Open a console to access the shell.
Ensure that you are the same user that you intend to run the VDS instance as.
Use kinit to authenticate to the Active Directory instance. To do this, simply enter something similar to the following:
```
 kinit Administrator@MYCOMPANY.LOCAL
```
Naturally you should substitute the appropriate domain name, and the user that you wish to connect to the Active Directory instance as. You will be prompted for the user's password, which you should enter.
If the command runs without an error, you have successfully authenticated and the system should have a TGT that it can use to access the Active Directory and encrypt future communications.
Maximize DSGUI and start your configuration.

6 Test your VDS instance and check that GSSAPI is being used

At this point, you have authenticated the VDS Host to Active Directory using the kinit tool. When you started the VDS instance, it will have created a connection pool by opening a number of connections to the backend Active Directory server. These connections are authenticated using the credentials that were specified when you authenticated with kinit. Furthermore, each connection will be encrypted using Kerberos, which is facilitated through the SASL/GSSAPI interface provided by VDS.

All that remains is for you to test that the VDS is working properly.

Open an LDAP browser, we recommend using the bundled Symlabs LDAP Browser to test the connection.
Connect to the VDS instance, by entering the IP address or hostname of the VDS Host and the port number that you have set for the Listener. Enter the Base DN to which you wish to connect on the backend Active Directory server. Provide an appropriate BIND DN and password that you wish to use to browse the directory.

Fig-5: Open an LDAP Browser to connect to your VDS instance
Check that you are able to browse the directory through the VDS proxy that you have created.

Fig-6: Browse the VDS tree to make sure that you have access
Finally, if you wish to check that GSSAPI is being used to encrypt your backend connections, you could either increase the Debug Log Level for Automatic ServerGroups in your VDS configuration under Global Parameters, you could then check the logs of the VDS instance to ensure that SASL/GSSAPI is being used when the connections are opened; or alternatively you could use a TCP traffic sniffing application such as Wireshark to check the actual packets moving between the systems.

TOP

Symlabs Virtual Directory Server Tutorials

Tutorial #1 - Merge Users From Multiple Directories

Tutorial #1 - Merge Users From Multiple Directories

Overview

Before you begin

Create a New Configuration

Server Group Configuration

Create the first Server Group

Create the second Server Group

Processing Configuration

Listener Configuration

Launch and Test Configuration

Tutorial #2 - Fragmented Identities

Tutorial #2 - Fragmented Identities

Overview

Before you begin

Create a New Configuration

Server Group Configuration

Create the first Server Group

Create the second Server Group

Processing Configuration

Listener Configuration

Launch and Test Configuration

Tutorial #3 - Integrating RDBMS into an LDAP Environment

Overview

Before you begin

Create a New Configuration

Server Group Configuration

Create the first Server Group

Create the RDBMS Server Group

Processing Configuration

Listener Configuration

Launch and Test Configuration

Tutorial #4 - Integrating an RDBMs Into an LDAP Tree

Collating RDBMS Data Into an LDAP Tree

Overview

Before you begin

Open the Existing Configuration from Tutorial 3

Configure an additional ServerGroup

Add Processing Stages

Add Join Entries stage

Add a Second Join Entries Stage

Listener Configuration

Launch and Test Configuration

Tutorial #5 - Working with Remote Configurations

Tutorial #5 - Working with Remote Configurations

1 Overview

2 Assumptions

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

4 Start the RAS service on the Remote VDS Host

5 Configure the Local VDS Controller

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

Tutorial #6 - Sharepoint Integration with Symlabs Enabled Identity Stores

Sharepoint Integration with Symlabs Enabled Identity Stores

Overview

Configuring Virtual Directory Server

Configuring and Testing Sharepoint

Conclusion

Tutorial #7 - Create a unified login resource for two different Active Directory instances

Tutorial #7 - Create a unified login resource for two different Active Directory instances using a Virtual Tree

1 Overview

2 Create A New Configuration

3.1 Server Group Configuration

3.2 Listener Configuration

4 Create a Virtual Tree

5 Testing the VirtualTree

6 Grouping users together into a single branch

Tutorial #8 - Securing a backend connection with GSSAPI

Tutorial #8 - Securing a backend connection with GSSAPI

1 Overview

2 Assumptions

3 Configure the VDS instance

4 Configure Kerberos on the VDS host

5 Use KINIT to authenticate against Active Directory, and start your VDS instance

6 Test your VDS instance and check that GSSAPI is being used