Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Virtual Directory
11g Release 1 (11.1.1)

Part Number E10046-07
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

4 Understanding Oracle Virtual Directory Plug-Ins

This chapter describes Java plug-ins for Oracle Virtual Directory and includes the following topics:

4.1 What is a Plug-In?

Plug-ins allow you to extend Oracle Virtual Directory with compartmentalized functionality to meet specific business and technical requirements. You can use plug-ins to provide custom logic as part of a transaction or to connect to a custom data source. Oracle Virtual Directory supports two types of plug-ins: Java plug-ins and Python Mapping plug-ins.

Note:

This chapter is specific to Java plug-ins for Oracle Virtual Directory, though from an operational perspective, Oracle Virtual Directory treats the two types of plug-ins equally. References to plug-ins in this chapter refer to Java plug-ins. See Chapter 5, "Understanding Oracle Virtual Directory Mapping" for information on mapping plug-ins.

Oracle Virtual Directory includes several plug-ins for various purposes, including plug-ins for analysis, auditing, caching, and dynamic group presentation. You can also deploy plug-ins using different approaches and with full control over the positioning of the plug-in inside the virtual directory, including:

For example, you can deploy the Cache plug-in to run only on a particular Microsoft Active Directory server and only after a mapping has been run to perform translation of the Active Directory user to the standard inetOrgPerson objectclass.

Note:

  • To configure plug-ins at the "global" server level, select Advanced from the Oracle Directory Services Manager task selection bar and refer to "Managing Global Server Plug-ins" for the complete steps in the process.

  • To configure plug-ins at the adapter level, select Adapter from the Oracle Directory Services Manager task selection bar and refer to "Managing Adapter Plug-ins" for the complete steps in the process.

Figure 4-1 shows the three layer architecture of the Oracle Virtual Directory plug-in framework:

Figure 4-1 Oracle Virtual Directory Plug-In Framework

OVD plug-in framework.

Plug-ins are arranged to form chains. When Oracle Virtual Directory receives a request, the request passes through Oracle Virtual Directory in the following sequence (as shown in Figure 4-1):

  1. The Global Service Interface (GSI), then to

  2. The chain of global plug-ins, then to

  3. The Adapter Service Interface (ASI), then to

  4. The chain of adapter plug-ins.

Global plug-ins are called for all requests. For an inbound request, after all global plug-ins have been executed, the request goes to the ASI, which is the component of Oracle Virtual Directory where routing and adapter handling decisions are made. After the routing system has decided which adapters are to be included in a request, the chosen adapter plug-ins are executed. Responses are generated by adapters and then sent back up the chain for further possessing and filtering.

4.1.1 Namespace Filtering

Oracle Virtual Directory provides flexibility in determining whether a plug-in should be executed globally or within the context of a single adapter. In some situations, you may have to further restrict when a plug-in gets used. 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 plug-in or mapping to apply them to only one part of the tree.

4.2 Understanding the General Purpose Plug-Ins

This topic describes the general purpose plug-ins included in Oracle Virtual Directory. The general purpose plug-ins extend Oracle Virtual Directory capabilities to perform special functions or mappings. This topic contains the following sections:

4.2.1 FA UserRole Plug-In

The FA UserRole plug-in allows VDE to redirect add and modify operations to specific adapters. You must only use this plug-in as a global plug-in.

4.2.1.1 Configuration Parameters

The FA UserRole plug-in has the following configuration parameters:

objectWrite

An attribute=value type of filter followed by a list of adapter names that is used to redirect add and modify operations to the list of adapters in the specified sequence.

You can define multiple instances of this configuration. For example: objectclass=user;A1;A2 means if an entry is of the user objectclass, the add and modify operation against the entry is first redirected to adapter A1. If there is no match on A1, the operation will be performed on A2. Another example: cn=user1;A3.

4.2.2 HideEntriesByFilter Plug-In

The HideEntriesByFilter plug-in enables you to control in fine detail which entries are returned by searches. Using its hideFilter configuration parameter, the HideEntriesByFilter plug-in enables you to explicitly control which entries are returned. For example, you are using Oracle Virtual Directory as an address book directory and you want to display only the entries for customer service representatives, which have ou values of CSR. You could use the HideEntriesByFilter plug-in with hideFilter set to ou=CSR so that when the adapter is searched, only the customer service representatives entries are returned.

Support for Bind Operation

When you deploy the HideEntriesByFilter plug-in, it allows only those entries that are exposed by the plug-in to perform a bind operation. The plug-in blocks entries that are hidden during search from performing a bind. Only static hide filters and LdapURL, configured in the HideEntriesByFilter plug-in parameters, are honored during a bind operation and not the dynamic hide filters.

4.2.2.1 Configuration Parameters

The HideEntriesByFilter plug-in has the following configuration parameters:

hideFilter

The LDAP filter that controls which entries are restricted for searches. This filter can contain static filters or dynamic filters.

  • For example, when creating a static filter, if you set hideFilter to (ou=Sales), then searches return only entries that contain ou=Sales. However, if you set hideFilter to (!(ou=Sales)), then searches return only entries that do not contain ou=Sales.

  • You form dynamic filters based on the authenticated user's attribute values. Dynamic filters can support usecases such as "Get all of the users whose department is the same as the bound user's department, without the need for the application to specify this criteria in LDAP search filter".

    For example, if you set the hideFilter to (department=%department%), the plug-in replaces %department% with the actual department value associated with the bound user. If there are multiple values for the specified attribute in the bound user entry, then the filter is created by ORing all the values.

ldapURL

A parameter used to further restrict the search results based on the entry DN. If an entry that is returned as part of search result satisfies the URL filter, then the entry is returned to the client only if it is a descendent of the URL base. If the entry does not satisfy the URL filter, then the entry is returned as is.

This parameter can occur multiple times in a plug-in configuration. At a minimum, you must set either the hideFilter or the ldapURL configuration parameter.

adapterNames

A parameter used in cases where the plug-in is deployed in one adapter and the bound user exists in a different adapter. This parameter takes in a list of adapters, which means it can occur multiple times in a plug-in configuration.

To process a dynamic filter, the user is queried in all the adapters specified in adapterNames. If a search against all adapters fails without returning any users, then the dynamic filter is ignored and the original search filter is sent to next plug-in.

applyForAdmin

Boolean value that controls whether plug-in processing should be executed for administrators. If you set this parameter to false, and the bound user is admin, the search results are returned as is, without being further filtered by the plug-in.

4.2.3 ChangeUserRDN Plug-In

The ChangeUserRDN plug-in enables you to rename or replace RDN values from the source directory to Oracle Virtual Directory. This plug-in is useful during LDAP directory migrations.

4.2.3.1 Configuration Parameters

The ChangeUserRDN plug-in has the following configuration parameters:

objectType

Identifies the objectclass type that RDN renaming is performed on. The default setting is person.

replaceValue

True or False: Indicates whether the original RDN value (identified by the fromRDN parameter) should be replaced by the new RDN value (identified by the toRDN parameter). The default setting is true.

Note:

When the value is set to true, and an entry has multiple values for the new RDN attribute, then Oracle Virtual Directory uses the first value in the attribute value vector in RDN.
fromRDN

Identifies the original RDN attribute name from the source directory to be replaced or renamed in Oracle Virtual Directory.

toRDN

Identifies the new RDN attribute name to be used in Oracle Virtual Directory and replaces the attribute name identified by the fromRDN configuration parameter.

dnAttributes

List of attributes with DNs to perform RDN renaming on. The default list of attributes is member, uniquemember, manager, owner, managedby.

4.2.4 UPNBind Plug-In

The UPNBind plug-in enables you to bind using any configured username attribute, such as cn, SamAccountName, sn, uid, and so on, or username@suffix attributes, such as UserPrincipalName, Mail, and so on. This plug-in is useful for Active Directory-centric applications and can simplify application development by removing the requirement to look-up DNs.

Note:

The UPNBind plug-in is supported only for deployment as a global plug-in—do not deploy the UPNBind plug-in on adapters.

4.2.4.1 Configuration Parameters

The UPNBind plug-in has the following configuration parameters:

Note:

At a minimum, either the NameAttributes or NameAndSuffixAttributes configuration parameter must be set.
NameAttributes

Identifies a list of naming attributes to use for authenticating users. For example: cn, sn, uid, SAMAccountName.

NameAndSuffixAttributes

A list of attributes in the form of name@suffix, such as UPN or mail, to use for authenticating users.

BindOption

Determines how the UPNBind plug-in should process resulting entries when multiple users have same values for the NameAttributes and NameAndSuffixAttributes parameters. The following is a list and description of the supported values for the BindOption option. The default setting is QuickFail.

  • QuickFail: When multiple users have same values for configured attributes, the UPNBind plug-in displays a Found more than one user entry error and the LDAP bind fails.

  • FirstUser: The UPNBind plug-in binds as the first user and returns the result of that bind.

  • FirstSuccess: The UPNBind plug-in binds as the first user. If that bind fails, the UPNBind plug-in proceeds through the list of all users until it finds a successful bind.

AdapterName

Identifies the adapter to use for authentication. If the user entry is not present in the specified adapter, the LDAP bind fails with an Invalid Credentials message. This is an optional parameter. If you do not specify this parameter, the plug-in considers all the available adapters for authenticating the user. This parameter is useful for improving the plug-in's performance when you know which adapter is used for authentication.

4.2.5 ForkJoin Plug-In

Supported only for Join View Adapters, the ForkJoin plug-in enables you to search against the primary adapter, the secondary adapters, or both primary and secondary adapters in a Join View. During LDAP search, when a search filter contains one or more attributes that are available only in secondary adapter, without this plug-in, Oracle Virtual Directory cannot return Joined entries that satisfies the filter, as the entire search filter is sent only to the primary adapter. Using the ForkJoin Plug-in, Oracle Virtual Directory can search on attributes only in the primary adapter, only in the secondary adapter, and in both the primary and secondary adapters.

For example, user data resides in multiple identity sources, with samaccountname, sn, givenname, employeenumber in Active Directory. However, the title attribute is stored in a Human Resources database. If Active Directory is configured as the primary adapter; Human Resources database as the secondary adapter; and if the ForkJoin plug-in is deployed, when an LDAP enabled application queries the user data based on samaccountname, on title, or both Oracle Virtual Directory returns the entry that satisfies the filter and includes both Active Directory and the Human Resources database data.

Support for Bind Operation

When you deploy the ForkJoin plug-in against a Join adapter and the JoinPolicy is set to FullOuterJoin, the bind is allowed — even for secondary-only users that do not exist in the primary adapter at all.

4.2.5.1 Configuration Parameters

The ForkJoin plug-in has the following configuration parameters:

Note:

At a minimum, you must set either the SecondaryOnlyAttributes or PrimaryAndSecondaryAttributes configuration parameter to deploy the ForkJoin plug-in.
SecondaryOnlyAttributes

A list of attributes that are present only in the secondary adapter and which the application can use in the search filter. The attributes identified by the SecondaryOnlyAttributes configuration parameter cannot also be identified by the PrimaryAndSecondaryAttributes configuration parameter.

