5 Understanding Oracle Virtual Directory Mapping

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


The mapping information in this chapter is included for historical purposes. While existing default mapping scripts are supported, any new customization should be done using the Java plug-in API. This is because the Java API supports full access to all Oracle Virtual Directory functionality and it is also a generally easier environment to develop in.

5.1 What is a Mapping?

Oracle Virtual Directory includes a bidirectional mapping system based on the Python scripting language. A Mapping is a special Python script, file type .mpy, that processes inbound and outbound transactional data flow and allows Oracle Virtual Directory administrators to manipulate and map data as it passes through the Oracle Virtual Directory server. Based on the popular Python scripting language, Oracle Virtual Directory's mapping system enables you to perform complex data manipulation without learning a new, proprietary, or complicated programming language. Oracle Virtual Directory's mapping system provides enterprises with additional flexibility in supporting identity access from applications. Oracle Virtual Directory compiles mappings into executable byte code and runs it inline for maximum performance.

Integrators can develop easy-to-use mapping scripts that perform custom transformations when mapping information from one data source to another. These scripts can be installed on a running server and deployed without resetting the server. A mapping script can adjust requests as they enter the system on the way to data sources and transform responses on the return path to the client. For example, you can use a mapping to normalize schema, such as making Active Directory look like InetOrgPerson; attach data-type, such as {sha} to a hashed password; or create a virtual attribute based on values of attributes retrieved from a data store.

When you create a Mapping you can use a predefined mapping template to simplify its configuration or you can create a new custom mapping (refer to "Understanding Mapping Templates" for more information on mapping templates). Typically, a Mapping is deployed to the Oracle Virtual Directory server as compiled Java code and runs inside a special type of plug-in known as a Mapper. As with Plug-ins, a Mapping may run globally or at an adapter level. Multiple mappings and adapters can be combined as a set of discrete functions performing an overall conversion service. Figure 5-1 shows a typical scenario where one Mapping is running on multiple adapters, while another Mapping is running only on a specific adapter.

Figure 5-1 Example Mapping Deployment on a Single Adapter and Multiple Adapters

Example mapping deployment.

Each Mapping has an inbound and outbound flow, allowing it to translate one way as a request is received and reverse that translation as results are returned to the requesting application. This programmatic reversal is important because it is not usually possible for the server to guess intent.

Oracle Virtual Directory provides a lot of flexibility in determining whether a Mapping should be executed globally or within the context of a single adapter. In some situations, you may have to further restrict the locations in the virtual tree where a Mapping is applied. For example, an adapter is set-up to proxy a Microsoft Active Directory domain and points to DC=VAN,DC=Oracle,DC=com. Under that point in the directory tree, there is a CN=Users container and a CN=Groups container. You can add a namespace filter to any Mapping to apply it to only one part of the tree.

The following is a list of notes to consider regarding Oracle Virtual Directory Mappings:

  • Oracle Virtual Directory mappings make extensive use of the Python language with additional Oracle provided functions for LDAP data manipulation. For more information about Python, refer to the Python Programming Language Official Web site at:


  • If you rename attributes with Mappings, Oracle Virtual Directory supports search on the renamed attribute/value only if the custom code overrides the incoming filter object, as is in the DB_Groups Mapping. For example:

    During outbound processing, a Mapping renames the givenname attribute to cn. During inbound processing, an incoming LDAP search filter, such as cn=John must be converted to givenname=John by the Mapping custom code.

  • If you deploy a Mapping and then run an ldapsearch command against Oracle Virtual Directory, the search base must be the namespace configured for the Mapping or any child of that namespace.

5.1.1 When to Use a Mapping and When to Use a Custom Plug-in

Most customers who use mappings use default mappings shipped with Oracle Virtual Directory to meet an application requirement. For customization needs, the Java plug-in API is typically used because the Mapper API only handles a subset of Java plug-in functionality and more developers know Java than Python, thus reducing time needed to develop the code.

5.1.2 Overview: Deploying Mappings

The following is an overview of the process for deploying Mappings at an adapter level and at a global server level:

  1. Construct the Mapping using Mapping templates, compile it into a script, and deploy it to the Oracle Virtual Directory server so that it can be activated at either the global server level or at the adapter level.

  2. Configure the Mapping at the global server level or at the adapter level by naming it, identifying its Mapping script file, determining the namespaces in the virtual directory tree where you want it to execute, and then activating it.


5.2 Understanding Mapping Templates

This topic describes each of the Oracle Virtual Directory Mapping templates and includes the following sections:

5.2.1 Active_Directory_to_inetOrg

Maps Microsoft Active Directory user and group objects to the inetOrgPerson and groupOfUniquenames objects (respectively).

5.2.2 Common_Name_to_Given_Name

Creates a virtual common name attribute by combining values from two attributes, default sn and givenname. The Common_Name_to_Given_Name mapping is typically used with the Database Adapter, which may have only a first and last name, but no full name.


This mapping does not support substring filters for common name attributes.

5.2.3 ConditionalPublish

Removes the attributes specified if the conditional value in another attribute is met. The ConditionalPublish mapping is useful to hide FERPA protected attributes in a higher education environment.

5.2.4 DB_Groups

Use this template to map a table that describes a group into a valid LDAP group. The first column is assumed to be cn, that is, the name of the group. The second column is assumed to be the uniquemember. With uniquemember, the DN is stripped so that only the RDN value is used inside the table. For example, converting: (uniqueMember=cn=XXX,ou=testusers) to (uniqeMember=XXX).

5.2.5 Map_DB_Password

Maps inbound binary syntax passwords to IA5String passwords compatible with the database.


If you associate the Map_DB_Password Mapping with a Database Adapter, then perform an LDAP modify with changetype Add and a binary attribute such as UserPassword with its value already existing in Oracle Virtual Directory, a duplicate row is added in the database if the primary key constraint is not present in the database table.