2 Understanding Oracle Virtual Directory Adapters

This chapter describes Oracle Virtual Directory adapters and contains the following sections:

2.1 What is an Adapter?

To present the single virtual directory view of data in multiple and various data repositories, Oracle Virtual Directory must connect to those repositories so it can virtualize the data and route data to and from the repositories. Oracle Virtual Directory uses adapters to connect to its underlying data repositories. Each adapter manages a namespace in the directory identified by a specific parent distinguished name (DN). There is no limit to how many adapters you can configure. You can also combine and overlap adapters to present a customized directory tree.

The sections in this chapter describe each Oracle Virtual Directory adapter in detail. The following is a list of the adapters Oracle Virtual Directory provides:

  • LDAP Adapter

  • Database Adapter

  • Local Store Adapter

  • Join View Adapter

  • Custom Adapters

2.2 Understanding the LDAP Adapter

The LDAP Adapter connects Oracle Virtual Directory to LDAP version 2 and 3 directories and Microsoft Active Directories. The LDAP Adapter enables Oracle Virtual Directory to present LDAP version 2 and 3 and Microsoft Active Directory data as a subtree of the virtual directory by providing automatic real-time directory structure and schema translation. You can configure the LDAP Adapter to root the virtual subtree at the top of the directory so that it spans the entire virtual directory information tree (DIT). One LDAP Adapter is required for each distinct LDAP source you want to connect to. For example, if you have an Active Directory domain controller that has four replica servers, you would deploy only one LDAP Adapter and configure it to list each of the four host names and ports of the replicas.

Oracle Virtual Directory can load-balance requests across the replicas or fail-over sequentially. The Oracle Virtual Directory administrator can adjust load-balancing ratios.

The LDAP Adapter provides additional fault tolerance and performance solutions, such as the ability to direct LDAP query traffic to multiple LDAP directory replicas according to particular search criteria or load-balancing requirements according to availability and operation type, such as, query operations compared to modify operations. For example, in a situation with thousands of active clients, Oracle Virtual Directory reduces load to 10 or 20 steady connections processing thousands of queries—or, for a particularly busy client, Oracle Virtual Directory distributes the load across each of its worker threads according to defined load balancing objectives.

In high performance scenarios, the LDAP Adapter can smooth the connection load seen by source directories by spreading the load from multiple clients across a limited set of connections. The LDAP Adapter does this by maintaining a pool of connections between the Oracle Virtual Directory and the source directory and its replicas, allowing the source directory to work faster by having a reduced connection handling load and by having Oracle Virtual Directory limit traffic to it so that its maximum thread load is not exceeded.

Note:

Oracle Virtual Directory enables you to secure the LDAP Adapter interface using SSL.

The remaining sections provide additional information on the LDAP Adapter, including:

2.2.1 LDAP Adapter Deployments

The LDAP Adapter can be deployed as a:

  • Pure proxy

  • Virtual directory proxy

LDAP Adapter as a Pure Proxy

As a pure proxy, the LDAP Adapter can be configured to perform no translation, which makes Oracle Virtual Directory act as a directory router for solving availability and firewall issues. To configure the LDAP Adapter as a pure proxy, you set the Adapter Root and Adapter Remote Base configuration parameters with the same values.

LDAP Adapter as a Virtual Directory Proxy

By contrast, there can often be a requirement to change one directory tree namespace to another name to provide a simple namespace mapping. By setting different values for the Adapter Root and Adapter Remote Base configuration parameters, a namespace mapping is implied. For example, imagine that the proxied directory has people entries at the base ou=People,o=Airius.com. The local directory design calls for the Airius entries to appear within the local people folder.

Consider the following settings for the adapter configuration parameters:

  • Adapter Root: ou=Airius,ou=People,dc=YourCompany,dc=com

  • Remote Base: ou=People,o=Airius.com

When queried through the LDAP Adapter with these settings, all entries below ou=People,o=Airius.com appear to have DNs under the designated DN root of ou=Airius,ou=People,dc=YourCompany,dc=com.

By default, all attributes are passed through as-is from the proxied directory through the Oracle Virtual Directory to the Oracle Virtual Directory client. The LDAP Adapter can perform basic DN translation of attributes containing DNs specified in the DN Attributes configuration parameter list. Only attributes listed in the DN Attributes parameter configuration list and attributes that have DN values that contain the Remote Base DN configuration parameter value for the LDAP Adapter as suffix are translated. For example, consider the following:

The adapter root DN is dc=emer,dc=orion,dc=com and the remote base DN is ou=emer,o=orion.com.

A group object in the dc=emer,dc=orion,dc=com namespace has members in both the dc=emer,dc=orion,dc=com and dc=amer,dc=orion,dc=com namespace (for example, because of an Active Directory trust relationship) would be translated as:

DN: cn=Group 1, cn=groups,ou=emer,o=orion.com 
objectclass: top 
objectclass: group 
member: cn=Jane Doe,cn=users,ou=emer,o=orion.com 
member: cn=Ted Davies,cn=users,dc=amer,dc=orion,dc=com 

Note:

The dc=amer,dc=orion,dc=com value did not change because the LDAP Adapter cannot translate values that are outside of the namespace.

This is an uncommon scenario because usually the DN attribute values either exist within the directory namespace or values are properly translated before being added into the directory.

If you do encounter this scenario, use a custom Mapping script to translate the values that are outside of the adapter's root namespace. Oracle Virtual Directory also can translate attributes on-the-fly as data from the remote directory passes through the Oracle Virtual Directory by using Mappings and Plug-ins.

2.2.2 LDAP Adapter Read, Write, Rename, and Compare Support

The LDAP Adapter supports full read, add, modify, delete, and rename functionality. Support for the LDAP rename operation includes the ability for renaming or moves between adapters. An LDAPv3 moddn function of LDAP rename, that is, a move, done between adapters causes a cut and paste to occur. To make this transaction safe, the originating entry is not removed until Oracle Virtual Directory has confirmed a successful add into the destination directory. If the add fails in the destination directory the operation is aborted the error from the destination directory is returned.

LDAP compare operations are automatically converted to LDAP get or LDAP bind operations to provide cross-adapter and cross-protocol support.

2.2.3 Access Control and the LDAP Adapter

Oracle Virtual Directory access control is applied at two levels:

  • Oracle Virtual Directory Access Control

  • Remote LDAP Server Access Control

Oracle Virtual Directory Access Control

Oracle Virtual Directory supports IETF RFC 2820 and also enforces access control according to the IETF LDAP Access Control Model for LDAPv3 (March 2, 2001 draft). This draft specifies how RFC 2820 should be implemented in a vendor neutral way. Oracle Virtual Directory enforces these standard- and draft-compliant access controls uniformly across all adapters providing a consistent security implementation. Refer to "Understanding Oracle Virtual Directory Access Control" for more information.

Remote LDAP Server Access Control

Because Oracle Virtual Directory acts as an LDAP client, it must conform to access controls in remote adapter directories, such as LDAP directories. How this works depends on the vendor's implementation of access control.

When Oracle Virtual Directory connects to a proxied directory server, it can use its own credentials or the bound end-client credentials.

  • If Oracle Virtual Directory passes through user credentials to the source directory, then end-to-end user contextual access control is enabled. The implication is that the remote server will authenticate the bound end-client credentials.

  • If Oracle Virtual Directory passes its own credentials, then Oracle Virtual Directory must provide its own user-specific access control while being subject to access control enforced against its server credential with the proxied directory.

Depending on the value you set for the LDAP Adapter's Pass Credentials configuration parameter, Oracle Virtual Directory can verify credentials in one of the following methods when processing bind requests using passwords for users whose entry is represented by an LDAP Adapter:

  • If the Pass Credentials configuration parameter is set to Always or Bind-only, Oracle Virtual Directory passes the supplied user DN and password to the proxied LDAP directory. The proxied directory is responsible for determining the validity of a user-supplied password. The success or failure of the remote password verification is then returned transparently to the user.

  • If the Pass Credentials configuration parameter is set to Never, Oracle Virtual Directory uses the adapter specified account to connect to the remote directory to retrieve the encrypted password value.

    Note:

    The account specified in the adapter configuration must be granted access to the encrypted password value by the proxied directory or the bind will be treated as a failure. When the encrypted value is returned to the Oracle Virtual Directory, Oracle Virtual Directory encrypts the user's password and compares it with the encrypted value returned from the proxied server. If a match is determined, Oracle Virtual Directory returns a successful bind.

    If users are performing certificate binding, the Pass Credentials setting of Never is implied where Oracle Virtual Directory confirms client credentials by pulling the client's public key from the remote LDAP proxy.