PrimaryAndSecondaryAttributes

A list of attributes that are present in both the primary and secondary adapters and which the application can use in the search filter. The attributes identified by the PrimaryAndSecondaryAttributes configuration parameter cannot also be identified by the SecondaryOnlyAttributes configuration parameter.

JoinPolicy

Supports the following settings:

  • Standard Join: Returns all entries that satisfy the search filter in the primary adapter after joining the corresponding entries in secondary adapters.

  • Left Outer Join: Returns all the entries in the primary adapter after joining with corresponding entries in secondary adapter (Standard Join), and returns entries from the secondary adapter that satisfy the join condition and which have a corresponding match in primary adapter. This is the equivalent to Left Outer Join in database terminology.

  • Full Outer Join: Returns all the entries in the primary adapter after joining with corresponding entries in secondary adapter (Standard Join); returns entries from the secondary adapter that satisfy the join condition and which have a corresponding match in primary adapter (Left Outer Join); and returns entries from the secondary adapter that satisfy the search filter but do not have a matching entry in primary adapter. This is the equivalent to Left Outer Join + Right Outer Join in database terminology.

    Note:

    For conditional joins when Full Outer Join is configured, the entries in secondary adapter are mapped to entries in primary adapter without considering the filter in join condition.

4.2.5.2 Example ForkJoin Plug-In Deployment

This section provides an example ForkJoin plug-in deployment. The following data resides in the primary adapter and secondary adapter. The primary adapter namespace is dc=primary and the secondary adapter namespace is dc=secondary.

Data in Primary Adapter Data in Secondary Adapter
dn: cn=Rock, dc=primary
objectclass: inetorgperson
cn: Rock
sn: Anne
givenname: Anne rock
telephonenumber: 54300
dn: cn=Rock, dc=secondary
objectclass: inetorgperson
cn: Rock
sn: Anne
title: Manager
dn: cn=Sandy, dc=primary
objectclass: inetorgperson
cn: Sandy
sn: Ketty
manager:  cn=Rock, dc=primary
telephonenumber: 54301
dn: cn=Sandy, dc=secondary
objectclass: inetorgperson
cn: Sandy
sn: Ketty
title: SMTS
dn: cn=Rivry,dc=primary
objectclass: inetorgperson
cn: Rivry
sn: Rod
title: Trainee
manager: cn=Rock, dc=secondary
telephonenumber: 54303
description: Trainee for dept 543
departmentNumber: 543
dn: cn=Rivry,dc=secondary
objectclass: inetorgperson
cn: Rivry
sn: Rod
title: Trainee
dn: cn=Woods,dc=primary
objectclass: inetorgperson
cn: Woods
sn: Tent
description: User with no title
dn: cn=Mounty,dc=secondary
objectclass: inetorgperson
cn: Mounty
sn: Ret
title: MTS - dept_sec

The Join Condition is cn=cn and the SecondaryOnlyAttributes parameter is set to title. An ldapsearch with a subtree scope and filter of (|(title=*e*)(sn=*e*)) is performed against the Join View Adapter.

The following are the search results for each type of JoinPolicy:

Standard Join:

cn=Rock,dc=Join
sn=Anne
cn=Rock
title=Manager
 
cn=Sandy,dc=Join
sn=Ketty
cn=Sandy
title=SMTS
 
cn=Woods,dc=Join
sn=Tent
cn=Woods

Left Outer Join:

cn=Rock,dc=Join
sn=Anne
cn=Rock
title=Manager
 
cn=Sandy,dc=Join
sn=Ketty
cn=Sandy
title=SMTS
 
cn=Woods,dc=Join
sn=Tent
cn=Woods
 
cn=Rivry,dc=Join
sn=Rod
cn=Rivry
title=Trainee

Full Outer Join:

cn=Rock,dc=Join
sn=Anne
cn=Rock
title=Manager
 
cn=Sandy,dc=Join
sn=Ketty
cn=Sandy
title=SMTS
 
cn=Woods,dc=Join
sn=Tent
cn=Woods
 
cn=Rivry,dc=Join
sn=Rod
cn=Rivry
title=Trainee
 
cn=Mounty,dc=Join
sn=Ret
cn=Mounty
title=MTS - dept_sec

4.2.6 VirtualMemberof Plug-In

The VirtualMemberof plug-in adds the memberof attribute to person entries. The values of this memberof attribute are the DNs of any groups the person entry belongs to. The VirtualMemberof plug-in is useful when applications want to see group membership, but do not want to perform a secondary search for the groups.

4.2.6.1 Configuration Parameters

The VirtualMemberof plug-in has the following configuration parameters:

searchBase

The DN of the base to search for groups containing person entries.

explicitrequestonly

True or False: If set to True, the memberof attribute will be added to the entry only if it is explicitly requested as a returned attribute. The default value is True.

adapterName

List of adapters containing group entries. This parameter helps minimize the scope of the search for groups.

4.2.7 VirtualAttribute Plug-In

The VirtualAttribute plug-in enables you to reuse attribute data in multiple attributes without deploying a mapping. For example, when a new application requires a person's full name to be used in their display; but instead of looking for cn, the application wants to use the displayname attribute—which does not exist in the adapter data. Using the VirtualAttribute plug-in, you can map displayname to the value of cn and have the cn attribute remain available for other applications that are looking for it. If the displayname attribute already exists in the adapter data, you can specify whether to add the values of cn to the existing values of displayname or to replace the values of displayname with the values of cn.

In addition to adding and replacing attribute values, you can also use the VirtualAttribute plug-in to

  • Create an attribute on-the-fly by using other attribute and literal values.

  • Perform the functionality of ConditionalPublish mapping. That is, using the RemoveAttributes configuration parameter, you can identify attributes to virtually remove from entries before they are returned to the client.

Note:

Constant values can be specified for the attributes that are added or replaced by the VirtualAttribute plug-in.

4.2.7.1 Configuration Parameters

The VirtualAttribute plug-in has the following configuration parameters:

Note:

At a minimum, you must set either the AddAttribute or ReplaceAttribute configuration parameter.
ContainerDN

An optional parameter, ContainerDN identifies the containers the VirtualAttribute plug-in applies to. The VirtualAttribute plug-in is applicable for all entries under the containerDN which match the filter specified by the matchFilter parameter. This parameter can be repeated to specify multiple containerDNs. This parameter also restricts the VirtualAttribute plug-in to a certain branch within data exposed by the adapter. The default setting is "", or DSE—that is, if you do not set the ContainerDN parameter, the VirtualAttribute plug-in searches the entire directory tree.

MatchFilter

An optional parameter, MatchFilter identifies the entries the VirtualAttribute plug-in applies to. The VirtualAttribute plug-in is applicable for all entries under containerDN that match the filter specified by the MatchFilter parameter. If you do not set the MatchFilter parameter, the VirtualAttribute plug-in is applicable for all the entries under the DNs identified by ContainerDN parameter.

AddAttribute

A list of attributes to add to the entry and a value to assign to these virtual attributes. If an attribute identified by the AddAttribute parameter already exists in the entry, the VirtualAttribute plug-in appends the specified values to the existing set of values. The value can be a constant, another attribute, or a combination of attribute values and constants.

You can set the AddAttribute parameter multiple times for the VirtualAttribute plug-in. The value you set for the AddAttribute parameter must be mutually exclusive, that is, different, from the ReplaceAttribute.

For example:

  • To add the values of the cn attribute to uid and displayName, set the value of the AddAttribute parameter to: uid=displayName=%cn%

  • To add the constant value Acme to the companyName attribute, set the value for AddAttribute parameter to: companyName=Acme

  • To add a combination of cn, sn, and dc values to the member attribute, set the AddAttribute parameter value to: member={cn=%cn%, sn=%sn%, dc=oracle, dc=com}

    Note:

    The "curly braces" ({}) are important.
ReplaceAttribute

A list of attributes to add to the entry and a value to assign to these virtual attributes. If an attribute identified by the ReplaceAttribute parameter already exists in the entry, the VirtualAttribute plug-in replaces them using the value you supply. The value can be a constant, another attribute, or a combination of attribute values and constants.

You can set the ReplaceAttribute parameter multiple times for the VirtualAttribute plug-in. The value you set for the ReplaceAttribute parameter must be mutually exclusive, that is, different, from the AddAttribute.

For example:

  • To replace the values of uid and displayName with the values of the cn attribute, the ReplaceAttribute parameter can be configured as: uid=displayName=%cn%

  • To replace the value of the companyName attribute with the constant value Acme, the ReplaceAttribute parameter can be configured as: companyName=Acme

  • You can replace the member attribute value with a combination of cn, sn, and dc values by configuring the ReplaceAttribute parameter as: member={cn=%cn%, sn=%sn%, dc=oracle, dc=com}

    Note:

    The "curly braces" ({}) are important.
RemoveAttributes

Comma-separated list of attributes to virtually remove from entries that satisfy the MatchFilter under the specified ContainerDN.

4.2.7.2 Example VirtualAttribute Plug-In Deployment

This section provides an example VirtualAttribute plug-in deployment. Assume the following VirtualAttribute plug-in configuration parameters are set:

Configuration Parameter Value
AddAttribute uid=displayName=%cn%
AddAttribute certificate=Verisign
AddAttribute member={cn=%cn%, sn=%sn%, dc=oracle, dc=com}
ReplaceAttribute title=%designation%
RemoveAttributes designation,uid

Assume the original entry to be processed is:

dn: cn=john, dc=com
cn: john
cn: jsmith
uid: 1234
certificate: selfsigned
designation: SMTS
title: Senior Software Engineer
sn: smith
objectclass: person
objectclass: top

The following shows how the VirtualAttribute plug-in transforms the original entry:

After processing the AddAttributes configuration parameter, the entry is:

dn: cn=john, dc=com
cn: john
cn: jsmith
uid: 1234
uid: john
uid: jsmith
displayName: john
displayName: jsmith
certificate: verisign
certificate: selfsigned
designation: SMTS
title: Senior Software Engineer
sn: smith
objectclass: person
objectclass: top
member: cn=john, sn=smith, dc=oracle, dc=com
member: cn=jsmith, sn=smith, dc=oracle, dc=com

After processing the ReplaceAttributes configuration parameter, the entry is:

dn: cn=john, dc=com
cn: john
cn: jsmith
uid: 1234
uid: john
uid: jsmith
displayName: john
displayName: jsmith
certificate: verisign
certificate: selfsigned
designation: SMTS
title: Senior Software Engineer
sn: smith
objectclass: person
objectclass: top
member: cn=john, sn=smith, dc=oracle, dc=com
member: cn=jsmith, sn=smith, dc=oracle, dc=com

After processing the RemoveAttributes configuration parameter, the entry is:

dn: cn=john, dc=com
cn: john
cn: jsmith
displayName: john
displayName: jsmith
certificate: verisign
certificate: selfsigned
title: Senior Software Engineer
sn: smith
objectclass: person
objectclass: top
member: cn=john, sn=smith, dc=oracle, dc=com
member: cn=jsmith, sn=smith, dc=oracle, dc=com

