3 Understanding Oracle Virtual Directory Routing

This chapter describes Oracle Virtual Directory routing and includes the following topics:

What is Routing?

In a traditional directory server, multiple databases are defined and each are responsible for part of the directory tree namespace and selection is determined strictly on namespace comparison. In a virtual directory, since it is possible to have multiple adapters sharing the same namespace, selection is more complex—yet more controllable.

Routing is the process by which Oracle Virtual Directory decides which adapter should be selected for an LDAP operation. Routing is applied to all adapters regardless of type and serves several purposes, including:

  • limiting the number of adapters selected to just the ones which contain the requested client data and are relevant to the current LDAP operation.

  • enabling you to design for complex environments.

  • enabling you to tune Oracle Virtual Directory to implement a more secure, higher-performing configuration by reducing the number of adapters for a particular transaction.

Routing controls adapter selection by examining not just the basic DN namespace, but also other aspects of transaction information including DN pattern matching, LDAP filters, attributes filters, and query filters. At its most basic level, Oracle Virtual Directory can select adapters through a process of adapter suffix comparison. The adapter suffix comparison involves looking at any particular search base or entry DN, such as in the case of add, modify, delete, and rename, and then comparing it with the suffix (root) of each adapter. Depending on the scope, Oracle Virtual Directory can determine if one or more adapters was impacted by any particular query.

Adapter suffix comparison works well with a small number of adapters, however, more flexible decisions are usually required—where routing is explicitly important. Routing lets administrators teach Oracle Virtual Directory about proxied data sources in the form of routing intelligence. Routing allows Oracle Virtual Directory to further qualify directory operations and send them to the specific places where they are needed, which helps keep existing directories from being overloaded with irrelevant operations and keeps partners from seeing queries that are not related to their own directory. The Oracle Virtual Directory routing process analyzes LDAP client search filters in addition to traditional adapter suffix comparison and further refines eligible adapters for processing.

Routing Example

Consider the example virtual directory structure shown in Figure 3-1 that has the following four adapters configured:

  • Adapter 0 forms the root of the directory tree and maps to o=AppView. This adapter holds the virtual root of the tree and local entries such as access control groups.

  • Adapters 1-3 map each directory source to positions beneath the ou=People branch of the new application tree.

Figure 3-1 Example Virtual Directory Structure

Example virtual directory structure with 4 adapters.

For example, say an application that uses the directory in Figure 3-1 has little intelligence with regard to a directory service and it was originally designed for a single business and does not understand that multiple business user groups may be using the same application. Instead of expecting a varied and diverse directory tree structure, the application only searches the directory from one common directory hierarchy point (or one common base). For this example, say the application only searches the directory from ou=People,o=AppView. When a user enters a login credential such as jim.smith@divisionB.com, the application issues the following search:

  • base: ou=People,o=AppView

  • scope: subtree

  • filter: (uid=jim.smith@divisionb.com)

After receiving this query, Oracle Virtual Directory automatically selects all adapters eligible for this query. Since the query is at the base of the tree, all adapters are selected, leading to a performance problem to examine. If all the other companies exist lower in the directory structure (for example, ou=DivisionB, ou=People,o=AppView), then by default, all directory sources are searched because their branches are below the parent ou=People,o=AppView.

To resolve this issue, Oracle Virtual Directory provides routing inclusion and exclusion filters. You can use these filters to filter traffic for any particular partner directory. In this example, the administrator can set up the following Routing Include filters:

  • Division A Adapter: (uid=*@divisiona.com)

  • Division B Adapter: (uid=*@divisionb.com)

  • Division C Adapter: (uid=*@divisionc.com)

Even though the base of the LDAP client search would normally have selected all directories, the filters specify that the search for (uid=jim.smith@divisionb.com) should go only to the Division B directory. Figure 3-2 shows the three shaded adapters that would normally be selected, while the dotted area shows that after filter processing, only Division B's data is searched.

Figure 3-2 Example of Adapter Search With Filters

Figure shows an example of an adapter search using filters.

In addition to filtering queries, Oracle Virtual Directory also lets you assign priorities to each adapter. The adapter with the lower priority number is always queried first. Adapters with the same priority number are searched in order of definition in the configuration file. When conflicts occur, for example, two entries with the same DN, Oracle Virtual Directory will always accept only the response from the lower numbered adapter in priority or configuration. When routing filters fail to select a single adapter, potential conflicts are resolved by priority selection.