2.2.4 Response Control and the LDAP Adapter

To simplify interoperability with LDAP client applications that use LDAP controls, you can configure the LDAP adapter and operation modules to retrieve response controls from JNDI (if present) for all operations and return those controls to the client. These response controls provide better information about which controls actually are supported in a virtualized environment.

To include or exclude request controls that can be propagated to a remote LDAP server, add the optional allowServerSupported parameter to the LDAP adapter configuration. Request controls that are in the exclude list are filtered out from the request sent to the remote server.

The allowServerSupported parameter has two values,

  • false (default). Passes all request controls through to the remote server.

  • true. Passes only the controls that are in the supportedControl of the remote server RootDSE through and ignores the include or exclude options.

2.3 Understanding the Database Adapter

The Database Adapter is a fully featured LDAP-to-Java Database Connectivity (JDBC) gateway supporting translation of all LDAP operations (add, bind, delete, get, modify, rename) into equivalent SQL prepared statement code. The Database Adapter can connect to most databases that support JDBC or Open Database Connectivity (ODBC) through the JDBC-ODBC library. The Database Adapter uses JDBC class libraries to form connections to databases for performing LDAP searches. The required database libraries are generally provided with the database distribution or are available through the database vendor.

Database Adapter Features

The following is a list of some Database Adapter features:

  • No modifications required for source database

  • Flexible table and column mapping, allowing almost any LDAP object to be constructed on-the-fly by using Mappings that define how LDAP objectclasses are derived from tables.

  • Connection pool for streamlining requests.

  • Multi-table Joins performed within Oracle Virtual Directory or through views in the RDBMS server.

  • Multi-value attribute mapping through row grouping using a primary key.

  • The ability to construct several object classes and hierarchies within a single adapter connection.

Database Adapter Considerations

When using the Database Adapter, keep the following in mind:

  • LDAP operations do not support transactions, so the Database Adapter modifies one database table at a time.

  • LDAP supports multivalue attributes, however, database tables support one value for each column. To create an entry with multivalue attributes in the database table, the Database Adapter denormalizes the table and creates one row for each variation of the attributes in the entry.

  • The Database Adapter connects to databases using only Oracle Virtual Directory's credentials—it cannot pass through client user credentials as the LDAP Adapter can.

  • The Database Adapter supports only normal SQL operations and does not support deployment specific stored procedures. Consider using a plug-in with the Database Adapter to support database stored procedure integration.

  • All components that form an entry's DN must be contained in the database table—except for the portion of the DN that is the adapter root namespace.

  • Oracle Virtual Directory returns only one attribute when multiple attributes are mapped to one database column. You can address this issue by creating a custom mapping script.

  • If you use the Database Adapter to manage client binds, for example, to validate passwords stored in a field in a database table, you must store the password in a CHAR/VARCHAR field in the database and you must deploy the Map DB Password mapping to the Database Adapter.

  • Currently, the Database Adapter only supports exact matches on telephone number values if used in a search filter. If you are using the Database Adapter to support lookups on telephone number, you can use a plug-in to normalize the input value before sending the query, which allows LDAP applications that do not adhere to the LDAP standard to continue to function.

  • The Database Adapter does not support multi-value RDNs.

The remaining sections provide additional information on the Database Adapter, including:

2.3.1 Access Control and the Database Adapter

The Database Adapter respects the access controls that exist on the remote database in addition to Oracle Virtual Directory's own native access controls. Unlike the LDAP Adapter, Oracle Virtual Directory cannot pass the authenticated user's credentials to the remote database. As a JDBC client, Oracle Virtual Directory is restricted in capabilities to those authorized by the RDBMS server for the adapter defined by the adapter's Database Username specified in the JDBC Connection information. All queries are performed using the account specified in the Database Username field.

Oracle Virtual Directory performs password verification by comparing the value returned from the database with the value supplied by the user. If the password is stored in hashed/encrypted form, the value must be prefixed with the appropriate hash qualifier ({crypt}, {sha}, {ssha}). The prefix informs Oracle Virtual Directory about what type of password hash comparison algorithm to use to validate the password. Since this is an LDAP convention, the prefix may not exist in the text file. Use an adapter mapping to assign a prefix.

Oracle Virtual Directory applies its own standards-based LDAP security and access control model simultaneously across all adapters and adapter types.

2.3.2 JDBC Java Class Libraries

Before you can use a particular JDBC driver, you must load the driver file Oracle Virtual Directory as described in "Loading Libraries into the Oracle Virtual Directory Server". The driver files can be downloaded from their respective manufacturers. For more information on locating drivers, refer to the Oracle Technology Network at: http://www.oracle.com/technology/index.html.

After the JDBC libraries are loaded into Oracle Virtual Directory you can define a new Database Adapter connection by either selecting a predefined database type, or by specifying the JDBC URL as defined by the manufacturer.

The Database Adapter supports predefined JDBC URLs for the following databases:

  • Hypersonic

  • IBM DB2

  • Microsoft SQL*Server

  • MySQL

  • OpenBase

  • Oracle

  • PostgreSQL

  • Sybase

  • Sun ODBC-JDBC Bridge

2.3.3 Understanding Database Adapter Mapping

The following is a list of aspects related to mapping relational data structures into a hierarchical directory when using the Database Adapter, including:

Entry Name Formation

All database fields that are used as part of an entry's name—except for the portion of the DN that is the adapter's root—must be contained in the table rows that are mapped and returned to Oracle Virtual Directory through the Database Adapter. For example, to create a hierarchy in which user objects contain both a common name (cn) and an organizational unit (ou) in their DN, for example, cn=Joe User,ou=Marketing, both the cn and ou must be part of the entry.

In pure LDAP, the ou attribute would not normally be required as it is part of the parent entry. Since databases are not hierarchical, you can generate multilevel DNs without requiring considerable new metadata to be created and managed to define hierarchy.

Indexes for Mapped Tables

To improve performance when using a Database Adapter, Oracle recommends creating the appropriate indexes on the database tables that are being mapped. For example, a table named employee contains columns named salary and employeename and the cn name is mapped to employeename. To improve performance, create a function index for employeename as follows:

create index upper_employee on employee (upper(employeename));
Multiple Table Writes

Multiple table writes are not possible directly through a single Database Adapter. This is the same limitation exhibited by databases where views cannot be updated directly when they present columns from multiple tables.

Oracle Virtual Directory can work around this limitation by using the Oracle Virtual Directory Join View Adapter. By creating multiple database adapters (perhaps one for each table) and defining the relationship between them, it is possible to have Oracle Virtual Directory manage writes to entries that are constructed through multiple tables.

Multiple Valued Attributes

Databases typically do not allow for multiple values for a single field within a single table row. There are exceptions where an array type is supported, but these data types tend to be relatively limited. Some users put multiple values into a row by separating data, such as account flags, within a field using delimiters such as commas or pipes (|).

Traditional database design dictates that fields that have multiple values should be normalized into an additional table. Databases that are part of a data warehouse may take a different approach in which every permutation of every field is placed into a denormalized table.

Oracle Virtual Directory can generally support either model. In general, Oracle Virtual Directory takes the designated RDN attributes and uses them to group multiple rows together. Where Oracle Virtual Directory schema supports multiple values, Oracle Virtual Directory groups these rows together to form a combined entry.

Consider a table used to define group memberships, as shown in the following example. In the first column there are group names. A member is defined in the second column as follows:

GroupName Member

My First Group

cn=Paul Jacobs,cn=Users,dc=Oracle,dc=com

My First Group

cn=Alice Wing,cn=Users,dc=Oracle,dc=com

My First Group

cn=Jim Smith,cn=Users,dc=Oracle,dc=com

Administrators

cn=Paul Jacobs,cn=Users,dc=Oracle,dc=com

Administrators

cn=Jim Smith,cn=Users,dc=Oracle,dc=com


In SQL, to list the members of each group, a SQL query would look like the following:

select * from grouptable group by groupName;

When proxied through the Database Adapter, Oracle Virtual Directory returns the data as follows:

dn: cn=My First Group,ou=Groups,dc=Yourcompany,dc=com
objectclass: groupofuniquenames
objectclass: top
cn: My First Group
uniquemember: cn=Paul Jacobs,cn=Users,dc=Oracle,dc=com
uniquemember: cn=Alice Wing,cn=Users,dc=Oracle,dc=com
uniquemember: cn=Jim Smith,cn=Users,dc=Oracle,dc=com