4.2.8 Dump Transactions Plug-In

The Dump Transactions plug-in generates a record of all transactions for each LDAP operation and logs the record to the Oracle Virtual Directory console log. You can configure the Dump Transactions plug-in to run on any log level. The Dump Transactions plug-in is particularly useful for diagnosing mapping and integration efforts while logic flows through the Oracle Virtual Directory system. You can use the Dump Transaction plug-in to analyze issues on a specific adapter without setting the entire server log level to a more verbose level. Think of the Dump Transactions plug-in as a protocol analyzer for Oracle Virtual Directory.

4.2.8.1 Configuration Parameters

The Dump Transactions plug-in has the following configuration parameter:

loglevel

The log level at which the plug-in logs transactions. Supported values are: SEVERE, WARNING, INFO, FINE, FINER, and FINEST. There is no default value.

4.2.9 DynamicTree Plug-In

The DynamicTree plug-in enables you to construct DNs in Oracle Virtual Directory using the attribute values of source directory entries that have parent entries which are real, virtual, or pointers to different real entries.

Note:

The DynamicTree plug-in is supported only for deployment on adapters—do not deploy the DynamicTree plug-in as a global plug-in.

This plug-in is useful for generating organization charts and reports in LDAP hierarchy format based on structural data contained in the source directory entry. The Dynamic Tree plug-in provides more flexibility than the DynamicEntry Tree plug-in because it enables you to browse the directory tree.

Consider the following figures and examples.

Note:

In the following graphics, attribute values in the source directory appear in bold type.

Figure 4-2 shows an example directory structure residing in the source directory:

Figure 4-2 Example Directory Structure in Source Directory

example in source directory

Figure 4-3 shows an example of how the DynamicTree plug-in, with the parentEntryType parameter set to 1 and the attributeName parameter set to parentou, transforms the source directory's flat hierarchy shown in Figure 4-2 into a layered hierarchy in Oracle Virtual Directory.

Figure 4-3 Directory Structure in OVD Using DynamicTree Plug-In

OVD directory structure using DynamicTree plug-in

Figure 4-4 shows another example directory structure residing in the source directory:

Figure 4-4 Example Directory Structure in Source Directory

example source directroy structure

Figure 4-5 shows an example of how the DynamicTree plug-in, with the parentEntryType parameter set to 0 and the attributeName parameter set to l, creates a layered hierarchy in Oracle Virtual Directory based on the l attribute value in the source directory shown in Figure 4-4.

Figure 4-5 Directory Structure in OVD Using DynamicTree Plug-In

OVD directory structure using DynamicTree plug-in

4.2.9.1 Configuration Parameters

The DynamicTree plug-in has the following configuration parameter:

attributeName

The attribute used to identify the entry's parent entry.

parentEntryType

Identifies the type of parent entry. Supported values are 0 and 1. Select 0 for virtual parent entries, which are entries that Oracle Virtual Directory creates based on attribute values in the source directory. Select 1 for parent entries created by multiple ou containers.

4.2.10 DynamicEntryTree Plug-In

The DynamicEntryTree is a general purpose plug-in that you can use to generate virtual directory tree hierarchy by using attributes found in entry leaf nodes. For example, if an adapter has a root of o=Airius.com and users are present as uid=scarter,ou=people,o=airius.com, the DynamicEntryTree plug-in can insert new hierarchy using data present in the entry of the user, such as: uid=scarter,ou=accounting,ou=people,o=airius.com.

4.2.10.1 Configuration Parameters

The DynamicEntryTree plug-in has the following configuration parameter:

patterns

The DynamicEntryTree plug-in is configured by specifying matching patterns using the patterns configuration parameter. The syntax for the patterns parameter value is

attr[=entryattr[(SUPPRESS|value)]],...

For each DN component, an attribute name can have a value substituted with the attribute on the right side of the equals sign (=). If no substitution is required, then just the attribute is listed, which essentially refers to a matching component with the original DN. When a value is substituted, you can also further qualify what happens when entryattr has no value. You may either specify SUPPRESS to suppress the entry completely, or you may specify a default value within brackets after the entryattr name.

Multiple patterns can be defined by separating them with a |. For example:

uid,ou=department(contract),ou|cn,ou=code(SUPPRESS)

This rule has two patterns. One pattern matches objects under the adapter root (o=airius.com) that have dn components matching uid,ou. Therefore, uid=scarter,ou=people,o=airius.com would be selected for mapping. Upon return, the department attribute would be checked for values. If none are present, the static text contract is substituted. On a search, if base is set to uid=scarter,ou=accounting,ou=people,o=airius.com, the search is modified so that the new base is uid=scarter,ou=people,o=airius.com and the filter is modified with an additional anded term of ou=accounting.

The second pattern is intended to match child objects of o=airius.com that have a cn rdn component. When matched, if the entry has an attribute code, its value is substituted by creating cn=mygroup,ou=code12,o=airius.com. If the attribute code is not present, the entry result is suppressed due to the SUPPRESS keyword.

4.2.11 FlatTree Plug-In

The FlatTree plug-in, as with the DynamicEntryTree, performs dynamic mapping of the virtual directory tree. The FlatTree plug-in compresses a directory source so that all entries appear directly under the root of the adapter.

FlatTree plug-in operates in two deployed modes:

  • as part of any existing adapter to flatten the existing namespace

  • as part of a Custom Adapter deployment

As part of a Custom Adapter deployment, you can use the FlatTree plug-in's adapter parameter to retrieve data from the designated adapter so that the data appears as part of the namespace of the Custom Adapter. When deployed this way, the adapter root object is not defined. This type of deployment can be useful if you want to overlay multiple adapters on top of a parent adapter without creating duplicate parent nodes.

4.2.11.1 Configuration Parameters

The following is a list and description of the FlatTree plug-in configuration parameters:

criteria

Criteria defines an LDAP filter that restricts the entries that can be searched for through the FlatTree plug-in. For example, if criteria was set to objectclass=user, then only user objects would be returned through the FlatTree plug-in.

adapter

If the adapter parameter is not defined, the FlatTree plug-in assumes data will be retrieved through its parent adapter. When defined, the adapter parameter must be the name of another adapter in the Oracle Virtual Directory configuration and the FlatTree plug-in retrieves data from this adapter and maps the entries to its parent adapter's root. If the adapter parameter is defined the root object is not returned—only the child entries are returned.

4.2.12 DynamicGroups Plug-In

The DynamicGroups plug-in enables Oracle Virtual Directory to process LDAP objectclasses that are both groupofuniquenames and groupofurls (referred to as a "dynamic group") and convert it into a virtual static group, or groupofuniquenames equivalent. The plug-in works by monitoring returned LDAP objects and detects objects where the memberurl attribute is present and the objectclass is both groupofuniquenames and groupofurls.

When detected, the plug-in automatically processes any memberurl values and adds the results to the uniquemember attribute. This dynamic object processing allows administrators to define groups that hold both static members and dynamic members while maintaining compatibility with applications that may not normally support the groupofurls objectclass.

Example 4-1 shows an example query when the Dynamic Groups plug-in is not enabled. Two groups are returned and the first group holds two static members and has a memberurl defining a particular directory subtree to also be members.

Example 4-1 Example Query When Dynamic Groups Plug-in Is Not Enabled

C:\>ldapsearch -D bindDN -q -b ou=groups,ou=airius,o=yourcompany.com -s
sub "(memberurl=*)"

cn=test,ou=groups,ou=airius,o=yourcompany.com
cn=test
memberurl=ldap:///ou=accounting,o=yourcompany.com??sub?(&(objectclass=person)(obj
ectclass=organizationalperson))
objectclass=groupofuniquenames
objectclass=groupofurls
objectclass=top
uniquemember=cn=Paul Jacobs,ou=People,ou=Airius,o=yourcompany.com
uniquemember=cn=Wendy Verbaas,ou=People,ou=Airius,o=YourCompany.com

cn=TestCheck,ou=groups,ou=airius,o=yourcompany.com
memberurl=ldap:///ou=alt bind,o=yourcompany.com??sub?(&(userprincipalname=*))
objectclass=groupofuniquenames
objectclass=groupofurls
cn=TestCheck

Example 4-2 shows the results of the same query as in Example 4-1, however, the Dynamic Groups plug-in is enabled:

Example 4-2 Example Query When Dynamic Groups Plug-in is Enabled

C:\>ldapsearch -D bindDN -q -b ou=groups,ou=airius,o=yourcompany.com -s
sub "(cn=test)"

cn=test,ou=groups,ou=airius,o=yourcompany.com
memberurl=ldap:///ou=accounting,o=yourcompany.com??sub?(&(objectclass=person)(obj
ectclass=organizationalperson))
objectclass=groupofuniquenames
objectclass=groupofurls
objectclass=top
cn=test
uniquemember=cn=Paul Jacobs,ou=People,ou=Airius,o=yourcompany.com
uniquemember=cn=Wendy Verbaas,ou=People,ou=Airius,o=YourCompany.com
uniquemember=cn=Vipi Velasquez,ou=accounting,o=yourcompany.com
uniquemember=cn=Preston Pena-Fernandez,ou=accounting,o=yourcompany.com
uniquemember=cn=Andreas O'Hara,ou=accounting,o=yourcompany.com
uniquemember=cn=Chitra Guenette,ou=accounting,o=yourcompany.com
...
uniquemember=cn=Jim Ward,ou=accounting,o=yourcompany.com

The Dynamic Group plug-in expands the "memberURL" value (that is, it executes an LDAP search query with the base, scope, and filter specified in the memberURL and adds the returned DNs to the member attribute) if, and only if, the search filter specified in the client request does not return any entries from a remote back-end server.

To illustrate this point, assume the LDAP entry shown in Example 4-3 exists in a remote LDAP server configured with Oracle Virtual Directory.

Example 4-3 LDAP Entry on a Remote LDAP Server with Oracle Virtual Directory

dn:cn=admingroup,dc=groups,dc=acme,dc=com
uniqueMember:cn=mark,cn=users,dc=acme,dc=com
memberURL:ldap:///cn=users,dc=acme,dc=com??sub?(|(cn=john)(cn=smith))
objectClass:groupOfUniqueNames
objectClass:groupOfUrls

The following LDAP search returns the entry as is; without expanding the memberURL value.

Base DN: dc=groups,dc=acme,dc=com
Scope: sub
Filter: uniquemember=cn=mark,cn=users,dc=acme,dc=com

However, if you execute the following LDAP search, the Dynamic Group plug-in returns the LDAP entry shown in Example 4-4 with the "cn=john" value in uniqueMember.

Base DN: dc=groups,dc=acme,dc=com
Scope: sub
Filter: uniquemember=cn=john,cn=users,dc=acme,dc=com

Example 4-4 Returned LDAP Entry with a Value in uniqueMember

dn:cn=admingroup,dc=groups,dc=acme,dc=com
uniqueMember:cn=mark,cn=users,dc=acme,dc=com
uniqueMember:cn=john,cn=users,dc=acme,dc=com
memberURL:ldap:///cn=users,dc=acme,dc=com??sub?(|(cn=john)(cn=smith))
objectClass:groupOfUniqueNames
objectClass:groupOfUrls