Understanding Routing Settings

After you create an adapter, you can configure the routing for that adapter using the adapter's Routing tab in Oracle Directory Services Manager. This topic describes the adapter routing settings available on the Routing tab and includes the following sections:


Click the Apply button on an adapter's Routing tab to apply changes you made to the adapter's Routing settings. Click the Revert button to revert (go back) to the Routing settings that were configured before you made changes. You cannot revert the settings after clicking Apply.


Sometimes it may be necessary to constrain Oracle Virtual Directory to process certain adapters before others, for example, when two or more adapters have overlapping namespaces. This situation can occur when bringing new directories into service while the existing directories must remain online.

The Priority setting determines the priority with which the adapter is to be treated relative to other adapters. 1 is the highest priority, 100 is the lowest priority, and 50 is the default setting.

In the example situation described above when bringing new directories into service while the existing directories must remain online, the Priority setting of the newer, more significant adapter should be set to a higher priority—that is, a number lower than the default 50 and also lower in respect to the existing adapter whose namespace overlaps with it.

Priority is used as the last chance selector when all other routing parameters have been processed. Given two otherwise equal candidates, the adapter with the higher priority, meaning lower number, is processed first. Adapters with the same priority number are searched in order of definition in the configuration file. When conflicts occur for a search operation, for example, two adapters who support the same DN, Oracle Virtual Directory will use the adapter with lowest priority number in the configuration first. During modify operations, Oracle Virtual Directory will only process entries within the adapter that are matched first moving up the tree from the entry.


For maximum precision, Oracle recommends using the Filters to Include, Filters to Exclude, and DN Matching settings to arbitrate in configurations where multiple adapters may be selected.

Filters to Include and Filters to Exclude

The Filters to Include and Filters to Exclude settings are essentially filters of a filter and apply to the LDAP search filters specified by a client. If a client search filter fulfills the logical requirements defined in the Filters to Include setting, that adapter is selected for inclusion in the set of adapters used in the search. Similarly, for the Filters to Exclude setting, if the logical requirements are met, that adapter is deselected from the set of adapters used in the client search.

The format for the Filters to Include and Filters to Exclude fields is a standard LDAP search filter followed by a scope term— either #base, #one, or #sub. The scope indicates at what scope level the filter should be applied. For example, filters using the #one scope apply to one level or sub tree searches and base searches would not be filtered.

The default scope for an include filter is #sub to filter out only queries involving an entire sub tree. To apply the filter applied for all scopes, set the scope to #base, which means the filter is applied to base, one-level, and sub-tree searches.

The default scope for an exclude filter is #one to allow blocking of specific searches. To apply the filter for all scopes, set the scope to #base. To apply the filter for just sub-tree searches, set the scope to #sub.

Both the Filters to Include and Filters to Exclude setting can be used together to form a more complex set of conditions governing the adapters used in a client search operation. For example, imagine you want to allow specific types of searches through an LDAP Adapter deployed as a firewall. To allow only certain searches, you could use a Filters to Include setting such as:


This filter would block any search with terms other than mail, uid, sn, givenname, or cn and allow only searches involving one or more of these terms. For example (cn=Jim Smith) is acceptable, while (uid=smith@oracle.com) is not acceptable since it does not end in myorg.com

Although most adapter configurations use simple search terms, a more complex example may better illustrate how the logic is applied. Consider the following filter example:

Client Search Command

$ ldapsearch -b dc=oracle,dc=com -s sub "(|(sn=user2)(cn=user2b))"

Routing Filter:


The routing filter indicates that if the client search filter contains an sn attribute and either a uid or cn term, than a match is made. In this example, without regard to other conditions, the adapter would be selected if the given routing filter were assigned to the Filters to Include setting and would be deselected if assigned to Filters to Exclude setting because the client filter includes an sn term and a cn term which fulfills the logic of the filter.

DN Matching

DN Matching is most often used when you want to have adapters sharing the same adapter root and you need a way to arbitrate which entries belong to which adapter. DN Matching allows you to exploit the differences in naming that might occur between two proxied sources. For example, in a large scale deployment you may wish to divide the entries based on the alphabet. DN Matching allows you to select alphabetic ranges and then allows Oracle Virtual Directory to select adapters based on range match. Thus, if you divided names into three ranges, users with IDs beginning A through J could be one directory, K through R might be another directory, and S through Z might be the final directory portion.