dn: cn=Administrators,ou=Groups,dc=Yourcompany,dc=com
objectclass: groupofuniquenames
objectclass: top
cn: Administrators
uniquemember: cn=Paul Jacobs,cn=Users,dc=Oracle,dc=com
uniquemember: cn=Jim Smith,cn=Users,dc=Oracle,dc=com

In these results, Oracle Virtual Directory has collapsed the group name into the single unique value and combined the group members into the multi-valued uniquemember attribute.

Searches and Multiple Row Objects

Searches are supported to normalized or denormalized tables without doing anything other than configuring a database-level join as necessary. Keep in mind that due to the most popular use cases, the current design of the database adapter is that if a multi-value attribute is searched, the adapter will return only the row that matched the search as part of the entry. In proper LDAP terms, all values of the attribute would normally be returned. For example, consider the following search:

ldapsearch -b "cn=administrators,ou=groups,dc=yourcompany,dc=com" -s
base"(uniquemember=Paul Jacobs,cn=Users,dc=Oracle,dc=com"

In normal LDAP servers, you would expect the following result:

dn: cn=Administrators,ou=Groups,dc=Yourcompany,dc=com
objectclass: groupofuniquenames
objectclass: top
cn: Administrators
uniquemember: cn=Paul Jacobs,cn=Users,dc=Oracle,dc=com
uniquemember: cn=Jim Smith,cn=Users,dc=Oracle,dc=com

Instead, the Database Adapter returns:

dn: cn=Administrators,ou=Groups,dc=Yourcompany,dc=com
objectclass: groupofuniquenames
objectclass: top
cn: Administrators
uniquemember: cn=Paul Jacobs,cn=Users,dc=Oracle,dc=com

In the Database Adapter results, the other members are missing. This apparent non-standard behavior is intentional and is designed to facilitate high performance searches to test membership in large database entities such as groups. In these scenarios, customers most often only wanted to determine whether a particular person was a member. Rather than transmit the entire group, the intersection group is returned by the adapter instead.

If standard LDAP behavior is expected, a mapping can be added to the adapter that replaces the uniquemember filter term with (objectclass=*). The mapping can then test the result after the group information is returned to confirm that the result found matches the filter.

Note:

Certain NOT conditions in the DB adapter search filter do not work correctly when the attribute contains multiple values. For example, assume that the LDAP entry contains three values for attribute telephonenumber in the database.

telephonenumber=44 1902 777777
telephonenumber=44 1902 888888
telephonenumber=44 1902 999999

When you perform a search for the LDAP entry with a NOT filter containing one of these values (for example, "!(telephonenumber=44 1902 999999)"), the telephonenumber entry would still be returned.

Writes to Tables

Writes to multi-table objects (normalized tables) must be performed by using a Join View Adapter that splits out attributes to each table based on the design of the database. This is required because while there are general guidelines for database design, every customer's database is different and the resulting relationship between joined tables can vary widely.

Most customers that use existing and important tables also use stored procedures as part of controlling updates to those tables. These are similar to API calls and are proprietary to each database in the way they are constructed and called. The calls themselves are proprietary to the customer. Oracle Virtual Directory supports stored procedures with its plug-in system.

Oracle Virtual Directory supports direct writes to denormalized tables in which each value for the field that is used in the entry associated with the field used as the RDN for the entry. All operations including add, modify, and delete are supported.

Within the modify operation, the way the LDAP modify-replace works is to remove existing attribute values and add new ones. This translates into a SQL delete and a SQL insert rather than a complex set of SQL inserts, updates, and deletes. The potential difficulty is with databases that have normalized tables in which the insert and delete triggers other actions within the database. In such a case, a plug-in would have to be constructed that would handle the modify-replace operation.

Most customers do not run into this issue as they either are not using direct SQL access for changes, are using multiple values only for read, or are only using modify-add and modify-remove directly. For example, customers solving issues with big groups are storing groups in databases by using Oracle Virtual Directory. Most group membership changes are adds and removes rather than replaces.

Cascading Deletes

Of the issues mentioned in the "Writes to Tables" description, the biggest issue to watch for when using the Database Adapter is when Oracle Virtual Directory will be handling database writes directly to a database that is using cascading deletes. A cascading delete is where a delete in one table causes the database to activate a stored procedure that causes deletes in other tables. With cascading deletes, a modify-replace can possibly trigger deletes outside of the table being directly touched by the Database Adapter. This happens because the database is sent a single transaction that performs a SQL DELETE that removes existing values and a SQL INSERT that adds new replacement values.

This is not an issue if the database trigger is based on a single-valued table in which fields with multiple values have been normalized to other tables. Oracle Virtual Directory does an UPDATE rather than a DELETE-INSERT combination on replaces in which the table has a single row associated with the entry being changed.

Note:

The Database Adapter sets unmapped database column values to NULL during an LDAP update. This limitation is planned to be removed in a future version of Oracle Virtual Directory.

To work-around this limitation, either map all columns (and use routing rules to hide them in search results) or map the table to a view with an update trigger.

Substring Searches

If applications use substring searches, the Database Adapter-mapped attribute must be mapped as VARCHAR database syntax. This is the only way for SQL to support substring searching.

2.4 Understanding the Local Store Adapter

The Local Store Adapter enables you to store small amounts of data that does not have to be made highly available in a local flat file.

The following is a list of the most common uses for the Local Store Adapter:

  • In a situation where you want to store a small amount of data that must be visible to client applications but does not change very often and also does not have to be made highly-available. For example, the base entries used by Oracle Virtual Directory to emulate Oracle Internet Directory as part of the Oracle Virtual Directory-Enterprise User Security integration.

  • Developers can use the Local Store Adapter when they are building an application that will eventually use the enterprise directory, but they currently do not have access to an enterprise directory service. In this situation, developers use the Local Store Adapter to store test entries as part of the development process, and later migrate to an enterprise directory storage system, such as Oracle Internet Directory, when the application is ready for production use.

    Note:

    Oracle Virtual Directory's value is as a virtualization and proxy service, not as a directory store. If you need a highly available directory storage system, Oracle recommends using Oracle Internet Directory—not Oracle Virtual Directory's Local Store Adapter.

  • To hold a single top of the directory tree entry when you have multiple adapters and they are all branches of the directory tree. For example:

    Suppose you have the following two LDAP Adapters configured:

    • ou=staff,dc=mycompany,dc=com

    • ou=customers,dc=mycompany,dc=com

    You can use the Local Store Adapter to store a top entry of dc=mycompany,dc=com above the other adapters. Oracle Virtual Directory does not require this top entry and it will be transparent to most LDAP clients, however some LDAP client applications, in particular Graphical User Interface desktop LDAP management clients, can return erroneous error messages if they do not find an entry at the top of the server.

You can deploy multiple Local Store Adapters for each Oracle Virtual Directory server, however most servers deploy only one. The most common use for deploying multiple Local Store Adapters is to store different parts of the directory tree in different files for backup and recovery considerations. For example, one branch of the directory tree might be relatively static and therefore does not require frequent backups.

If you want to employ Oracle Virtual Directory high availability with Enterprise User Security (EUS), be aware that EUS only searches the data in the Local Store Adapter. Because EUS does not actually update data stored in this adapter, you are not required to configure any type of replication or synchronization for EUS-related Local Store Adapters.

Use the syncovdconfig command to copy the Local Store Adapter (and other adapter) configurations to other Oracle Virtual Directory servers. For more information about using the syncovdconfig command, refer to Section 9.7, "Copying Configuration Files Between Oracle Virtual Directory Servers Using syncovdconfig."

For Local Store Adapter data sync, you can either load the entries into the Local Store Adapters of each of your Oracle Virtual Directory instances or you can load the data on one instance only and use the oidcmprec tool to synchronize the data in the Local Store Adapters. For more information, refer to Section 2.4.1, "Migrating Local Store Adapter Data."

2.4.1 Migrating Local Store Adapter Data

You can use the Oracle Internet Directory oidcmprec tool to migrate LDAP data out of a Local Store Adapter and into another repository.

Note:

Only the compare and reconcile operations of the oidcmprec tool are supported for Local Store Adapter data migration.

This section provides an overview of migrating data out of a Local Store Adapter using oidcmprec.

See Also:

Refer to the following documents for complete information on the Oracle Internet Directory oidcmprec tool:

This section contains the examples for migrating data out of a Local Store Adapter using oidcmprec in the following scenarios:

Notes:

  • After executing the oidcmprec command, you are prompted for the replication dn password for both the source and destination directories.

  • Oracle Virtual Directory does not allow you to modify the orclguid. Oracle recommends excluding orclguid when comparing two directories using oidcmprec.

  • If the oidcmprec tool cannot find an entry in the destination source directory, the tool attempts to find the correct entry by using orclguid to perform a global search on the source directory, which can cause problems when searching Oracle Virtual Directory. If you configured Oracle Virtual Directory with multiple adapters, ldapsearches go to all of the adapters. If any of the adapters are inactive, an error can result.

    The oidcmprec tool can detect if it is searching an Oracle Virtual Directory, and it searches for all the Oracle Virtual Directory adapter rootDNs. The oidcmprec tool uses the most appropriate Oracle Virtual Directory adapter rootDN as the basedn for the ldapsearch, which then limits the search to only one adapter.

  • The oidcmprec tool can copy the data inside a Local Store Adapter to a second server, but doing so is a one-time operation. The oidcmprec tool cannot keep the Local Store Adapter's content in-sync, so you must call it whenever you modify the Local Store Adapter's content.

Initial One-Way Data Migration Between Two Local Store Adapters

For example, consider the following use case. You have two Oracle Virtual Directory servers running on two different hosts, myhost1 and myhost2. Each host has a Local Store Adapter (LSA) configured: LSA1 on myhost1 and LSA2 on myhost2. You want to migrate the data under c=US in LSA1 to LSA2 for the first time. To perform this migration, run the following command:

oidcmprec operation=reconcile source=myhost1:port 
destination=myhost2.port base="'c=US'" scope=subtree exclattr=orclguid

Note:

Oracle recommends using the reconcile operation of oidcmprec for one-way data migration.

Synchronization Between Two Local Store Adapters

For example, consider the following use case. You performed an initial data migration from one Local Store Adapter (for example, LSA1) on one Oracle Virtual Directory (for example, myhost1) to another Local Store Adapter (for example, LSA2) on a different Oracle Virtual Directory (for example, myhost2) as described in Initial One-Way Data Migration Between Two Local Store Adapters. Later, you want to synchronize the data under c=US between the two Local Store Adapters. You do not have to migrate all data under c=US from the source. Instead, migrate only recently modified data using the oidcmprec tool's timestamp based filters, which are based on RFC 2254. All data in the source that was modified after the value specified by the timestamp filter is migrated to the destination.

Notes:

  • When synchronizing data between two Local Store Adapters, only one-way data migration is supported. That is, if you initially synchronize data in LSA1 (source) to LSA2 (destination), you should not synchronize data from LSA2 to LSA1 in the future.

  • The target (destination) Oracle Virtual Directory must be running to migrate the data.

To perform this type of migration, run the following command:

oidcmprec operation=reconcile source=myhost1:port 
destination=myhost2.port base="'c=US'" scope=subtree
filter='("modifytimestamp>=point_in_time")' exclattr=orclguid

Local Store Adapter to Oracle Internet Directory Data Migration

You can also use the oidcmprec to migrate data from a Local Store Adapter to Oracle Internet Directory. The following command migrates data under c=US in the Local Store Adapter on Oracle Virtual Directory running on myhost1 to the Oracle Internet Directory running on myhost2:

oidcmprec operation=reconcile source=myhost1:OVD_port 
destination=myhost2.OID_port base="'c=US'" scope=subtree exclattr=orclguid

Local Store Adapter Migration and Data Synchronization Between Two Oracle Virtual Directorys

For example, consider the following use case. You have configured one or more Local Store Adapters on one Oracle Virtual Directory and want to use oidcmprec to synchronize the data with another Oracle Virtual Directory.

To perform this migration, use the following command:

oidcmprec operation=reconcile source=ovdhostsrc.mycompany.com:6501
destination=ovdhostdest.mycompany.com:6501 base="'dc=eusovd,dc=com'"
scope=subtree exclattr=orclguid sbinddn='"cn=orcladmin"'
dbinddn='"cn=orcladmin"'

2.5 Understanding the Join View Adapter

The Join View Adapter combines multiple different data sources into one unified LDAP view similar to a relational database's table join. The Join View Adapter does not connect to the underlying data repository like the other Oracle Virtual Directory adapters—it builds on top of one or more existing adapters to assemble its data. Think of the Join View Adapter as joining two or more data repositories by defining join relationships, sometimes called "Joiners," between adapters.

A Join View is dynamic and performs no synchronization between proxied sources. The Join View objective is to present merged data to an LDAP client in real time. A Join Adapter solves the problem of split-profiles, meaning cases where data for a single entry is split between two or more sources. For example, a Join Adapter is used to link a person's LDAP entry with their job title from the Human Resources database. A Join Adapter is not used to solve the problem of allowing applications to search multiple and different sources, such as one LDAP for staff and one LDAP for customers. This particular problem can be solved by making the sources appear as virtual branches under a common root.

The following is a list of some Join View Adapter's capabilities:

  • Attributes from multiple adapters and object classes can be merged into a new virtual entry.

  • Each adapter can have specific attributes selected for display during a search.

  • Each adapter can subscribe to changes for any attribute during a modify operation.

  • Support for nested Join View Adapters where a primary or joined adapter can be another Join View Adapter.

  • Support for recursive Join View Adapters that perform a join with itself and the recursive structure ends when no join entry is found.

  • For each joined adapter entry returned, the Join View Adapter adds an attribute value, vdejoindn, that indicates which entries in the joined adapters were used to form the consolidated entry.

The following are important aspects about the Join View Adapter, including:

Join View Adapter's Primary Adapter

Each Join View Adapter requires one—and only one—primary adapter to be identified. The primary adapter is used for creating and searching the directory tree entries. The Join View Adapter operates by taking each entry found in the primary adapter and joining it with entries in other adapters according to the defined join relationship. An entry must exist in the Join View Adapter's primary adapter for it to also exist in the Join View Adapter. By default, the primary adapter is used for processing authentication credentials. Any joined adapter may also be used for binding.

Join Rules

Each Join View Adapter may have zero or more join rules that specify a join relationship between an entry in a primary adapter and an entry in a joined adapter. A join rule consists of a join relationship, the adapter it is joining, and some simple join configuration information, such as userprincipalname=uid search criteria. Join rules are processed in the order defined and run in cumulative fashion. As each join is processed, the resulting joined entry is used for the next join relationship.

Refer to Join Relationships for more information.

Join View Adapter Routing

The Join View Adapter relies on several routing attributes, specifically, Routing Retrievable and Routing Storable, to determine which attributes are retrievable and modifiable for each adapter. You can use the Visibility routing attribute to hide primary and joined adapters that are used to form the Join View Adapter.

Searching Join View Adapters

By default, Join View Adapters only search the primary adapter. However, you can use the ForkJoin plug-in to enable searching across attributes in "Joined" sources.

See:

"ForkJoin Plug-In" for more information.

You have two adapters: A and B. Adapter A is the Primary Adapter and contains uid, sn, and cn. Adapter B contains uid, mail, and employeeNumber. You create a Join View Adapter C with adapter A as the Primary Adapter and adapter B as the secondary adapter, and search on uid. Oracle Virtual Directory searches adapter A and finds the entry, then searches adapter B to find any matching join entries. The search returns an entry that contains uid, sn, cn, mail, and employeeNumber.

If client requests all attributes to be returned, that is, there is no list of attributes after the search operation, Oracle Virtual Directory requests all attributes from the joined adapters. However, if the client specifies a list of attributes to be returned, those attributes are extended internally with the attributes from the join condition and Oracle Virtual Directory requests only that list of attributes from the joined adapters. For performance reasons, only the attributes specified by the client—not the attributes in the join condition—are returned. Limiting the number of attributes to be returned from an LDAP server, regardless of Oracle Virtual Directory or using a Join View adapter, helps improve performance.

Duplicate Attributes in Join View Adapters

The Join View Adapter shows only a single value if there are multiple attributes with the same name from multiple data sources (such as two uids from two different LDAP Adapters) and you configure the Join View Adapter to retrieve attribute values only from a specific adapter. To show only the attribute from a specific adapter, ensure the attribute is not listed in the Retrievable Attributes field in the Routing settings for the adapter you do not want to show the attribute for. Optionally, you can hide specific attributes using a Mapping or Plug-in.