To resolve the dynamic groups configured in a back-end remote server, you must perform the following steps:

  1. Configure the DynamicGroups plug-in.

  2. Add the "memberurl" attribute to the DN Attributes list in adapter configurations where you want to convert the memberurl from the remote base to the proxy root DN. Without this configuration, the dynamic groups cannot be converted for the adapter.

For example, to activate the DynamicGroups plug-in and resolve the dynamic groups when the base root DN of Oracle Virtual Directory adapter configuration is different from the remote base, perform the following steps:

  1. Configure a dynamic group in the remote server.

    cn=dyngroup,dc=ralf,dc=oracle,dc=com
    memberurl: ldap:///dc=ralf,dc=oracle,dc=com??sub?cn=a*
    uniquemember: cn=b1,ralf,dc=oracle,dc=com
    
  2. Populate a dynamic member entry.

    cn=a1,dc=ralf,dc=oracle,dc=com
    
  3. Configure an LDAP Adapter to be Root DN != Remote base.

    Root DN : dc=test,dc=ovd,dc=comRemote base : dc=ralf,dc=oracle,dc=com
    
  4. Add "memberurl" to the dnAttribute list in the adapter configuration.

    DN Attributes : uniquemember,manager,secretary,owner,memberurl
    
  5. Configure a DynamicGroups plug-in.

  6. Run a search operation with the proxy base.

    > ldapsearch -p 5566 -D cn=admin -w welcome1 -b
    "dc=test,dc=ovd,dc=com"
    -s sub "cn=dyn*"
    

    Your test result should be similar to the following example:

    cn=dyngroup,dc=test,dc=ovd,dc=com
    memberURL=ldap:///dc=dc=test,dc=ovd,dc=com??sub?cn=a*
    objectClass=groupofuniquenames
    objectClass=groupofurls
    objectClass=top
    cn=dyngroup
    uniquemember=cn=b1,dc=test,dc=ovd,dc=com
    uniquemember=cn=a1,dc=test,dc=ovd,dc=com
    

    Note that all of the base DN was converted from dc=ralf,dc=oracle,dc=com to dc=test,dc=ovd,dc=com.

The next example illustrates how to activate the DynamicGroups plug-in and resolve the dynamic groups when the base root DN of the Oracle Virtual Directory adapter configuration and the remote base is the same:

  1. Configure a dynamic group in the remote server.

    cn=dyngroup,dc=ralf,dc=oracle,dc=com
    memberurl: ldap:///dc=ralf,dc=oracle,dc=com??sub?cn=a*
    uniquemember: cn=b1,ralf,dc=oracle,dc=com
    
  2. Populate a dynamic member entry.

    cn=a1,dc=ralf,dc=oracle,dc=com
    
  3. Configure an LDAP Adapter to be Root DN = Remote base.

    Root DN : dc=ralf,dc=oracle,dc=comRemote base : dc=ralf,dc=oracle,dc=com
    
  4. Configure a dynamic groups plug-in.

  5. Run a search operation with the proxy base.

    > ldapsearch -p 5566 -D cn=admin -w welcome1
    -b "dc=ralf,dc=oracle,dc=com" -s sub "cn=dyn*"
    

The example's test result should be similar to the following:

cn=dyngroup,dc=ralf,dc=oracle,dc=com
memberURL=ldap:///dc=ralf,dc=oracle,dc=com??sub?cn=a*
objectClass=groupofuniquenames
objectClass=groupofurls
objectClass=top
cn=dyngroup
uniquemember=cn=b1,dc=ralf,dc=oracle,dc=com
uniquemember=cn=a1,dc=ralf,dc=oracle,dc=com

This final example illustrates how to convert only the base DN of the memberurl without resolving the dynamic groups:

  1. Configure a dynamic group in the remote server.

    cn=dyngroup,dc=test,dc=ovd,dc=com
    memberurl: ldap:///dc=ralf,dc=oracle,dc=com??sub?cn=a*
    uniquemember: cn=b1,dc=test,dc=ovd,dc=com
    
  2. Populate a dynamic member entry.

    cn=a1,dc=test,dc=ovd,dc=com
    
  3. Configure an LDAP Adapter with Root DN != Remote base.

    Base DN : dc=test,dc=ovd,dc=comRemote base : dc=ralf,dc=oracle,dc=com
    
  4. Run a search operation with the proxy base.

    > ldapsearch -p 5566 -D cn=admin -w welcome1 -b
    "dc=test,dc=ovd,dc=com"
    -s sub "cn=dyn*"
    

Your test result should be similar the following:

cn=dyngroup,dc=test,dc=ovd,dc=com
memberURL=ldap:///dc=test,dc=oracle,dc=com??sub?cn=a*
objectClass=groupofuniquenames
objectClass=groupofurls
objectClass=top
cn=dyngroup
uniquemember=cn=b1,dc=test,dc=ovd,dc=com

Note that Oracle Virtual Directory converted the base DN and retrieved only the static member.

4.2.12.1 Testing Group Membership

Products such as policy servers often must check whether a particular person is a member of a group, which can be a significant task if a group is very large or if the group is a dynamic group. However, the Dynamic Groups plug-in detects a membership test query by detecting the presence of both cn and uniquemember filter terms. When present, the Dynamic Groups plug-in processes the query differently by recognizing that the client wants to test a membership assertion. The plug-in modifies the results and returns only the single user being tested as the member, as shown in Example 4-5:

Example 4-5 Example Membership Test with the Dynamic Groups Plug-in

C:\>ldapsearch -D bindDN -q -b ou=groups,ou=airius,o=yourcompany.com -s
sub "(&(cn=TestCheck)(uniquemember=cn=Jim Ward,ou=accounting,o=yourcompany.com))"

cn=TestCheck,ou=groups,ou=airius,o=yourcompany.com
memberurl=ldap:///ou=accounting,o=yourcompany.com??sub?(&(userprincipalname=*))
objectclass=groupofuniquenames
objectclass=groupofurls
cn=TestCheck
uniquemember=cn=Jim Ward,ou=Accounting,o=YourCompany.com

4.2.12.2 Configuration Parameters

The following is a list and description of the Dynamic Groups plug-in configuration parameters. To enable the Dynamic Groups plug-in, add it to a plug-in chain.

memberattribute

Name of the attribute that stores member values. If no values are specified, uniqueMember is used by default.

accessInternal

Setting this parameter to true enables this plug-in to access adapters with visibility set to Internal to resolve the memberURL for the members configured with those internal adapters. Default is false.

usersearchbase

Optional value for a virtual search base that needs to override the base specified in an LDAP URL.

fetchBothStaticAndDynamicGps

Parameter used when a user is a member of both static and dynamic groups. Default value is false.

  • If set to false, fetches only static groups to which a particular searched user belongs, and it does not fetch the dynamic group.

  • If set to true, fetches both static and dynamic groups for the searched user.

checkurlbase

Boolean indicating whether to honor the base and scope specified in memberURL while performing membership test queries. Default value is false.

globalsearch

Boolean describing whether the search for expanding dynamic groups should happen from the Global Plugin Chain (Global Service Interface) layer or the Adapter Plugin Chain (Adapter Service Interface) layer of Oracle Virtual Directory.

4.2.13 Cache Plug-In

The Cache plug-in provides a true cache for Oracle Virtual Directory—it is an in-memory copy of a LDAP search result set and is designed to improve the performance of repeated queries. For example, imagine a 3rd party portal server as part of a daily synchronization process that queries for all of the groups in the enterprise LDAP server (that is, Oracle Virtual Directory) three consecutive times. The cache plug-in can keep a copy of the result of the first search for reuse by LDAP clients. While it did result in a slightly faster result to the client application—more importantly it reduced the load of the enterprise source systems.

Oracle Virtual Directory is designed to function without the Cache plug-in and often it is not necessary because many applications either cache results on their own, or because most enterprise source systems already cache data. Also, because Oracle Virtual Directory is often used in secure environments, keeping a cache exposes security elements, such as if an employee is terminated and their user result is still in the cache.

Note:

If you use the Cache plug-in, the cache timeout should be kept small to avoid cache update problems in cases such as these.

The Cache plug-in can greatly improve performance for applications where queries are highly repetitive and can be configured to run any where within Oracle Virtual Directory. The Cache plug-in can be executed globally or within the context of a single adapter, and can also be restricted to specific namespaces using namespace filtering.

If a query is repeated by the same user and the same attributes or a subset of attributes are requested, the cache returns its results instead of Oracle Virtual Directory retrieving the information from the source. For example, consider the following two theoretical queries where the client changes the search attributes in Query 2:

Query 1

  • Bind as: "cn=Example User,cn=users,dc=mycompany,dc=com"

  • Base of: "dc=mycompany,dc=com"

  • Query of: "uid=jdoe"

  • Attributes: "cn,mail"

Query 2

  • Bind as: "cn=Example User,cn=users,dc=mycompany,dc=com"

  • Base of: "dc=mycompany,dc=com"

  • Query of: "uid=jdoe"

  • Attributes: "telephonenumber,manager"

By using the Cache plug-in, Oracle Virtual Directory does not treat Query 1 and Query 2 as two separate queries and does not search the back-end source twice. Oracle Virtual Directory requests all the attributes for matching entries in Query 1, but only returns the attributes requested by the client and keeps an in-memory copy of the search results in its cache.

Note:

Oracle Virtual Directory retrieves only the attributes which the bound user has access to based on the back-end source repository Access Control Lists (ACLs), Oracle Virtual Directory ACLs, and adapter routing rules.

The Cache plug-in can also be configured to allow cache hits to be shared between users. Sharing cache entries between users should not be used unless passcredentials is not being passed to back-end sources and Oracle Virtual Directory is solely responsible for security enforcement.

Note:

Careful planning should take place when sharing cache hits between users as it may then be possible for one user to see something they should not, since they may have access to a cache result from a more privileged user.

The Cache plug-in periodically reviews the cache and checks for any expired results or entries that have been invalidated by a previous modify transaction. If the cache quota is exceeded, the Cache plug-in attempts to trim memory by purging the queries that were least recently used.

4.2.13.1 Configuration Parameters

The following is a list and description of the Cache plug-in configuration parameters:

storeallattrs

Controls whether the Cache plug-in silently requests all attributes. Supported values are 0 (disable) or 1 (enable). By default, the storeallattrs parameter is disabled (0).

bysubject

Indicates whether cache results are shared between subjects. Supported values are 0 or 1. A value of 0 indicates results are shared between subjects and a value of 1 indicates that results are not shared between subjects. The default value is 1.

maintenanceinterval

The amount of time (in seconds) between when the cache manager checks for expired queries. The default value is 60.

size

The maximum number of entries that may be cached at any one time. The default value is 10000.

maximumage

The maximum age (or time), in seconds, that any query/entry can be stored in the cache. The default value is 600.

maxresultsize

The maximum number of entries that may be cached for any particular query. The default setting is 1000.

trimsize

When the maximum cache size is exceeded, this parameter indicates the amount by which the cache manager must reduce the balance. The default value is 10000.