Another useful scenario for DN Matching is federating Microsoft Active Directory users with users in an external directory such as Open LDAP or some other directory. If the users in Open LDAP have relative distinguished names (RDNs) that are based on the uid attribute and Active Directory has user entries based on the cn attribute, then you can establish a regular expression that selects adapters based on the RDN type.

For Active Directory Adapter, the DN match might be:


For Open LDAP, the DN match might be:


By using DN Matching, Oracle Virtual Directory can effectively manage overlapped adapters by exploiting the differences in the existing sources.

In the DN Matching field you can enter a regular expression indicating how DN's within the adapter must be formed. The regular expression applies to the portion of the DN below the adapter's root. For example, if the adapter's root is ou=People,o=MyBigOrg.com and you only want to allow entries in the next level whose RDN begins with the letters A through J, you can specify an expression such as:


This expression indicates that the DN must contain a uid= term, followed by the letters A thru J, followed by any number of alpha numeric characters. The $ sign indicates the end of the string. In this case, because a comma is excluded at the end of the string, the uid= must be the last component of the DN within this adapter. Because the UID value must begin with A through J, then only UIDs matching that criteria are accepted. Finally, the ^(.*) part of the regular expression indicates that any number of characters of any type can occur between the start of the string (indicated by ^) and the specific value uid=.


  • Because DN's are case-insensitive, regular expression matching is performed in a case-insensitive manner.

  • The m/ and trailing / part of the match expression is optional.


When using multiple adapters where some adapters are children of other adapters, it may be desirable to configure the parent adapter so that queries occurring within the namespace of a child adapter are not also sent to the parent adapter. This happens when the DN of an LDAP operation pertains to both a child adapter and a parent adapter through normal namespace selection. By setting the depth, or level of the parent adapter, Oracle Virtual Directory can eliminate the parent adapter from participating in child transactions.

Used in conjunction with LDAP searches, the routing Levels setting determines how many levels below the adapter root the search base may be. For example, a value of 0 requires the search base to be the same as the adapter root, a value of 1 allows the search base to be at the adapter root or one level down, and so on. An empty (blank) Levels setting, which is the default setting, allows searches at all levels.

The Levels setting is useful as a performance parameter when mixing highly nested multiple adapter scenarios. Although the root adapter has the potential for being selected for all queries of a virtualized tree, this may not be desirable since other adapters may be set to point to parts of the tree containing the relevant data. To keep the root adapter out of all queries except those actually examining the root entry, thus increasing server performance, the Levels setting should be set to 0.

For example, if a Local Store Adapter was defined to be o=Oracle.com, it might be used to be a common parent for a series of LDAP Adapters who will be ou=Partner1, o=Oracle.com and ou=Partner2, o=Oracle.com, and so on. In this case, o=Oracle.com is a place holder for the child adapters. Since the adapter has only one entry, it only needs to be queried for operations where the search base is specifically o=Oracle.com. The adapter does not need to be searched when the search base is ou=Partner1, o=Oracle.com. In this case, a routing Levels value of 0 is appropriate.

Attribute Flow Settings

The Attribute Flow routing settings control how attributes flow into and out of an adapter. The Attribute Flow routing settings provide security by preventing information from being requested or returned to an unauthorized client. Also, for Join View adapters, the Attribute Flow routing settings control which attributes flow to which adapters since multiple adapters can contribute to the same virtual joined entry.


Unlike access controls, attribute flow rules provide quiet enforcement—they simply filter the request without returning an error to the client. In a high security setting this quiet enforcement prevents the client from knowing whether or not they are even allowed to see a particular attribute.

The following is a list of the Attribute Flow routing settings. Each setting is described in detail in the remaining subsections in this section:

Retrievable Attributes

The Retrievable Attributes setting controls which attributes may be retrieved by the adapter on the target directory. The Retrievable Attributes setting contributes to server performance and in some cases, security, since only the attributes named can be requested from a proxied server for add, modify, delete operations.

Additionally, you can use the Retrievable Attributes setting to control attribute flow when using the Join View Adapter. Since a Join View Adapter joins entries from two or more adapters, you need to control which attributes should come from the participating adapters. To control which attributes can come from the participating adapters in the Join View, configure the Retrievable Attributes settings on each adapter in the Join View.