2.5.1 Typical Join View Adapter Deployments

The Join View Adapter presents dynamic, real-time joined views of data—no synchronization is required, allowing it to be especially useful to address the following typical identity management tasks:

  • Password consolidation with Microsoft Active Directory

    If you are using Microsoft Active Directory as your central user identity repository, you can avoid the cumbersome password consolidation process by using the Join View Adapter. The Join View Adapter eliminates the need to export password information from Active Directory to other application directories by joining the two. Using the Join View Adapter, gives clients a view of the application directory data, but binds using the Active Directory data.

  • Data Integration

    Using the Join View Adapter allows Oracle Virtual Directory to create a unified view of a user by joining multiple data sources, including databases and directories.

  • Application Integration

    Some applications, especially custom applications, have unique data requirements and it is often difficult to alter the enterprise's directory schema to accommodate those unique requirements. Using the Join View Adapter, you can use data in the enterprise directory and also manage the unique custom application data in a different directory or the Local Store Adapter.

2.5.2 Join Relationships

Each Join View Adapter requires a separate primary adapter. You combine the Join View Adapter and the primary adapter by creating join relationships, sometimes called "Joiners." The join relationship is a set of routines that define how joins are formed and how they impact all directory operations on behalf of the client. Oracle Virtual Directory provides an extensible Joiner class that you can use to provide custom logic. The Joiner class also includes an API that enables you to provide pre-processing and DN mapping logic for each LDAP operation (for example, preAdd, preModify, preGet, preDelete, preRename).

You can also use a Join View Adapter without a join relationship to copy an existing adapter into a new part of the directory tree. This has the advantage of sharing the original adapter's connection pool without creating duplicate adapters.

The following is a description of the supported join relationships types, including:

2.5.2.1 Simple Joiner

The Simple join relationship defines a one-to-one relationship between the entries in the primary adapter and the Join View Adapter by comparing their attributes using a simple join relationship in the form remoteattribute=primaryadapterattribute where remoteattribute is an attribute in the target joined adapter and primaryadapterattrinute is an attribute from the primary adapter. A more complex criteria is possible by using a comma separated list of conditions which creates a multi-condition join where all conditions are anded together. For example, uid=uid,sn=sn,mail=mail.

If multiple matching attributes exist, Oracle Virtual Directory uses the first matching attribute. Oracle Virtual Directory applies Add, Delete, and Rename LDAP operations only to the primary adapter and ignores these operations in the Join View Adapter.

Figure 2-1 shows a a high-level example of a Simple Join used for authentication:

Figure 2-1 Example Simple Join for Authentication

Example Simple Join used for authentication.

2.5.2.2 Conditional Simple Joiner

As described in the "Simple Joiner" section, the Simple Joiner joins entries from two adapters based on a shared attribute value. The Conditional Simple join relationship extends the Simple Joiner functionality so that the join only occurs because of an additional condition. The Conditional Simple join relationship uses a ; character in the join rule to extend a Simple Join relation and add a condition, such as "employeenumber>0" for which the join may only occur on.

For example, a Simple Joiner condition could be: employeenumber=employeenumber

You can extend this Simple Joiner rule and add a condition using the ConditionalSimpleJoiner and the ; character, for example:

employeenumber=employeenumber;(&(employeenumber=101)(sn=Smith))

2.5.2.3 OneToMany Joiner

The OneToMany join relationship defines a one-to-many relationship between multiple primary adapters and the Join View Adapter. Similar to the Simple join relationship, the OneToMany join relationship locates attributes in the Join View Adapter by comparing attributes, however, all matching entries in the Join View Adapter are included in the relationship between adapters. The OneToMany Join is useful to consolidate multiple role objects or identities into one virtual entry. Also similar to the Simple join relationship, Oracle Virtual Directory applies Add, Delete, and Rename LDAP operations only to the primary adapter and ignores these operations in the Join View Adapter when using the OneToMany join relationship.

Figure 2-2 shows an example where a policy server must make policy decisions about an individual. For integration purposes, the policy server prefers to see a single entry with the rights of the user exposed as a privilege attribute, which allows the policy server to test rights assertions with queries such as:

ldapsearch –b "uid=e027451,ou=People,o=LargeCo" –s base "(priv=XYZ Mgr)"

The OneToMany Joiner is used to match one or more privileges to a user based on a profile attribute in their main ou=People entry. The OneToMany Joiner looks for all privileges with the same profile value as in the entry and merges them with the entry. A second stage join uses the Simple Joiner so that the SunOne Directory combined profile is used with the user's Active Directory credentials.

Figure 2-2 Example OneToMany Join

Example OneToMany Join.

2.5.2.4 Shadow Joiner

Use the Shadow Joiner when you must store entries in a source such as an LDAP or Database Adapter that requires a schema extension—but the schema extension is not possible either for business or technical reasons. The Shadow Joiner enables you to the extended attributes in another store, such as a Local Store Adapter or in another LDAP directory that supports the extensibleobject objectclass like Oracle Internet Directory or Oracle Directory Server Enterprise Edition (formerly Sun™ Java System Directory Server) (Microsoft Active Directory does not currently support the extensibleobject objectclass).

Note:

Oracle recommends using the Local Store Adapter as a store for a Shadow Join attributes only for testing and demonstration purposes. For production environments, use Oracle Internet Directory as the Shadow Join data store.

The Shadow join relationship maintains the same structure of the entry in the primary adapter, but stores additional attributes by creating shadow entries using a separate adapter. Using the Shadow Join relationship, applications can use the enterprise directory and also store application-specific attributes in the Join View Adapter's data store. The application believes it is communicating to a directory that stores all attributes, but Oracle Virtual Directory is actually quietly storing application-specific data in an alternate shadow directory. The shadow attributes are only visible after attributes with values are added to the joined entry DN.

The Shadow Joiner requires that the directory that stores the data must support the ExtensibleEntry objectclass and the vdeshadowobject objectclass must be defined. The extensibleobject objectclass defines an object that may contain any attribute and is not supported by all LDAPv3 server products (it is an optional item in the IETF RFC 2251). The Shadow Joiner uses the extensibleobject and the vdeshadowobject objectclasses to store the local entries because local entries may only contain one or more attributes and may not form valid objectclasses. Typically, the Local Store Adapter is used to store local entries, however you can use any LDAP directory that supports the extensibleobject objectclass and where the vdeshadowobject objectclass has been defined.

Note:

Oracle Internet Directory supports the ExtensibleEntry objectclass.

The Shadow Joiner works by encoding all primary adapter DNs into a hash that you can use to locate the joined entry in the joined adapter without needing to perform a search. When the Shadow Joiner fails to locate a corresponding record in the Join View adapter, it automatically creates a new one, storing designated attributes in the joined adapter. As much as possible, the Shadow Joiner operates transparently to the application, taking care of creating and renaming entries that are synchronized with that of the primary adapter.

Note:

A shadow join works well with most Oracle applications that require schema changes on the user record, such as Oracle Access Manager 10g. However, you cannot use a shadow join to eliminate schema changes with Oracle Virtual Directory-Enterprise User Security because the user password hash must be stored in the Active Directory user record, and Oracle Virtual Directory uses an extended attribute, orclCommonAttribute, for this purpose.

It is possible to store the password hash in a different directory by using Oracle Internet Directory-Enterprise User Security with Directory Integration Platform. Directory Integration Platform intercepts the password change and sends it to Oracle Internet Directory to be stored.

The Shadow Joiner supports all LDAP operations. When an LDAP modify operation occurs, the Shadow Joiner examines the parameters identified by the adapter's Storable Attributes routing parameters to see if any attributes are to be stored in the Shadow Join adapter. If any such attributes exist, the Shadow Joiner attempts to locate the local entry by taking the MD5 hash of the primary entry and locating the local entry. After it is located the appropriate LDAP modify operation is performed locally. If a local entry is not found, the Shadow Joiner attempts a secondary search, in case the primary DN changed, to locate the entry using a primary key. If no local entry is found, a new entry is automatically created.

Figure 2-3 shows a CheckPoint firewall configured to connect to an Oracle Virtual Directory. The Oracle Virtual Directory uses Oracle Internet Directory to maintain the CheckPoint firewall schema, allowing integration of the CheckPoint firewall into the corporate enterprise directory without requiring that the corporate enterprise directory schema be extended with application-specific data. Instead, by storing it in Oracle Internet Directory, the application-specific data can be managed by the team responsible for the CheckPoint firewall management.