Note:

When necessary, trimming is done by purging expired queries first followed by queries in order of least recent use.
zeroresults

Indicates whether to cache query results containing zero entries. Supported values are 0 and 1.

4.2.14 ObjectClass Mapper Plug-In

The ObjectClass Mapper plug-in is a general mapping plug-in that can make one objectClass, such as user, appear like another objectClass, such as inetOrgPerson. This ability is useful when an application is expecting a particular objectClass and attributes but the directory does not support that objectClass or attributes.

The ObjectClass Mapper plug-in can perform several different types of manipulation based on configuration parameters you select, including:

  • attribute mapping

  • objectclass mapping

  • adding attributes conditional on objectclass

  • removing attributes

  • filtering auxiliary classes

  • handling activation and deactivation

Where attribute mapping relationships occur, the prefix client- indicates client side and source- indicates data source side. For example, mapping Active Directory server user to represent it as InetOrgPerson would imply that Active Directory is the source side and InetOrgPerson is the client side.

4.2.14.1 Configuration Parameters

The following is a list and description of the ObjectClass Mapper plug-in configuration parameters:

directoryType

The directory type to use when performing user activation. Supported values are SunOne, eDirectory, ADAM, and ActiveDirectory. For example:

Parameter Name: directoryType

Parameter Value: ActiveDirectory

activationAttribute

Use the activationAttribute parameter when an application has no knowledge of the underlying directory's user activation system. The activationAttribute parameter informs Oracle Virtual Directory which incoming attribute contains the user activation flag, which is then mapped to a directory specific attribute and flag. For example:

Parameter Name: activationAttribute

Parameter Value: myuseraccountcontrol

deactivationValue

Comma separated list of attribute values specified in activationAttribute that indicate this user should be marked as inactive.

activationValue

Comma separated list of attribute values specified in activationAttribute that indicate this user should be marked as active.

mapObjectClass

An objectClass to be mapped in the form of client-ObjectClass=source-ObejctClass. For example:

Parameter Name: mapObjectClass

Parameter Value: inetOrgPerson=user

You can use the mapObjectClass parameter multiple times for multiple mappings.

addAttribute[-objectclassvalue]

Adds attributes for a user during the add process. An optional objectclass value may be added to the configuration name to add the attribute only for certain objectclasses. For example, to add a userAccountControl attribute to only the user objectclass, use:

Parameter Name: addAttribute-user

Parameter Value: userAccountControl=546

Note:

An attribute value may be referenced on the value side of the expression by supplying the attribute name surrounded by the percentage character (%). For example:

Parameter Name: addAttribute-group

Parameter Value: samaccountname=%cn%

filterAttribute[-objectclassvalue]

Comma-separated list of attributes that are removed during the add operation and from all returned entries. A conditional objectclass value may be added to the name of the parameter to filter out attributes for a specific objectclass. For example:

Parameter Name: filterAttribute

Parameter Value: objectsid,memberof,samaccountname

mapAttribute

An attribute to be mapped in the form of client-Attribute=source-attribute. For example:

Parameter Name: mapAttribute

Parameter Value: uniqueMember=member

You can use the mapAttribute parameter multiple times for multiple mappings.

filterAuxiliaryClass

Comma separated list of objectclasses that must be removed on an add operation. An example is Microsoft Active Directory for Windows 2000 does not allow auxiliary object classes to be listed while adding an entry, while Microsoft Active Directory and ADAM for Windows Server 2003 does allow for auxiliary classes to be listed. For example:

Parameter Name: filterAuxiliaryClass

Parameter Value: person,myorgPerson

filterObjectClassOnModify

Comma-separated list of attributes that are removed during the modify operation for a specific objectclass. For example:

Parameter Name: filterObjectClassOnModify

Parameter Value: objectsid,memberof,samaccountname

4.2.15 Sub-Tree Plug-In

The Sub-Tree plug-in was originally developed to support early versions of IBM's Tivoli Access Manager product, which had a requirement where it stored policy information about a person's entry under the person's entry, thereby changing the person entry from its typical leaf model to be a branch. Some directories did not support such a model or did not want to populate their enterprise directory this way.

The Sub-Tree plug-in enables you to store these sub-tree entries in a different adapter while presenting the expected directory tree view to the application—in this case Tivoli Access Manager. The requirement to add entries under a normal leaf entry is uncommon. The more common case is to make a data-store appear as a branch under an existing data-store and any adapter can perform this by properly setting its root namespace value.

4.2.15.1 Configuration Parameters

The following is a list and description of the Sub-Tree plug-in configuration parameters:

storeadapter

The adapter to store the user subtree objects in.

storeroot

The location in the store adapter where you want to store the user subtree objects.

subtreematch

Identifies the subtree distinguished name (DN) component that the Sub-Tree plug-in should intercept and redirect to the store adapter. The default value is secAuthority=Default.

matchdn

Numbered parameters that specify distinguished names (DN) under which user objects are found and the user object RDN. For example: 0=ou=People,o=Airius.com\:uid

4.2.16 Performance Monitor Plug-In

The Performance Monitor plug-in enables you to monitor the performance of a specific adapter. To use the Performance Monitor plug-in, attach it to an adapter and then perform operations against that adapter. To view the adapter performance, you must perform a specific type of base level LDAP search on the adapter's root namespace with a filter of vdeSearchtime=*.

The search returns results similar to Example 4-6, where all time measurements are in milliseconds:

Example 4-6 Example of Data Returned with the Performance Monitor Plug-In

dn: dc=demo,dc=com
vdeNumSearches: 4
vdeNumEntries: 5
vdeMinSearchTime: 0
vdeMaxSearchTime: 16
vdeTotalSearchTime: 16
vdeAverageSearchTime: 4
vdeMinEntryTime: 0
vdeMaxEntryTime: 0
vdeTotalEntryTime: 0
vdeAverageEntryTime: 0
vdeMinSearchCompleteTime: 0
vdeMaxSearchCompleteTime: 203
vdeTotalSearchCompletionTime: 219
vdeAverageSearchCompletionTime: 54

Note:

The Performance Monitor data is reset after the Oracle Virtual Directory server restarts.

4.2.16.1 Configuration Parameters

The Performance Monitor plug-in has no configuration parameters. To enable the Performance Monitor plug-in, add it to a plug-in chain.

4.2.17 UniqueEntry Plug-In

In some Oracle Virtual Directory environments users have duplicate accounts for multiple services they connect to using Oracle Virtual Directory adapters. Typically, building a Join View Adapter to unify multiple adapters and create a single virtual user entry would resolve this problem. However, there are circumstances where building a Join View Adapter is not an option. For example, there might be a directory for staff personnel and a directory for customers, but certain staff members have accounts in both directories for legitimate business purposes and you cannot create a Join View Adapter.

The UniqueEntry plug-in solves this problem by enabling you to rank various adapters by their authoritative source. For example, if you are attempting to determine which of the duplicate user identities is a staff account, then the staff directory is more relevant than the customer directory and you would place a higher priority on the staff directory adapter than the customer directory adapter.

When ranking adapter priorities, the lower the value of the numerical ranking is, the higher priority. For example, if you are searching two adapters and one adapter has a priority ranking of five and the other adapter has a priority ranking of ten, the adapter with the priority ranking of five is searched first, before the adapter with the priority ranking of ten.

Note:

Do not apply the UniqueEntry plug-in at the adapter level—it should always be applied only as a Global plug-in.

4.2.17.1 Configuration Parameters

The UniqueEntry plug-in has the following configuration parameter:

uniqueattribute

The attribute to use as the unique key.

4.2.18 Adapter Plug-In Version

Do not deploy the Adapter Plug-in Version plug-in—it is for information only and has no server functionality. It provides the adapter version information that appears on the Oracle Directory Services Manager home page.

4.2.19 Proxy Authorization Support Plug-In

In many deployments, customers store the user credentials in an enterprise password credential directory such as Microsoft Active Directory but they also aggregate content from other data sources such as Oracle Directory Server Enterprise Edition, Oracle Internet Directory, and so forth. In these deployments, customers want the ability to apply a consistent security and audit trail that maps to the authenticated user, which is called identity propagation. The Proxy Authorization Support plug-in leverages the proxy authentication capability of enterprise directories so that even though the user is actually authenticated in Active Directory, the user identity can be propagated to one or more other sources so that security/audit in these additional sources are mapped to the actual user authenticated to Oracle Virtual Directory and not to an application account stored in Oracle Virtual Directory.

The Proxy Authorization Support plug-in constructs the client DN, adds a proxy authorization control with this client DN to the request, then passes the request to the back-end LDAP server. The LDAP server authenticates the request using the Oracle Virtual Directory Proxy DN, and processes the operation using the client user identity specified in the proxy authorization control without requiring any changes to the client application.

When you configure the Proxy Authorization Support plug-in, you must configure the directory to support the proxy control you are going to pass.

4.2.19.1 Configuration Parameters

The following is a list and description of the Proxy Authorization Support plug-in configuration parameters:

remoteBase

An optional parameter used as parent DN to construct the user authorization DN to pass in Proxy Authorization Control. Defaults to the same value as the adapter's remoteBase.

directoryType

An optional parameter used to indicate the directory types. Allowable values are OID and SunOne. SunOne is the default value, and only this value is supported in this release.

4.2.20 UserManagement Plug-In

The UserManagement plug-in provides data mapping for Oracle Identity Manager attributes to LDAP directory servers.

4.2.20.1 Configuration Parameters

The UserManagement plug-in has the following configuration parameters:

filterObjectclass

Comma-separated list of objectclasses that need to be removed on an add/modify request.

removeAttribute

Comma-separated list of attributes that will be virtually removed from entries before they are returned to the client.

exclusionMapping

Defines the exclusion of a specific attribute mapping on a specific objectclass. For example, specifying a parameter with the value inetorgperson,uid=samaccountname excludes mapping a uid to samaccountname on entries of objectclass inetorgperson. Using multiple instances of this option allows for multiple exclusions on mappings.

oimLanguages

Comma-separated list of language codes to be used in attribute language subtypes. This parameter is functional only when the directoryType parameter is set to ActiveDirectory.

oamEnabled

True or False: Indicates whether Oracle Access Manager is deployed with Oracle Identity Manager. By default, Oracle Access Manager is not deployed, therefore the default setting for this parameter is false.

Note:

The oamEnabled parameter for the UserManagement plug-in and the changelog plug-in must have identical values.
directoryType

Identifies the type of source LDAP directory server. Supported values are OID, ActiveDirectory, and SunOne. The default value is OID.

Note:

The directoryType parameter for the UserManagement plug-in and the changelog plug-in must have identical values.
ssladapter

The ssladapter parameter, which is operational only when the directoryType parameter is set to ActiveDirectory, identifies the name of the adapter to which the UserManagement plug-in routes requests when userPassword or unicodePwd is contained in requests. If unicodePwd is contained in the request, the request must also contain the useraccountControl attribute with a proper value.

The adapter identified by the ssladapter parameter must have:

  • The same local base as the adapter the UserManagement plug-in is configured on

  • Its Routing Visibility set to Internal