In the Retrievable Attributes field, enter an explicit list of attributes that may be retrieved from an adapter. An empty list implies all attributes are retrievable. A specific list in the Retrievable Attributes field indicates that only the listed attributes may be requested from the proxied directory.


DN and objectclass are always returned from ldapsearch regardless of an adapter's Retrievable Attributes routing settings. DN is not an attribute and objectclass is handled as a unique objectclass.

Storeable Attributes

The Storeable Attributes setting controls which attributes may be stored by the adapter on the target directory. The Storeable Attributes setting contributes to server performance and in some cases, security, since only specific attributes and their values may be sent to the proxied server for add, modify, delete operations.

Additionally, you can use the Storeable Attributes setting to control attribute flow when using the Join View Adapter. Since a Join View Adapter joins entries from two or more adapters, you need to control which attributes should go to the participating adapters. To control which attributes can go to the participating adapters in the Join View, configure the Storeable Attributes settings on each adapter in the Join View.

In the Storeable Attributes field, enter a list of attributes that may be written to the adapter. An empty list implies all attributes are storable—unless Unstoreable Attributes are defined. If Unstorable Attributes are specified, only the specific values listed in the Storeable Attributes field are storable.

To make an adapter read only, enter _never in the list of Storable Attributes. The _ character is illegal in an attribute name and the condition can never be true, causing the adapter to be read only.

Unstoreable Attributes

Use this list if it is easier to express which attributes cannot be modified, rather than those that can be modified (as indicated using the Storeable Attributes field). Normally either a Storable Attributes list or an Unstorable Attribute list is specified, but not both.


An adapter's Visibility routing setting controls whether an adapter can be queried by an external client and whether it is published in the server namingcontexts attribute under the root entry. The following is a list and description of each Visibility setting:


The Visibility options are listed in the Oracle Directory Services Manager interface in English only, however the description for each Visibility option is supported in localized language translations.

The default setting, a visible adapter is an adapter whose root is published to the servers root entry as part of the namingcontexts attribute.


When visibility is set to No, the adapter is not listed in the namingcontexts attribute, but is still available to external LDAP clients. This is useful when you have multiple adapters working together to form a single directory tree branch. Rather than publish the parent and all of the child adapters in namingcontexts, you can publish just the root adapter since the whole logical tree is implied and publishing the child adapters would be redundant or confusing to applications.


An Internal adapter is an adapter that is only available to plug-ins and Join View adapters running inside of Oracle Virtual Directory. Internal adapters are not available for use by external LDAP clients. An example of this is an adapter configured for use by a Join View adapter. Rather than publish information twice in the external virtual directory, the primary and joiner adapters can be marked as internal so that only the Join View Adapter may access the information defined in these adapters.

Bind Support

The Bind Support option indicates whether the adapter can process LDAP bind operations. If the adapter does not support a bind function, Oracle Virtual Directory will attempt to obtain the userPassword attribute from the entry corresponding to the DN specified and will perform a local password compare operation. This is equivalent to having the Pass-through Mode setting set to Never in an LDAP Adapter. Enable the Bind Support setting when defining Custom Adapters that may or may not support a bind operation.


When a search operation with an adapter fails due to a host error, Oracle Virtual Directory reacts according to the Criticality setting. The following is a list and brief description of each of the Criticality settings:


The Criticality options are listed in the Oracle Directory Services Manager interface in English only, however the description of the Criticality field is supported in localized language translations.

The default setting, this setting indicates that if the adapter fails to return a result, for example, due to an operations error or when all remote hosts have failed, Oracle Virtual Directory will cause the overall search operation to fail and return a DSA Unavailable error to the client regardless of whether data was found in any other adapter or not.


This setting instructs Oracle Virtual Directory that the failure to perform an operation in the adapter is not critical to the overall result. If a non-critical adapter incurs an operations error, than the result is simply omitted from the overall LDAP search results and Oracle Virtual Directory returns partial results from any other adapters and does not indicate any error.


Setting the adapter criticality to Partial means the application can notify its own users that partial results were obtained. When an error occurs, Oracle Virtual Directory will return an Admin Limit Exceeded error. While this is not the expected error, the intention of this setting is to cause client application logic to indicate that not all results are shown.