Figure 2-3 Example Shadow Join Use for Storing Application-Specific Data Locally

Shadow Join for storing application-specific data locally.

2.5.2.5 Custom Join

The Join View Adapter also supports Java-based plug-in join relationships allowing you to implement different and complex relationships. For example, where joins are performing multi-step operations, a custom join can provide specific recovery mechanisms suitable for the scenario at hand. Refer to Chapter 4, "Understanding Oracle Virtual Directory Plug-Ins" for more information on Java-based plug-ins.

2.6 Understanding the Custom Adapter

Oracle Virtual Directory supports the ability to create custom adapters using plug-ins that can connect to almost any data source with a defined API. Refer to "Creating and Configuring Custom Adapters" for information on deploying custom adapters.

2.7 Understanding How Adapters Create the Virtual Directory

This section provides the following examples to demonstrate how adapters are used to create the virtual directory:

2.7.1 Example of a Basic Virtual Directory

Figure 2-4 shows a virtual directory structure for a directory that has a base of o=YourCompany,c=US and the following main branches:

  • ou=Airius which points to a partner LDAP directory

  • ou=People which points to an internal RDBMS

  • ou=Groups with group and role information to be stored in the local Oracle Virtual Directory directory store

Figure 2-4 Example Virtual Directory Structure

Example virtual directory structure.

The virtual directory in Figure 2-4 requires the following adapters:

  • an LDAP Adapter

  • a Database Adapter

  • a Local Store Adapter

The following list describes how the adapters are configured in Figure 2-5 to create the virtual directory:

  • Adapter 0: Local Store Adapter

    This adapter forms the base of the directory and holds entries that are not proxied. In this case, the directory entries under Groups are stored in the local directory.

  • Adapter 1: LDAP Adapter

    This adapter specifies a remote LDAP directory and a remote base which is mapped into the virtual directory tree. In this case, all entries under o=Airius.com in the remote server are made to appear as if they were ou=Airius,o=YourCompany,c=US in the virtual directory.

  • Adapter 2: Database Adapter

    This Database adapter is a database connection specifying that two tables are used to form entries in the directory. In this case, records from the joined queries of two tables is used to form user objects in the namespace ou=People,o=YourCompany,c=US in the virtual directory.

Figure 2-5 Adapters Configured for Example Virtual Directory

Virtual directory sourced from different repositories.

As shown in Figure 2-5, Oracle Virtual Directory and its adapters allow different portions of the directory tree to be sourced from different repositories. In planning your virtual directory information tree structure, be sure you do not have two adapter roots that occupy the same root node. However, you may have an adapter appear to be a child node of another adapter.

2.7.2 Example of a Virtual Directory Using the Join View Adapter

Figure 1-2 in Chapter 1, "Understanding Oracle Virtual Directory," shows an example of an enterprise application used by all employees in a company. The application accesses directory information from three different sources and each contains a separate population of users. The topology in Figure 2-6 and in Figure 1-2 is the same; however, all three directory sources on the right side of Figure 2-6 contain the same user population.

Figure 2-6 Directory Virtualization with the Same User Population

Directory virtualization with the same user population.

Figure 2-6 shows a main enterprise directory which contains the main source of enterprise directory information for all users. For example, imagine for each user in the enterprise directory you want to match them to a corresponding account in Microsoft Active Directory for user-authentication purposes. Also, to gain access to personnel related application information in the corporate database, you must associate each user in the enterprise directory with a table entry in the enterprise database.

To address the requirements in Figure 2-6, you would configure Oracle Virtual Directory with the following four adapters:

  • Adapter 0 is for local application storage and to hold the root position in the tree.

  • Adapter 1 is defined to proxy to Active Directory.

  • Adapter 2 proxies to the Enterprise LDAP directory.

  • Adapter 3 is a Database Adapter that maps in the appropriate user records within the corporate RDBMS.

  • Adapter 4 is a Join View Adapter. In this case, Adapter 2 for the Enterprise Directory, is used as the primary adapter and therefore all entries displayed by Adapter 4 exactly mirror the entries in Adapter 2. With nothing else defined, the Join View Adapter is a carbon copy of Adapter 2.

After configuring the adapters you must define join relationships. In this situation you define two join relationships: one to Active Directory and one to the corporate RDBMS. For the Active Directory join, you define a Simple Join in Adapter 4 to Adapter 2—note that you are really joining with the primary adapter, Adapter 1.

To complete the join, specify unique criteria that joins entries in Active Directory to the primary adapter. As shown in Figure 2-7, use uid=userprincipalname where uid is in Adapter 1 and userprincipalname is in Adapter 2 (Active Directory). For the second join, you join with Adapter 3 using a Simple Join and use uid=userid to achieve a unique match.

Figure 2-7 Specifying Unique Criteria Between Joins

Unique criteria between Joins

Lastly, because you want to use Adapter 1 for authentication rather than the primary adapter (Adapter 2), you set the bindadapter setting to 1, causing the Join View Adapter to test authentication against the joined adapter rather than the primary adapter.

Note:

If you wanted users to match multiple RDBMS records (for example, a privilege table), you could specify a OneToMany Join such as approle=priv. In this case approle would be an attribute in the enterprise directory. The approle attribute matches up with a series of privileges in the RDBMS. By performing the join in this example, you would translate a simple role into a series of privileges.

After Adapter 4 is configured, you can hide Adapters 1, 2, and 3 from end users by setting Routing Visibility on each of these adapters to Internal. This results in a directory that appears to have a single ou=People,o=AppView branch. As you browse the directory below ou=People, you are querying Adapter 4, the Join View Adapter. When the Join View Adapter receives queries, it automatically transforms and passes them on to the other three hidden adapters. Ultimately the application perceives that there is only a single entry for each person.

2.8 Understanding Adapter Namespaces

Figure 2-8 shows a source directory tree structure where there are four separate directories. The goal is to combine all four separate directories into one new directory tree design. The most basic directory tree design you can implement with Oracle Virtual Directory is with no translation so the source directory structure with four separate directory trees is valid within Oracle Virtual Directory and it is operating as a pure directory proxy using no translation features.

Figure 2-8 Example Source Directory Tree Structure with Four Separate Directories

Source directory structure with 4 separate directories.

Figure 2-9 shows that two external companies were added as descendants to o=YourCompany, c=US. In this example, Adapter 1 and Adapter 2 occupy subtree entry positions relative to Adapter 0. At the same time, Adapter 3 is left occupying a separate namespace, which could represent a third-party company that provides administrative network services and may not participate in the business application of the other three organizations. In this is the case, it may be best to keep the ISP directory entries separated.

Figure 2-9 Example Source Directory Tree Structure with Two Additions

Two additions have been made to Figure 2-8.

Figure 2-10 shows the directory structure after it was redesigned so that all partner users are under the ou=People branch. This requirement may be due to a limitation in an application (for example, it only authenticates users from a single base of ou=People, o=YourCompany, c=US). Notice that YourCompany's people entries are directly under ou=People while the partner directories are contained within organization units under ou=People. Keeping the organization unit allows for easier creation of access control groups and roles specific to users of those partners and avoids namespace conflicts. Notice also that only one adapter may occupy any particular node in the tree.

Figure 2-10 Redesigned Source Directory Tree Example

Figure 2-9 after it has been redesigned.

Figure 2-11 shows an example where two problems were created due to conflicts between entries stored in Adapter 0 and the root entry of Adapters 1 and 3. During search operations, Oracle Virtual Directory searches the overlapping namespace and return matches from all adapters. However, during modify operations, Oracle Virtual Directory only processes entries in the adapter that are matched first walking up the tree from the entry (in this example, Adapters 1 and 3 because Adapter 0 is further up the tree).

Figure 2-11 Example of an Overlapping Directory Structure

Example of an overlapping directory structure.

Traditionally, the overlapped directory structure would be unacceptable, however, Oracle Virtual Directory supports routing filters that control how it handles operations to overlapping namespaces.

2.9 Understanding Adapter Templates

Oracle Virtual Directory includes adapter templates to help simplify the process for configuring adapters. When you create an adapter, the New Adapter screen contains an Adapter Template list that displays the available templates for each adapter. After selecting an adapter template, Oracle Directory Services Manager automatically populates default values for some adapter settings. You should alter these default settings according to your environment.

The following sections list and describe the adapter templates:

2.9.1 Default Template

The Default template is a general template available for all adapter types and is not specific to any one vendor's directory. You should use the Default template if no other template satisfies your needs.

2.9.2 LDAP Adapter Templates