If no value is set for ssladapter, the current adapter is used by default.

mapAttribute

Defines the attribute translation in the form of OVD-attribute=OIM-attribute, for example: orclGUID=objectGuid. You can set the mapAttribute configuration parameter multiple times to define translations for multiple attributes.

mapPassword

True or False. When the directoryType configuration parameter is set to ActiveDirectory, the mapPassword parameter controls whether to convert the user password to the unicodePwd attribute. The default value is false.

mapRDNAttribute

Defines the RDN attribute translation in the form of OVD-RDNattribute=OIM-RDNattribute, for example: uid=cn.

pwdMaxFailure

Identifies the maximum number of failed logins the source LDAP directory server requires to lock an account (as defined by the password policy effective on the user entries being exposed through the adapter on which this plug-in is deployed).

mapObjectclass

Defines the objectclass value translation in the form of OVD-objectclass=OIM-objectclass, for example: inetorgperson=user. You can set the mapObjectclass configuration parameter multiple times to define translations for multiple objectclasses.

Note:

The mapObjectclass parameter for the UserManagement plug-in and the changelog plug-in must have identical values.
addAttribute

In the form of attribute=value pairs, this parameter identifies attributes to be added before returning the get operation result. You can prefix the attribute name with objectclass, to add the attribute and value to a specific objectclass. You can also surround a value with % to reference other attributes. For example, specifying the value user,samaccountname=%cn% assigns the value of cn to samaccountname when the entry objectclass=user. Specifying the value samaccountname=jdoe adds attribute samaccountname with value jdoe to all the entries.

4.2.21 Changelog Plug-Ins

Note:

Prior to release 11.1.1.4.0, Oracle Virtual Directory had three changelog plug-ins:
  • oidchangelog for use with Oracle Internet Directory

  • sunonechangelog for use with Oracle Directory Server Enterprise Edition

  • adchangelog for use with Microsoft Active Directory

These three plug-ins are deprecated in release 11.1.1.4.0 and a new, single Changelog plug-in is now available. You can use this plug-in with Oracle Internet Directory, Oracle Directory Server Enterprise Edition, and Microsoft Active Directory.

4.2.21.1 Deploying the Release 11.1.1.4.0 Changelog Plug-In

When deploying the single Changelog plug-in, you must:

  • Set the adapter's Remote Base to an empty value; that is blank, nothing.

  • Set the adapter's Mapped Namespace to: cn=changelog.

  • If the back-end is Oracle Directory Server Enterprise Edition, be sure to enable change logging on Oracle Directory Server Enterprise Edition.

4.2.21.2 Deploying Changelog Plug-Ins from Prior Releases

If you are using a version of Oracle Virtual Directory that was released prior to 11.1.1.4.0, you must use the following changelog plug-ins to standardize changelog information from source directories into a suitable format for Oracle Identity Manager.

Note:

These plug-ins will not work with Oracle Virtual Directory release 11.1.1.4.0.

For Oracle Internet Directory

Use the oidchangelog plug-in with Oracle Internet Directory.

When deploying the oidchangelog plug-in, you must set the adapter's Remote Base to an empty value; that is, blank, nothing.

For Oracle Directory Server Enterprise Edition

Use the sunonechangelog plug-in with Oracle Directory Server Enterprise Edition.

When deploying the sunonechangelog plug-in, you must:

  • Set the adapter's Remote Base to an empty value; that is, blank, nothing.

  • Ensure change logging is enabled on the Oracle Directory Server Enterprise Edition.

  • Set the adapter's Mapped Namespace to: cn=changelog

For Microsoft Active Directory

Use the adchangelog plug-in with Microsoft Active Directory.

When deploying the adchangelog plug-in, you must:

  • Set the adapter's Remote Base to an empty value; that is, blank, nothing.

  • Set the adapter's Mapped Namespace to: cn=changelog

4.2.21.3 Configuration Parameters

Each of the changelog plug-ins have the following configuration parameters:

removeAttribute

Comma-separated list of attributes that are virtually removed from entries before they are returned to the client.

oimLanguages

Comma-separated list of languages to be used in attribute language subtypes.

skipErrorChangelog

True or False. If set to false and the plug-in encounters a corrupted changelog entry, the plug-in throws a DirectoryException and stops further processing changelog entries. If set to true, the plug-in logs an error without throwing an exception, skips this changelog, and continues processing the next changelogs. The default value is false.

oamEnabled

True or False: Indicates whether Oracle Access Manager is deployed with Oracle Identity Manager. By default, Oracle Access Manager is not deployed, therefore the default setting for this parameter is false.

Note:

The oamEnabled parameter for the UserManagement plug-in and the changelog plug-in must have identical values.
directoryType

Identifies the type of source LDAP directory server. Supported values are OID, ActiveDirectory, and SunOne. The default value is OID.

Note:

The directoryType parameter for the UserManagement plug-in and the changelog plug-in must have identical values.
mapObjectclass

Defines the objectclass value translation in the form of OIM-objectclass=Source-Directory-objectclass, for example: inetorgperson=user. You can set the mapObjectclass configuration parameter multiple times to define translations for multiple objectclasses.

In the Oracle Identity Manager use case, the following parameters are configured out-of-the-box:

  • For Active Directory: inetorgperson=user, orclidxperson=user, and groupOfUniqueNames=group

  • For Oracle Directory Server Enterprise Edition: container=nsContainer and changelog=changelogentry

  • For Oracle Internet Directory: container=orclContainer

Note:

The mapObjectclass parameter for the UserManagement plug-in and the changelog plug-in must have identical values.
sizeLimit

Identifies the maximum number of changelog entries to be returned.

A zero (0) or a negative value means no size restriction.

If the incoming search request specifies a size constraint, then the smaller value is used. For example, if you specify the plug-in's sizeLimit as 100, and the search request's count limit is 200, then the actual size limit of the request is reset to 100.

mapAttribute

Defines the attribute translation in the form of Source-Directory-attribute=OIM-attribute, for example: orclGUID=objectGuid. You can set the mapAttribute configuration parameter multiple times to define translations for multiple attributes.

targetDNFilter

Identifies the container to retrieve changes from. This parameter can be set multiple times to identify multiple containers to retrieve changes from. If set multiple times, the targetDN filter should look similar to the following example, and this targetDN filter is "ANDed" to the incoming filter:

"(|(targetDN=*cn=users,dc=mycom1)(targetDN=*,cn=groups,dc=mycom2))"

Sample values include:

  • *,cn=xxx,dc=yyy

  • *cn=xxx,dc=yyy

  • cn=xxx,dc=yyy (must be a descendant of the local base of the adapter specified in virtualDITAdapterName)

All of these samples have the same meaning.

requiredAttribute

Comma-separated list of attributes to always be retrieved from the source LDAP directory server, regardless of the return attributes list specified for changelog queries to Oracle Virtual Directory.

addAttribute

Comma-separated list of attributes to be added to the normalized changelog entry. For example, orclContainerOC=1, changelogSupported=1, where =1 indicates the changes retrieved from the source directory which support changelog.

mapUserState

True or False. This parameter enables or disables the mapping of the directory specific account attributes to Oracle Virtual Directory virtual account attributes.

modifierDNFilter

Single-valued configuration parameter that defines an LDAP filter on modifiersName. This parameter is "ANDed" to the incoming filter. An example value can be "(modifiersName=cn=myadmin,cn=users,dc=mycom)".

Note:

This configuration does not take effect if directoryType=ActiveDirectory.
virtualDITAdapterName

Identifies the corresponding user profile adapter name.

For example, in a single-directory deployment, you can set this parameter value to "A1," which is the user adapter name. In a split-user profile scenario, you can set this parameter to "J1;A2," where "J1" is the JoinView adapter name, and "A2" is the corresponding user adapter in the "J1".

This parameter can be multi-valued, which means there are multiple base entry adapters configured for the same back-end directory server as this changelog adapter.

If you set this parameter to "A1," the plug-in fetches the mapAttribute and mapObjectclass configuration in the UserManagementPlugin of adapter A1, so you do not have to duplicate those configurations.

4.2.22 Consolidated Changelog Plug-In

The Consolidated Changelog plug-in provides a consolidated changenumber when Oracle Virtual Directory is providing a consolidated view of the identities from multiple directories. This plug-in also provides a consolidated, normalized view of the data from the different changelogs. You can only deploy this plug-in as a Global plug-in.

The Consolidated Changelog plug-in is based on the concept of providing a unified cookie for the consolidated changelog. This cookie is constructed based on the adapters involved in providing a consolidated view of the directories for which adapters are configured in Oracle Virtual Directory.

The consolidated changenumber is a cookie of the form:

<changelogAdapterName1>:<changenumber1>;<changelogAdapterName2><changenumber2>;<targetDN:dn>

Where:

  • <changelogAdapterName1> is the source adapter from which the changelog is coming.

  • <changenumber1> is the changeNumber of this entry in changelogAdapter1.

  • <changelogAdapterName2> is a second changelog adapter configured in this Oracle Virtual Directory.

  • <changenumber2> is the changeNumber last read from changelogAdapter2.

  • <targetDN:dn> is the targetDN of this changelog entry as in the back-end directory. This value is optional, and used for diagnostic purposes only.

For example, assume you have two directories for which the changelog is to be consolidated, and that the changelog adapters are CA1 and CA2. Also, assume that the changenumber from the Directory server where CA1 is pointing starts with 101 and the Directory server where CA2 is pointing starts with 501. Then the cookie value for change 101 for CA1 is:

CA1:101;CA2:501;<targetDN:targetDN_of_CA1_101>

Similarly, the cookie value for CA2 is:

CA2:501;CA1:101;<targetDN:targetDN_of_CA2_501>

The length of this cookie value is 2048 bytes.

As with a regular directory, the Consolidated Changelog plug-in supports the "lastChangeNumber" query, as follows:

ldapsearch -h <ovdHost> -p <ovdPort> -D <ovdAdmin> -w <ovdAdminPwd> -b "cn=changelog" -s base "objectclass=*" lastChangeNumber

Example 4-7shows a sample returned entry.

Example 4-7 Sample Entry Returned by lastChangeNumber Query

cn=Changelog
lastChangeNumber=Changelog_ActiveDirectory:165095;Changelog_OID:408;Changelog_SunOne:298328

Note:

This plug-in is designed to only be used with Oracle Identity Manager version 11g.

With this plug-in deployed, supported query filters must be in a form that combines exactly one filter (changenumber>=cookie) with one or more of the following filters:

  • (targetdn=*domain) where the domain is a valid domain dn.
    For example, (targetdn=*cn=.yyy, dc=zzz)

  • (modifiersname=xxx) where xxx is a dn.

  • !(modifiersname=yyy) where yyy is a dn.

  • (changetype=xxx) where xxx can be ADD/MODIFY/DELETE/ADDRMODIFY

  • !(changetype=yyy) where yyy can be ADD/MODIFY/DELETE/ADDRMODIFY

4.2.22.1 Configuration Parameters

The Consolidated Changelog plug-in has no configuration parameters. To enable the Consolidated Changelog plug-in, you must install and deploy it as a global plug-in.

