4 Understanding Oracle Virtual Directory Plug-Ins

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

• What is a Plug-In?

• Understanding the General Purpose Plug-Ins

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

• Understanding the Microsoft Active Directory Plug-Ins

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:

• "Stringing-together" plug-ins to create combined and reusable functionality.

• Deploying plug-ins at the "global" server level so the plug-in affects all requests and responses.

• Deploying plug-ins at the adapter level so the plug-ins manipulate requests and responses for a particular adapter.

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

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 will 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.

Namespace Filtering

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

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:

• Dump Transactions Plug-In

• DynamicEntryTree Plug-In

• FlatTree Plug-In

• Dynamic Groups Plug-In

• Cache Plug-In

• ObjectClass Mapper Plug-In

• Sub-Tree Plug-In

• Performance Monitor Plug-In

• UniqueEntry Plug-In

• Adapter Plug-In Version

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.

Configuration Parameters

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

loglevel

The log level the plug-in will log transactions at. The default value is Debug. If the log level for the Oracle Virtual Directory server is set to Debug, you do not have to set a loglevel for the Dump Transactions plug-in, as it defaults to Debug. If the log level for the Oracle Virtual Directory server is not Debug, you must set the Dump Transactions loglevel to the same level as the Oracle Virtual Directory server.

DynamicEntryTree Plug-In

The DynamicEntryTree is a general purpose plug-in that can be used 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.

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 will be modified so that the new base is uid=scarter,ou=people,o=airius.com and the filter will be 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 will be suppressed due to the SUPPRESS keyword.

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.

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.

Dynamic Groups Plug-In

The Dynamic Groups 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 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

Testing Group Membership

Products such as policy servers often need to 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-3:

Example 4-3 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

Configuration Parameters

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

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 re-use 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 in many cases 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 will return its results instead 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.

Configuration Parameters

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

storeallattrs

Controls whether or not 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 or not cache results are shared between subjects. Supported values are 0 or 1. A value of 0 indicates results will be shared between subjects and a value of 1 indicates that results will not be 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 or not to cache query results containing zero entries. Supported values are 0 and 1.

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.

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 will 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=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 will be removed during the modify operation for a specific objectclass. For example:

Parameter Name: filterObjectClassOnModify

Parameter Value: objectsid,memberof,samaccountname

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 allows 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.

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

Performance Monitor Plug-In

The Performance Monitor plug-in allows 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 will return results similar to Example 4-4, where all time measurements are in milliseconds:

Example 4-4 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.

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.

UniqueEntry Plug-In

In some Oracle Virtual Directory environments users have duplicate accounts for more than one service 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.

Configuration Parameters

The UniqueEntry plug-in has the following configuration parameter:

uniqueattribute

The attribute to use as the unique key.

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.

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:

• EUSActiveDirectory Plug-In

• EUSiPlanet Plug-In

• EUSOID Plug-In

• EUSeDirectory Plug-In

• EUSMemberDNMapping Plug-In

• euslockout Plug-In

• ONames Plug-In

• subschemasubentry Plug-In

See Also:

• Integrating with Oracle's Enterprise User Security

• Integrating with Oracle's Net Services

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.

Configuration Parameters

The EUSActiveDirectory plug-in has the following configuration parameter:

ADLockoutDuration

The amount of time (in minutes) before the user account for Enterprise User Security authentication expires.

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 Sun Java System Directory Server. The EUSiPlanet plug-in translates Sun Java System Directory Server attributes to a format that can be used by the Enterprise User Security database.

Configuration Parameters

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

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.

Configuration Parameters

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

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.

Configuration Parameters

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

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.

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, Sun Java System Directory Server) 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.

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 utilize 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.

See Also:

Enabling User Account Lockout

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 Sun Java System Directory Server, or eDirectory for Novell eDirectory.

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

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 Sun Java System Directory Server, or eDirectory for Novell eDirectory.

ONames Plug-In

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

Configuration Parameters

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

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 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.

Configuration Parameters

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

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:

• ActiveDirectory Password Plug-In

• Active Directory Ranged Attributes Plug-In

• InetAD Plug-In

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 via 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 unciodePwd 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 via 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.

Configuration Parameters

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

adapter

The name of the adapter the ActiveDirectory Password plug-in will reroute requests to 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.

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.

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.

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.

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 that will 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 that will 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 this plug-in will reroute requests to if they contain userPassword. The current adapter is used if this parameter is not set. The adapter named in this option must have:

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

• Its Routing Visibility set to Internal