The following sections describe the LDAP Adapter templates:

Note:

Some adapter templates use Python mapping scripts. The template configures the mapping script with the adapter's information, but the template does not deploy the mapping script. If you use an adapter template that uses a mapping script, you must explicitly deploy the mapping script to the Oracle Virtual Directory server after configuring the adapter.

2.9.2.1 Active_Directory

Use the Active_Directory template when connecting to a Microsoft Active Directory or Active Directory Application Mode target and you do not want to map Active Directory objects to InetOrgPerson objects.

Note:

If you are connecting to a Microsoft Active Directory or Active Directory Application Mode target and you do want to map Active Directory objects to InetOrgPerson objects, use the OAM/AD Adapter with Mapper template even if you are not integrating with Oracle Access Manager.

2.9.2.2 CA_eTrust

Use the CA_eTrust template when connecting to a Computer Associates (CA) eTrust directory.

2.9.2.3 Changelog_LDAP-TYPE

Use the Changelog_LDAP-TYPE templates when you require the source LDAP directory's changelog information to be standardized into a suitable format. Oracle Virtual Directory includes adapter templates for Microsoft Active Directory (Changelog_ActiveDirectory), Oracle Internet Directory (Changelog_OID), and Oracle Directory Server Enterprise Edition (Changelog_SunOne).

Each Changelog_LDAP-Type template deploys the Changelog plug-in.

Note:

Table 2-1 is deprecated in Oracle Virtual Directory release 11.1.1.4.0. The adapter templates noted in this table will not work in Oracle Virtual Directory release 11.1.1.4.0.

Table 2-1 Changelog Adapter Templates

Source LDAP Directory Adapter Template Plug-In Deployed by Adapter Template

Oracle Internet Directory

Changelog_OID

oidchangelog

Microsoft Active Directory

Changelog_ActiveDirectory

adchangelog

Oracle Directory Server Enterprise Edition

Changelog_SunOne

sunonechangelog


2.9.2.4 EUS_ActiveDirectory

Use the EUS_ActiveDirectory template for an Oracle Virtual Directory-Enterprise User Security integration that uses Active Directory. The EUS_ActiveDirectory simplifies the integration by deploying the following plug-ins:

  • Objectclass Mapper: Maps certain Oracle attributes and object classes so they can be managed in Active Directory.

  • Active Directory Password: Allows storage of database password into Active Directory when database registers with the directory.

  • EUSActiveDirectory: Converts certain Active Directory attributes, such as GUID, into a format that Enterprise User Security can use.

2.9.2.5 EUS_OID

Use the EUS_OID template for an Oracle Virtual Directory-Enterprise User Security integration that uses Oracle Internet Directory. The EUS_OID simplifies the integration by deploying the EUSOID plug-in, which converts certain attributes to a consistent format for use with Enterprise User Security.

2.9.2.6 EUS_Sun

Use the EUS_Sun template for an Oracle Virtual Directory-Enterprise User Security integration that uses Oracle Directory Server Enterprise Edition. The EUS_Sun simplifies the integration by deploying the following plug-ins:

  • Objectclass Mapper: Maps certain Oracle attributes and object classes so they can be managed in Oracle Directory Server Enterprise Edition.

  • EUSSun: Converts certain Oracle Directory Server Enterprise Edition attributes, such as GUID, into a format that Enterprise User Security can use.

2.9.2.7 EUS_eDirectory

Use the EUS_eDirectory template for Oracle Virtual Directory-Enterprise User Security integrations that use Novell eDirectory. The EUS_eDirectory simplifies the integration by deploying the following plug-ins:

  • Objectclass Mapper: Maps certain Oracle attributes and object classes so they can be managed in eDirectory.

  • EUSeDirectory: Converts certain eDirectory attributes into a format that Enterprise User Security can use.

2.9.2.8 General_LDAP_Directory

The General_LDAP_Directory template is identical to the Default Template.

2.9.2.9 IBM_Directory

Use the IBM_Directory template when connecting to an IBM Directory Server.

2.9.2.10 Novell_eDirectory

Use the Novell_eDirectory template when connecting to a Novell eDirectory.

2.9.2.11 OAM/AD Adapter with Mapper

Oracle suggests using this template for an Oracle Virtual Directory-Oracle Access Manager integration that uses Microsoft Active Directory, though other applications can benefit from using this template. The OAM/AD Adapter with Mapper template simplifies the LDAP Adapter's interaction with Active Directory by deploying the following plug-ins:

  • Active Directory Ranged Attributes: converts ranged attributes, which are attributes with several multi-valued values that Active Directory splits into multiple requests, often confusing clients, into a single request.

  • ObjectClass Mapper: maps Active Directory User/Group objects into InetOrgPerson/GroupOfUniqueName objects.

  • ActiveDirectory Password: converts the standard userPassword attribute into Microsoft's unicodePWD attribute. Additionally, to have the adapter connect to Active Directory over a non-SSL port, this plug-in can route password updates to a different adapter instance that connects to the Active Directory server over SSL (because Active Directory requires password changes over LDAP to use SSL). If the adapter is set to use SSL, remove the host name from the plug-in configuration. If the adapter is set not to use SSL, set the plug-in host name to the name of the Active Directory adapter connected to Active Directory over SSL.

  • Dump Before: a version of the Dump Transaction plug-in that dumps the values of the operation to vde.log before passing data to plug-ins.

  • Dump After: a version of the Dump Transaction plug-in that dumps the values of the operation to vde.log after passing data to plug-ins.

Note:

The OAM/AD Adapter with Mapper template is similar to the OAM/AD Adapter with Script template but it does not require you to deploy an additional mapping script like the OAM/AD Adapter with Script template does.

2.9.2.12 OAM/AD Adapter with SSL, Mapper

Configures an LDAP Adapter to connect to an Active Directory target over SSL for password change operations only in an Oracle Virtual Directory-Oracle Access Manager integration. By default, the adapter's Visibility routing setting is set to internal, hiding the adapter to clients and making it accessible only through plug-ins like the Active Directory Password plug-in.

2.9.2.13 OAM/AD Adapter with Script

Similar to the OAM/AD Adapter with Mapper template except that it uses the OblixADMapping Python mapping script to do attribute renaming instead of the ObjectClass mapper. The OAM/AD Adapter with Script template simplifies the LDAP Adapter's interaction with Active Directory by deploying the following plug-ins:

  • Active Directory Ranged Attributes: converts ranged attributes, which are attributes with several multi-valued values that Active Directory splits into multiple requests, often confusing clients, into a single request.

  • ActiveDirectory Password: converts the standard userPassword attribute into Microsoft's unicodePWD attribute. Additionally, to have the adapter connect to Active Directory over a non-SSL port, this plug-in can route password updates to a different adapter instance that connects to the Active Directory server over SSL (because Active Directory requires password changes over LDAP to use SSL). If the adapter is set to use SSL, remove the host name from the plug-in configuration. If the adapter is set not to use SSL, set the plug-in host name to the name of the Active Directory adapter connected to Active Directory over SSL.

  • Dump Before: a version of the Dump Transaction plug-in that dumps the values of the operation to vde.log before passing data to plug-ins.

  • Dump After: a version of the Dump Transaction plug-in that dumps the values of the operation to vde.log after passing data to plug-ins.

The OAM/AD Adapter with Script template also configures the OblixADMapping script using the adapter's information. The OblixADMapping script is similar to ObjectClass mapper which maps Active Directory User/Group objects into InetOrgPerson/GroupOfUniqueName objects.

Note:

You must explicitly deploy the OblixADMapping mapper script to the Oracle Virtual Directory server after configuring the adapter with the OAM/AD Adapter with Script template.

If you can use either the OAM/AD Adapter with Script template or the OAM/AD Adapter with Mapper template to obtain equal results, you may want to use the OAM/AD Adapter with Mapper template because the OAM/AD Adapter with Script template requires you to explicitly deploy the OblixADMapping mapper script to the Oracle Virtual Directory server after configuring the adapter and the OAM/AD Adapter with Mapper template does not.

2.9.2.14 OAM/ADAM Adapter with Mapper