4.2.23 GenericMapper Plug-In

The GenericMapper plug-in provides functionality that is equivalent to the following Oracle Virtual Directory plug-ins, but with more flexible functionality:

  • VirtualAttribute plug-in

  • ObjectClass Mapper plug-in

  • DynamicTree plug-in

This plug-in is based on the Directory Integration Platform's mapping rules file format described in the Oracle® Fusion Middleware Administrator's Guide for Oracle Directory Integration Platform.

The GenericMapper plug-in handles mapping based on the entry's objectclass. All attributes from the user are copied, as is, to the back-end directory and vice versa. This plug-in uses the following keywords in addition to the keywords provided in the Directory Integration Platform documentation:

ATTRIBUTEEXCLUSIONLIST

List of attributes that are to be excluded from the result to the end user. This is applicable for UserBound operations (search/read)

VIRTUALATTRIBUTELIST

List of attributes that are not to be included when the operations are done on the back end. This is applicable for UserBound operations (search/read)

FILTERRULES

The filtered entries on which the mapping rules are to be applied.

4.2.23.1 Configuration Parameters

The following tables describe the configuration parameters you use to configure the GenericMapper plug-in to achieve the VirtualAttribute, ObjectClass Mapper, and DynamicTree plug-ins' functionality.

To Achieve VirtualAttribute Plug-In Functionality:

Use the parameters described in the following table.

Parameter Name Description
Container DN DomainRules. Specify all containers given in the Container DN as domain rules.
MatchFilter FilterRules. Specify the matchfilter value after the filterRules.
AddAttribute Specify the attribute mapping rule as follows:
<attribute to be added >:[required]: [attribute type – string/binary]:
<objectclass to which the attribute belongs to>: 
<backend attr name>:[attribute type]:<objectclass> : 
<rule defining the value to be added>

For example, to return "cn" for "my commonname," use the following rule:

Mycommonname: : : myObjectClass: cn: :inetorgperson: cn

Specify the following rule to return "SALES" for "department":

Department: : :organizationalperson:cn: :person: "SALES"
ReplaceAttribute Specify the attribute mapping rule as follows:
<clientview of attribute >:[required]: [attribute type – string/binary]:<objectclass to which the attribute belongs to>: 
<backend attr name>:[attribute type]:<objectclass> : 

For example, to return "cn" for "displayname," use the following rule:

displayname: : : inetorgperson: cn: :inetorgperson:  

When the GenericMapper plug-in interprets the rule, it replaces the displayname value with cn.

RemoveAttributes AttributeExclusionList (Specify the list of all attributes to be excluded).

To Achieve ObjectClass Mapper Plug-In Functionality:

Use the parameters described in the following table.

Parameter Name Description
Container DN DomainRules. Specify all containers given in the Container DN as domain rules.
MatchFilter FilterRules. Specify the matchfilter value after the filterRules.
AddAttribute Specify the attribute mapping rule as follows:
<attribute to be added >:[required]: [attribute type – string/binary]:
<objectclass to which the attribute belongs to>: 
<backend attr name>:[attribute type]:<objectclass> : 
<rule defining the value to be added>

For example, to return "cn" for "my commonname," use the following rule:

Mycommonname: : : myObjectClass: cn: :inetorgperson: cn

Specify the following rule to return "SALES" for "department":

Department: : :organizationalperson:cn: :person: "SALES"
ReplaceAttribute Specify the attribute mapping rule as follows:
<clientview of attribute >:[required]: [attribute type – string/binary]:
<objectclass to which the attribute belongs to>: 
<backend attr name>:[attribute type]:<objectclass> : 

For example, to return "cn" for "displayname," use the following rule:

displayname: : : inetorgperson: cn: :inetorgperson:  

When the GenericMapper plug-in interprets this rule, it replaces the displayname value with cn.

RemoveAttributes AttributeExclusionList (Specify the list of all attributes to be excluded).
ObjectClassMapping/Filtering auxiliary classes Objectclass mapping is handled by the way the objectclass is specified in the Src attribute definition and the destination attribute definition. The objectclass values are also added, depending on which attributes are mapped.
Handling activation and deactivation This information is provided in the sample map files.

To Achieve DynamicTree Plug-In Functionality:

To configure the GenericMapper plug-in to achieve the same results as the DynamicTree plug-in, you must configure the following:

<domain name as seen by client> : <domain name as seen in the backend> : cn=%, l=%,ou=%, <domain name as seen by the client>

All of the entries are considered to be parts of different DITs, based on their attributes.

Note:

The GenericMapper plug-in has one limitation. In searches where you specify the attribute in the construct rule as the base, the GenericMapper plug-in only returns subtree entries, it does not return the base entry.

4.3 Understanding the Enterprise User Security and Oracle Net Services Plug-Ins

Oracle Virtual Directory includes plug-ins to simplify the integration with Enterprise User Security (EUS) and Oracle Net Services. This topic describes the plug-ins related to these integrations and contains the following sections:

4.3.1 EUSActiveDirectory Plug-In

Use the EUSActiveDirectory plug-in only when integrating Oracle Virtual Directory with Oracle's Enterprise User Security database product and your user identities are stored in Microsoft Active Directory. The EUSActiveDirectory plug-in translates Active Directory attributes to a format that can be used by the Enterprise User Security database.

4.3.1.1 Configuration Parameters

The EUSActiveDirectory plug-in has no configuration parameters. To enable the EUSiPlanet plug-in, add it to a plug-in chain.

4.3.2 EUSiPlanet Plug-In

Use the EUSiPlanet plug-in only when integrating Oracle Virtual Directory with Oracle's Enterprise User Security database product and your user identities are stored in Oracle Directory Server Enterprise Edition (formerly Sun Java System Directory Server). The EUSiPlanet plug-in translates Oracle Directory Server Enterprise Edition attributes to a format that can be used by the Enterprise User Security database.

4.3.2.1 Configuration Parameters

The EUSiPlanet plug-in has no configuration parameters. To enable the EUSiPlanet plug-in, add it to a plug-in chain.

4.3.3 EUSOID Plug-In

Use the EUSOID plug-in only when integrating Oracle Virtual Directory with Oracle's Enterprise User Security database product and your user identities are stored in Oracle Internet Directory. The EUSOID plug-in translates Oracle Internet Directory attributes to a format that can be used by the Enterprise User Security database.

4.3.3.1 Configuration Parameters

The EUSOID plug-in has no configuration parameters. To enable the EUSOID plug-in, add it to a plug-in chain.

4.3.4 EUSeDirectory Plug-In

Use the EUSeDirectory plug-in only when integrating Oracle Virtual Directory with Oracle's Enterprise User Security database product and your user identities are stored in Novell eDirectory. The EUSeDirectory plug-in translates Novell eDirectory attributes to a format that can be used by the Enterprise User Security database.

4.3.4.1 Configuration Parameters

The EUSeDirectory plug-in has no configuration parameters. To enable the EUSeDirectory plug-in, add it to a plug-in chain.

4.3.5 EUSMemberDNMapping Plug-In

Use the EUSMemberDNMapping plug-in only when integrating Oracle Virtual Directory with Oracle's Enterprise User Security database product. The EUSMemberDNMapping plug-in translates the distinguished name (DN) namespace for the Enterprise User Security database administrators group stored in an external repository to the same payload that Oracle Virtual Directory sends to the database.

4.3.5.1 Configuration Parameters

The following is a list and description of the EUSMemberDNMapping plug-in configuration parameters:

remoteDomainDN

The base DN in the remote external repository (Active Directory, Oracle Internet Directory, Oracle Directory Server Enterprise Edition) where the Enterprise User Security database administrators group is located.

localDomainDN

The base DN of the name of the group that Oracle Virtual Directory exposes.

Note:

Typically, the values for the remoteDomainDN and localDomainDn configuration parameters are identical.

4.3.6 EUSLockout Plug-In

Use the EUSLockout plug-in only when integrating Oracle Virtual Directory with Oracle's Enterprise User Security database product. LDAP servers have the ability to lock a user account after several bind attempts fail. The EUSLockout plug-in allows the Oracle Virtual Directory-Enterprise User Security integration to use this lockout feature and enforce the back-end LDAP server's password lockout policy as follows:

  • An incorrect login to the Oracle Database records a login failure to the back-end LDAP server

  • A correct login to the Oracle Database resets the login failure count in the back-end LDAP server

    Note:

    This functionality is not available for integrations that use Active Directory.
  • A locked user account cannot be used to log in to the Oracle Database.

When you configure the EUSLockout plug-in, you must:

  • Create a directoryType parameter with a value according to your back-end LDAP server, such as ActiveDirectory for Active Directory, iPlanet for Oracle Directory Server Enterprise Edition, or eDirectory for Novell eDirectory.

  • Create a namespace using the name of your Oracle Virtual Directory-Enterprise User Security integration user container.

4.3.6.1 Configuration Parameters

The following is a list and description of the EUSLockout plug-in configuration parameters:

directoryType

The type of back-end directory server in the Oracle Virtual Directory-Enterprise User Security integration where the user identities are stored. Supported values are ActiveDirectory for Active Directory, iPlanet for Oracle Directory Server Enterprise Edition, or eDirectory for Novell eDirectory.

4.3.7 ONames Plug-In

The Onames plug-in is used only when integrating Oracle Virtual Directory with Oracle Net Services. The plug-in removes entries that are specific to the source LDAP directory to facilitate the Oracle Virtual Directory-Oracle Net Services integration.

4.3.7.1 Configuration Parameters

The ONames plug-in has no configuration parameters. To enable the ONames plug-in, add it to a plug-in chain.

4.3.8 SubschemaSubentry Plug-In

When Oracle database queries Oracle Virtual Directory in Enterprise User Security and Oracle Net Services integrations it expects LDAP schema to be in the same name as Oracle Internet Directory. However, Oracle Internet Directory and Oracle Virtual Directory store the LDAP schema differently. The SubschemaSubentry plug-in transparently redirects the Oracle database queries to allow Oracle Virtual Directory-Enterprise User Security or Oracle Virtual Directory-Oracle Net Services integrations to function.

4.3.8.1 Configuration Parameters

The SubschemaSubentry plug-in has no configuration parameters. To enable the SubschemaSubentry plug-in, add it to a plug-in chain.

4.4 Understanding the Microsoft Active Directory Plug-Ins

Microsoft Active Directory has several features that many applications do not know how to handle. Oracle Virtual Directory includes multiple plug-ins to allow applications to use these unique features without affecting, recoding, or reconfiguring the application.

This topic describes the Microsoft Active Directory and Active Directory Application Mode (ADAM) plug-ins included in Oracle Virtual Directory and contains the following sections:

4.4.1 ActiveDirectory Password Plug-In

Active Directory and ADAM have special rules about how the password of a user may be updated by using LDAP, including:

  • Passwords may only be updated through a secure SSL connection

  • If a user is updating their own password, the original password must be included in a modify delete with the new password being a modify add in the same modify operation.

  • Only an administrator may reset the password of a user without knowing the previous password.

  • Active Directory does not use the userPassword attribute—it uses the unicodePwd attribute, which is in Unicode format.