Views allow applications to see different information in Oracle Virtual Directory. Views are defined by the distinguished names (DN) and IP addresses configured for the View. If an Adapter is enabled for a View, then only the DNs or IP Addresses configured in the View may see data from that Adapter. An Adapter can be enabled for one or more Views. A user that is a member of a View can only see information from Adapters that are enabled to the same View.

To enable an Adapter for a View, in the Views section on the adapter's Routing tab, select the Enable option for the appropriate View. If an Adapter is not enabled for a View, it is part of the default View. Any client not assigned to a View may see any Adapter that is part of the default View.

Creating and Configuring Views

Perform the following steps to create and configure a View:

  1. Log in to Oracle Directory Services Manager.

  2. Select Advanced from the task selection bar. The Advanced navigation tree appears.

  3. Expand the Server Views entry in the tree. The list of existing Views appear.

  4. Click the Add New View button. The Add New View dialog box appears.

  5. Enter a name for the View in the View Name field and click the OK button to create the new View. The new View appears in the list of existing Views.

  6. Click the name of the View in the list of existing Views. A screen appears where you can configure the DNs and IP Addresses for the View.

    To add a DN or IP address to the View, click the create button in the appropriate field, enter a value, and click the Apply button.

    To delete a DN or IP address from the View, select the value you want to delete and click the Delete button.

Include Binds From and Exclude Binds From

The Include Binds From and Exclude Binds From settings allow the administrator to indicate adapters which can share each other's credentials. The Include Binds From and Exclude Binds From settings also help the adapter determine whether the user credentials or the adapter's proxy account should be passed through on an operation. For example, consider different LDAP Adapters proxying two different domain controllers within a Microsoft Active Directory forest. To Oracle Virtual Directory, a user credential from one domain does not appear to be part of another domain. Also, because both domains are from the same forest, we know that the second domain can in fact accept a credential from another domain. The Include Binds From and Exclude Binds From settings allow the administrator to instruct Oracle Virtual Directory on how to handle these situations.

When deciding whether a user credential can be passed through, Oracle Virtual Directory considers the following two conditions:

  • whether the supplied credentials are under the current adapter root

  • whether the user credentials map under an adapter listed in the Include Binds From field, and also, whether the user credential maps under an excluded adapter listed in the Exclude Binds From field.

Consider the following example with adapter root ou=admin,o=depts,dc=oracle,dc=com. A user credential may either:

  1. Case A: Map within the namespace of ou=admin,o=depts,dc=oracle,dc=com

  2. Case B: Not map within the namespace of ou=admin,o=depts,dc=oracle, dc=com (for example, the credential has DN ends with ou=sales,o=depts, dc=oracle,dc=com).

Case A

User credential ends with ou=admin,o=depts,dc=oracle,dc=com:

If the Exclude Binds From field is not empty, then the user's credential must be checked to see if they are a child of one of the excluded adapters. If it is, then the Proxy credential must be used (instead of passing through the client's credential). If the user's credential does not belong to an excluded adapter, then the user's credential may be passed through the current adapter.

This scenario most often occurs when two LDAP Adapters are defined where the second adapter is a child of the first or parent adapter. A credential that is part of the child adapter could also erroneously be considered to be part of the parent adapter. Using the Exclude Binds From setting helps correct the problem where the credential from the child adapter would be incorrectly passed through to the parent adapter. Using the Exclude Binds From setting allows Oracle Virtual Directory to understand that certain child DNs do not map to the parent adapter's credential set.

Case B

User credential ends with root different from ou=admin,o=depts, dc=oracle,dc=com:

If the Include Binds From field is not empty, but has adapters defined as shared, the user credential must be checked to see if it maps to one of the shared adapters. If it does, the credential is mapped by the shared adapter and returned to the original adapter. The original adapter is then able to pass through the credential mapped by the shared adapter.

If the credential does not map to the current adapter, or any of the shared adapters, then the proxy credential must be used rather than passing through the provided credential.

An example of this is an Oracle Virtual Directory that proxies multiple Microsoft Active Directory domains. User credentials may have different roots, but since all proxies go to the same forest, it is possible that one domain controller can authenticate a DN from another domain controller. In this situation, credentials from either adapter can be shared in common across both adapters. For example, Domain A adapter proxies Domain A, Domain B adapter proxies Domain B. Domain A and B are in the same forest. Therefore, on both the Domain A and Domain B adapter, you can set the Include Binds From setting to Domain A, Domain B and both adapters are able to pass through each-other's credentials.