Oracle suggests using this template for an Oracle Virtual Directory-Oracle Access Manager integration that uses Microsoft Active Directory Application Mode, though other applications can benefit from using this template. The OAM/ADAM Adapter with Mapper template simplifies the LDAP Adapter's interaction with Active Directory Application Mode by deploying the following plug-ins:

  • Active Directory Ranged Attributes: converts ranged attributes, which are attributes with several multi-valued values that Active Directory splits into multiple requests, often confusing clients, into a single request.

  • ObjectClass Mapper: maps Active Directory User/Group objects into InetOrgPerson/GroupOfUniqueName objects.

  • ActiveDirectory Password: converts the standard userPassword attribute into Microsoft's unicodePWD attribute. Additionally, to have the adapter connect to Active Directory over a non-SSL port, this plug-in can route password updates to a different adapter instance that connects to the Active Directory server over SSL (because Active Directory requires password changes over LDAP to use SSL). If the adapter is set to use SSL, remove the host name from the plug-in configuration. If the adapter is set not to use SSL, set the plug-in host name to the name of the Active Directory adapter connected to Active Directory over SSL.

  • Dump Before: a version of the Dump Transaction plug-in that dumps the values of the operation to vde.log before passing data to plug-ins.

  • Dump After: a version of the Dump Transaction plug-in that dumps the values of the operation to vde.log after passing data to plug-ins.

Note:

The OAM/ADAM Adapter with Mapper template is similar to the OAM/ADAM Adapter with Script template, but it does not require you to deploy an additional mapping script like the OAM/ADAM Adapter with Script template does.

2.9.2.15 OAM/ADAM Adapter with SSL, Mapper

Configures an LDAP Adapter to connect to an Active Directory Application Mode target over SSL for password change operations only in an Oracle Virtual Directory-Oracle Access Manager integration. By default, the adapter's Visibility routing setting is set to internal, hiding the adapter to clients and making it accessible only through plug-ins like the Active Directory Password plug-in.

2.9.2.16 OAM/ADAM Adapter with Script

Similar to the OAM/ADAM Adapter with Mapper template except that it uses the OblixADMapping Python mapping script to do attribute renaming instead of the ObjectClass mapper. The OAM/ADAM Adapter with Script template simplifies the LDAP Adapter's interaction with Active Directory Application Mode by deploying the following plug-ins:

  • Active Directory Ranged Attributes: converts ranged attributes, which are attributes with several multi-valued values that Active Directory splits into multiple requests, often confusing clients, into a single request.

  • ActiveDirectory Password: converts the standard userPassword attribute into Microsoft's unicodePWD attribute. Additionally, to have the adapter connect to Active Directory over a non-SSL port, this plug-in can route password updates to a different adapter instance that connects to the Active Directory server over SSL (because Active Directory requires password changes over LDAP to use SSL). If the adapter is set to use SSL, remove the host name from the plug-in configuration. If the adapter is set not to use SSL, set the plug-in host name to the name of the Active Directory Application Mode adapter connected to Active Directory over SSL.

  • Dump Before: a version of the Dump Transaction plug-in that dumps the values of the operation to vde.log before passing data to plug-ins.

  • Dump After: a version of the Dump Transaction plug-in that dumps the values of the operation to vde.log after passing data to plug-ins.

The OAM/ADAM Adapter with Script template also configures the OblixADMapping script using the adapter's information. The OblixADMapping script is similar to ObjectClass mapper which maps Active Directory User/Group objects into InetOrgPerson/GroupOfUniqueName objects.

Note:

You must explicitly deploy the OblixADMapping mapper script to the Oracle Virtual Directory server after configuring the adapter with the OAM/ADAM Adapter with Script template.

If you can use either the OAM/ADAM Adapter with Script template or the OAM/ADAM Adapter with Mapper template to obtain equal results, you may want to use the OAM/ADAM Adapter with Mapper template because the OAM/ADAM Adapter with Script template requires you to explicitly deploy the OblixADMapping mapper script to the Oracle Virtual Directory server after configuring the adapter and the OAM/ADAM Adapter with Mapper template does not.

2.9.2.17 OAM/SunOne Adapter with Mapper

Configures an LDAP Adapter to connect to a SunOne directory target in an Oracle Virtual Directory-Oracle Access Manager integration and converts SunOne attributes for use with Oracle Access Manager. The OAM/SunOne Adapter with Mapper template simplifies the LDAP Adapter's interaction with SunOne by deploying the following plug-ins:

  • ObjectClass Mapper: Filters out the nsaccountlock attribute and marks the directory type as SunOne.

  • Dump SunOne: Dumps output of plug-in activity to vde.log.

2.9.2.18 OAM/SunOne Adapter with Script

Similar to the OAM/SunOne Adapter with Mapper template except that it uses the OblixSunOneMapping Python mapping script to do attribute renaming instead of the ObjectClass mapper. Oracle suggests using the OAM/SunOne Adapter with Mapper template instead of the OAM/SunOne Adapter with Script template for first and fresh installations.

The OAM/SunOne Adapter with Script template simplifies the LDAP Adapter's interaction with SunOne by deploying the Dump Transactions plug-in, which dumps output of plug-in and mapping activity to vde.log.

The OAM/SunOne Adapter with Script template also configures the OblixSunOneMapping script using the adapter's information. The OblixSunOneMapping is similar to ObjectClass mapper which filters out the nsaccountlock attribute and marks the directory type as SunOne.

Note:

You must explicitly deploy the OblixSunOneMapping mapper script to the Oracle Virtual Directory server after configuring the adapter with the OAM/SunOne Adapter with Script template.

If you can use either the OAM/SunOne Adapter with Script template or the OAM/SunOne Adapter with Mapper template to obtain equal results, you may want to use the OAM/SunOne Adapter with Mapper template because the OAM/SunOne Adapter with Script template requires you to explicitly deploy the OblixSunOneMapping mapper script to the Oracle Virtual Directory server after configuring the adapter and the OAM/SunOne Adapter with Mapper template does not.

2.9.2.19 ONames_LDAP-TYPE

Use the ONames_LDAP-TYPE adapter templates only when integrating Oracle Virtual Directory with Oracle Net Services. Oracle Virtual Directory includes ONames adapter templates for Microsoft Active Directory (ONames_ActiveDirectory), Oracle Internet Directory (ONames_OID), and Oracle Directory Server Enterprise Edition (ONames_Sun).

Each ONames_LDAP-TYPE template deploys only the ONames plug-in, which removes entries that are specific to the source LDAP directory to facilitate the Oracle Virtual Directory-Oracle Net Services integration.

2.9.2.20 Oracle_Internet_Directory

Use the Oracle_Internet_Directory template when connecting to an Oracle Internet Directory (OID).

2.9.2.21 Siemens_DirX

Use the Siemens_DirX template when connecting to a Siemens DirX directory.

2.9.2.22 SunOne_Directory

Use the SunOne_Directory template when connecting to any directory in the Netscape family of directories, including Netscape, Sun Microsystems, and Fedora.

2.9.2.23 User_LDAP-TYPE

Use the User_LDAP-TYPE adapter templates for Oracle Virtual Directory-Oracle Identity Manager integrations that require data mapping for Oracle Identity Manager attributes to LDAP directory servers. Oracle Virtual Directory includes adapter templates for Microsoft Active Directory (User_ActiveDirectory), Oracle Internet Directory (User_OID), and Oracle Directory Server Enterprise Edition (User_SunOne).

Each User_LDAP-TYPE template deploys the UserManagement plug-in.

2.9.3 Local Store Adapter Templates

The following sections describe the Local Store Adapter templates:

2.9.3.1 Local_Storage_Adapter

The Local_Storage_Adapter template is identical to the Default Template.

2.9.4 Database Adapter Templates

The following section describes the Database Adapter templates:

2.9.4.1 OAM/DB Adapter with Script

Configures a Database Adapter to connect to a database target in an Oracle Virtual Directory-Oracle Access Manager integration and uses a Python mapping script handle business logic. The OAM/DB Adapter with Script template simplifies the Database Adapter's interaction with Oracle Access Manager by deploying the following plug-ins:

  • DumpDB1: a version of the Dump Transaction plug-in that dumps the output of operations to vde.log before passing data to plug-ins and mappings.

  • DumpDB2: a version of the Dump Transaction plug-in that dumps the output of operations to vde.log after passing data to plug-ins and mappings.

The OAM/DB Adapter with Script template also configures the Oblix_OAMMapping script using the adapter's information. The Oblix_OAMMapping script provides business logic for the Oracle Access Manager integration, such as removing Oracle Access Manager specific objectclasses that must be removed before entries can be added.

Note:

You must explicitly deploy the Oblix_OAMMapping mapper script to the Oracle Virtual Directory server after configuring the adapter with the OAM/DB Adapter with Script template.