The ActiveDirectory Password plug-in helps administrators with the Active Directory's password update rules when an application is not designed to use them and it is not advantageous to connect to Active Directory or ADAM through SSL for all operations. By configuring the ActiveDirectory Password plug-in on a non-SSL enabled adapter and pointing the plug-in to an SSL-enabled adapter, this plug-in allows a password update on Active Directory to work as a password update on an inetOrgPerson directory would.

Important:

The ActiveDirectory plug-in must be configured only on an LDAP Adapter, typically against Microsoft Active Directory.

4.4.1.1 Configuration Parameters

The ActiveDirectory Password plug-in has the following configuration parameter:

adapter

The name of the adapter to which the ActiveDirectory Password plug-in reroutes requests if they contain a userPassword attribute. The adapter identified must have its virtual root be the same as the current adapter and its Routing Visibility setting must be set as Internal. If the adapter parameter is not defined, the current adapter is used.

mapPassword

Indicates whether the password must be converted to the unicodePwd attribute (true), or not (false). Supported values are true or false. The default value is true.

4.4.2 Active Directory Ranged Attributes Plug-In

Attributes in Active Directory and ADAM with more then 1000 values are returned 1000 at a time with a name that includes the range of values that were returned (or 1500 for Windows 2003). The range is returned to the client in the following format:

member;1-1000: somevalue

To get the next thousand entries, the client application must know to repeat the query and request the attribute member;1001-2000. This requires applications to handle Active Directory in a unique method when compared to other directory products.

The Active Directory Ranged Attributes plug-in detects attributes that Active Directory or ADAM has "ranged" and automatically retrieves all values. If the Active Directory Ranged Attributes plug-in is not enabled, the LDAP Adapter's dn-attribute configuration option is not applied because the range of values are appended to the attribute name.

Important:

The Active Directory Ranged Attributes plug-in determines what attributes on an adapter are marked as dn-attributes and performs the appropriate base mapping. You can only use the Active Directory Ranged Attributes plug-in as an adapter plug-in on an LDAP Adapter.

4.4.2.1 Configuration Parameters

The Active Directory Ranged Attributes plug-in has no configuration parameters. To enable the Active Directory Ranged Attributes plug-in, add it to a plug-in chain.

4.4.3 InetAD Plug-In

The InetAD plug-in combines the functionality of the ObjectClass Mapper Plug-In, Active Directory Ranged Attributes Plug-In, and ActiveDirectory Password Plug-In to allow one single plug-in to be configured to handle multiple unique Active Directory features.

The InetAD plug-in utilizes the ObjectClass Mapping plug-in because most LDAP directories use the inetOrgPerson and groupOfUniqueNames object classes for users and groups, while Active Directory uses the user and group objectClasses with attributes specific to Active Directory's NOS requirements.

The InetAD plug-in allows Oracle Virtual Directory to make an Active Directory or ADAM directory server appear to have inetOrgPerson schema. Based on the parameter configuration, the InetAD plug-in can rename attributes and object classes and add attributes for a user in Active Directory to have all needed attributes. If no configuration parameters are used, the InetAd plug-in makes an Active Directory user or group appear to be an inetOrgPerson or groupOfUniqueNames object class.

Note:

Where attribute mapping relationships occur, the client- prefix indicates client side and the source- prefix indicates data source side. For example, mapping Active Directory server user to represent it as InetOrgPerson would imply Active Directory is the source side and InetOrgPerson is the client side.

4.4.3.1 Configuration Parameters

The following is a list and description of the InetAD plug-in configuration parameters:

directoryType

The directory type to use when performing user activation. Supported values are SunOne, eDirectory, ADAM, and ActiveDirectory. For example:

Parameter Name: directoryType

Parameter Value: ActiveDirectory

activationAttribute

Use the activationAttribute parameter when an application has no knowledge of the underlying directory's user activation system. The activationAttribute parameter informs Oracle Virtual Directory which incoming attribute contains the user activation flag, which is then mapped to a directory specific attribute and flag. For example:

Parameter Name: activationAttribute

Parameter Value: myuseraccountcontrol

deactivationValue

Comma separated list of attribute values specified in activationAttribute that indicate this user should be marked as inactive.

activationValue

Comma separated list of attribute values specified in activationAttribute that indicate this user should be marked as active.

mapObjectClass

An objectClass to be mapped in the form of client-ObjectClass = AD-ObejctClass. For example:

Parameter Name: mapObjectClass

Parameter Value: inetOrgPerson=user

You can use the mapObjectClass parameter multiple times for multiple mappings. The default values are groupOfUniqueNames=group, inetOrgPerson=user.

addAttribute[-objectclassvalue]

Adds attributes for a user during the add process. An optional objectclass value may be added to the configuration name to add the attribute only for certain objectclasses. For example, to add a userAccountControl attribute to only the user objectclass, use:

Parameter Name: addAttribute-user

Parameter Value: userAccountControl=546

Note:

An additional attribute value may be substituted as an expression by supplying its name surrounded by the percentage character (%). The default configuration is:
addAttribute-user: useraccountcontrol=544,
addAttribute-group:samaccountname=%cn%,
addAttribute-group: grouptype=-2147483646
filterAttribute[-objectclassvalue]

Comma-separated list of attributes to be removed during the add operation and from all returned entries. A conditional objectclass value may be added to the name of the parameter to filter out attributes for a specific objectclass. For example:

Parameter Name: filterAttribute

Parameter Value: objectsid,memberof,samaccountname

mapAttribute

An attribute to be mapped in the form of client-Attribute=AD-attribute. For example:

Parameter Name: mapAttribute

Parameter Value: uniqueMember=member

You can use the mapAttribute parameter multiple times for multiple mappings. The default values are "uniqueMember=member", "uid=samaccountname", "ntgrouptype=grouptype".

filterAuxiliaryClass

Comma separated list of objectclasses that must be removed on an add operation. Active Directory for Windows 2000 does not allow auxiliary object classes to be listed while adding an entry, while Microsoft Active Directory and ADAM for Windows Server 2003 does allow for auxiliary classes to be listed. The default value is person, organizationalPerson.

filterObjectClassOnModify

Comma-separated list of attributes to be removed during the modify operation for a specific objectclass. For example:

Parameter Name: filterObjectClassOnModify

Parameter Value: objectsid,memberof,samaccountname

mapPassword

Indicates whether the password must be converted to the unicodePwd attribute (true), or false if not (ADAM). Supported values are true or false. The default value is true.

sslAdapter

The name of the adapter to which this plug-in reroutes requests if they contain userPassword. The current adapter is used if the sslAdapter parameter is not set. The adapter identified by the sslAdapter parameter must have:

  • The same local base as the adapter the InetAD plug-in is configured on

  • Its Routing Visibility set to Internal

4.5 Understanding the Oracle Access Manager Plug-Ins

Oracle Virtual Directory includes plug-ins to simplify the integration with Oracle Access Manager. This topic describes the plug-ins related to this integration and contains the following sections:

4.5.1 OAMPolicyControl Plug-In

For Oracle Virtual Directory-Oracle Access Manager integrations only, the OAMPolicyControl plug-in is for applications that use LDAP for authentication and want to use Oracle Access Manager policy controls, but cannot integrate with Oracle Access Manager.

Before deploying the OAMPolicyControl plug-in, you must:

  • Set the Bind pass-through settings to Never for any LDAP Adapters that are using the Oracle Access Manager policy configuration.

    The plug-in handles all authentications and uses proxy credentials to perform all operations.

  • Configure different adapters for Oracle Access Manager.

    These adapters should use the OAMPolicyControl plug-in to use Oracle Access Manager policies. If you deploy these adapters on the same Oracle Virtual Directory server, you must configure one of the following options:

    • Use a different LDAP namespace for each adapter. An Oracle Access Manager adapter namespace must be independent from the namespaces used by general purpose LDAP clients.

    • Use an Oracle Virtual Directory view, with accessibility criteria that distinguishes requests for different Oracle Access Manager adapters.

  • Configure the Oracle Access Manager Access Server by:

    • Creating a proxy resource that corresponds to Oracle Virtual Directory.

    • Disabling the policy domains for Identity Server and Access Server because the plug-in does not cache the OBSSO Cookie.

  • Configure the AccessSDK as follows:

    • Configure an AccessSDK installation for the Oracle Access Manager Access Server by using AccessServerSDK\oblix\tools\configureAccessGate.

    • Configure the opmn to start the Oracle Virtual Directory component by pointing the -Djava.library.path to the AccessSDK installation.

      Edit the INSTANCE_HOME/config/OPMN/opmn/opmn.xml file as follows:

      <ias-component id="ovd1">
       <process-type id="OVD" module-id="OVD">
        <module-data>
         <category id="start-options">
          <data id="java-bin" value="$ORACLE_HOME/jdk/bin/java"/>
          <data id="java-options" value="-server -Xms512m -Xmx512m
           -Dvde.soTimeoutBackend=0
           -Doracle.security.jps.config=$ORACLE_
      INSTANCE/config/JPS/jps-config-jse.xml
           -Djava.library.path=AccessSDK_install_
      dir/AccessSDK/AccessServerSDK/oblix/lib/"/>
           <data id="java-classpath" value="$ORACLE_
      HOME/ovd/jlib/vde.jar$:$ORACLE_HOME/jdbc/lib/ojdbc6.jar"/>
          </category>
         </module-data>
        <stop timeout="120"/>
       </process-type>
      </ias-component>
       
      
    • Copy the jobaccess.jar file from AccessSDK_install_dir/AccessServerSDK/oblix/lib to ORACLE_HOME/ovd/plugins/lib.

Note:

Failure to successfully complete the preceding prerequisite configurations will cause the Oracle Virtual Director to generate a NoClassDefFound error.

4.5.1.1 Configuration Parameters

The OAMPolicyControl plug-in has the following configuration parameters:

Note:

All of the following configuration parameters—except for useAccessAuthPolicy—are required to deploy the OAMPolicyControl plug-in.
resourceIdOVD

Identifies the proxy resource for Oracle Virtual Directory that the Oracle Access Manager server configures. For example: //host:port/ovd_proxy_resource.

identityproxyid

Used for authentication against the Identity Server, the identityproxyid parameter identifies the value of the administrator's usernameAttribute.

install_dir

Identifies the AccessSDK installation directory containing the required libraries. For example: AccessSDK_INSTALL_DIRECTORY/AccessServerSDK/.

OrclOVDEncryptedproxypasswd

Administrator password for authentication against Identity Server.

identityEndpointAddress

Identifies the URL corresponding to the listening endpoint of the Identity Server's um_modifyUser web service. For example: http://host:port/identity/oblix/apps/userservcenter/bin/userservcenter.cgi

usernameAttribute

Identifies the attribute configured to be the Login attribute of the Identity Server. For example, uid or genUserId.

useAccessAuthPolicy

An optional and case-insensitive parameter, useAccessAuthPolicy determines usage of the Oracle Access Manager server's authorization policies while accessing the proxy resource. Supported values are True and False. The default setting is False.