How to create a "basic" Virtual Tree (134906)

How to create a "basic" Virtual Tree

What are the steps to configure a Virtual Tree in One Identity Virtual Directory Server?

Note: The following steps will result in a configuration equivalent to the "sample.virtualtree" sample configuration provided with version 6.1 of the product.  This is a basic sample and may lack the functionality required for your purposes.  This article is provided for demonstration purposes only. 


Create A New Configuration

Begin by creating a new configuration and attaching the two Active Directories to it as two different DataSources (formerly Server Groups).

Click File on the menu bar, then click New | New Local Config...:

Give the new configuration a name, then click the "New Config" button:




DataSource Configuration

DataSources are the directories where your user information is stored.  Examples include Active Directory, Sun Directory Server and Oracle Internet Directory.  For this article we will be creating two separate DataSources that will contain each of our Active Directory instances (domains).

Click on "Output" on the left-hand side of the application and then click on the "New DataSource" button near the bottom of the screen:



Label the first DataSource as "MyCompany", or use a name of your choosing.

Click on the "MyCompany" node in the Output section in the configuration navigator to enter the configuration panel for the new DataSource:



Verify that the Protocol is set to ldap (this is the default).

Under the "Servers" tab, enter the Hostname/IP Address and the port number (389) for the Active Directory instance (Domain Controller) that hosts the MyCompany domain.

Note: In order to enter a new server, you will need to right-click the current field and select "Insert Before" or "Insert After" to allow for an editable row:



Once you have entered the correct details for your Domain Controller, click "OK" to commit the changes:



Be sure to also click the save button on the top right of the application while creating your virtual tree to preserve your changes as you progress:



(A note on saving changes with the "OK" and "Save Config" buttons:

Configuration Panels allow you to view and change properties of the currently selected item. Whenever you have made changes to the configuration options in this area of the screen, you will need to click the "OK" button before you select another node in the configuration tree. If you fail to do this, the GUI will ask you whether you want to save your changes to the current item before moving on to the newly selected item. By clicking the "Cancel" button, you can undo the latest changes and restore the item’s properties to the ones that were set when you initially selected the item in the Navigator.

Note that these changes are not saved to disk, they are only saved in memory. In order to save the changes to disk, you will need to save the entire configuration by selecting the "Save Config" button from the Toolbar, or selecting the "Save Config" option within the File Menu. If you attempt to run the instance of VDS without having saved your changes, the GUI will give you the option of actually saving the configuration before you run the instance. If you choose not to save the configuration, VDS will still run the instance, but with the last saved configuration. It is important to note that if the GUI is closed for some reason without your saving the configuration to disk, all of your changes will be lost.)

Click on the "Security" tab and check the "Use Service Account" option.

Enter the Bind DN and password of an admin user in the MyCompany domain, e.g.: domain\administrator or cn=administrator (in the example below, the domain is actually THEROOMS.  "MyCompany" is a fictional domain name for the purpose of this article). The assigned server will inherit the credentials on its "Security" tab.

Click "OK" and then click on the "Test Connection" button to confirm the connection succeeds before proceeding.



Select the "Output" node again, and create a DataSource for the second domain, using the same steps as above.

Be sure to test the second configuration as well.


Listener Configuration

The listener will provide the interface that LDAP clients are able to connect to in order to have access to the newly created Virtual Tree.

Click on the "Input" node 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 (or a name of your choosing) and then click the "OK" button.

Click on the "VirtualTree" node on the left-hand side of the screen and the following will appear:

Under the "Main Listener Properties" tab:

- ensure the Protocol is set to ldap.

- set the port to 3890.

- click the "OK" button near the top of the screen to save the Listener configuration.




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 selecting the "Virtual Tree" option and then clicking on the "New Virtual Entry Root" button in the "Routing Information" section for 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.  The "objectclass" and "dc" attributes will be pre-populated:



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, the attributes for the virtual entry will be pre-populated, creating an "objectclass" and an "ou" attribute. For the "objectclass" change the value from "top" to "organizationalUnit" (click the 'Edit" button to edit the value):



Click "OK" to save the changes.  

Finally, 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, right-click on the virtual entry 'ou=People' in the Virtual Tree, and select the option "New Virtual Mount Point", from the context menu.  In this example, we will create a mount point for each of the User branches in both of the Active Directory instances.

Provide an appropriate RDN for each new virtual mount point. For example, create mount points with the following RDNs: 'ou=mycomp' and 'ou=sales'.





The mount point "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 mount point that you have created, you will be able to specify the DataSource and the DN for the data that you wish to attach. In this case, the DataSource should be set to MyCompany, and the DN should be the actual distinguishedName for the Users OU in your domain (or whichever OU you choose). E.g.:



For the other virtual mount point, we will be attaching the different user OU in the PartnerComp domain.  To do this, click on the mount point and specify the PartnerComp DataSource as the source to obtain the data, and then specify the DN where the data is stored. For example, for the sales users you would specify a DN of 'ou=sales,dc=partnercomp,dc=local'.



Now click on the VirtualTree node in the navigation and click to the "Virtual Tree" tab.  Here we will define Entry Exceptions, to forward particular BIND requests on to a backend DataSource.  Add an entry for the administrative users for each domain and select the DataSource for the administrator that you are configuring (e.g. MyCompany) as the default DataSource to handle bind requests for this user.



Next we will add a "DirectoryIntegration" stage and a plugin to handle the Naming Context. The Naming Context plugin adds a hook for RES_SEARCH_ENTRY request operations, in order to check whether the DN within the request is empty. If the DN is empty, the plugin will check for the existence of the namingContext attributes returned within the Root DSE result and will either replace the namingContext attributes returned by the server, or will append them to the list that is returned.  This behavior is controlled by setting the 'Overwrite Directory' option in the configuration of the plugin.

- Right-click the "Processing" node in the left-hand window and select "New Stage". Call the new stage "DirectoryIntegration" and keep the Stage Type set to "Automatic".



- Select the "DirectoryIntegration" node and click the "Add Plugin" button to add a new plugin.



In the "Add new Plugin" window, scroll down to the "Directory Integration" section and select "Manage Naming Contexts":



Click "OK" and then add the "Naming Context" for the virtual tree, e.g., dc=virtcomp,dc=com, and select the "Overwrite Directory" option:



Note at this point that the DirectoryIntegration stage will appear red even after clicking "OK". This is because the stage has to be added to the listener on the "Attached Stages" tab:



Finally, select the "Health Monitoring" node and on the "Health Check" tab select "Enable Health Checking".  Health checking is responsible for checking the availability of the servers defined within the configuration.




Testing the Virtual Tree

At this point, your Virtual Tree 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 Virtual Tree.

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 (select the "Extras" menu and choose "Launch LDAP Browser"), 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:



Note: enter the Suffix manually using the value of the configured Naming Context.

Ignore the Connection Warning that appears stating that "No schema was returned by the server." by clicking "OK".

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.