Skip Headers
Oracle® Virtual Directory Product Manual
Release 10g (10.1.4.2.0)
E10286-01
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

B Bundled Plug-ins

This appendix provides information on the plug-ins included in the Oracle Virtual Directory and contains the following sections:

Introduction

Oracle Virtual Directory includes several plug-ins. These plug-ins extend the capabilities of Oracle Virtual Directory to perform special functions or mappings.


Note:

Oracle Virtual Directory may include other plug-ins not documented in this manual. Contact Oracle support for more information.

For plug-ins not distributed by Oracle, contact the plug-in author or distributor for more information.


General Purpose Plug-ins

This section documents the following general purpose plug-ins:

Caching

The CachePlug-in provides an in-memory cache for Oracle Virtual Directory. It has the ability to cache query results from any source for re-use by LDAP clients. This plug-in has the ability to greatly improve performance for those applications where queries are highly repetitive.

To review cache operation and configuration, set VE logging levels up to 7 or 9 to see more details.

Because the cache is a normal plug-in, the cache can be configured to run any where within Oracle Virtual Directory. It can be executed globally, or within the context of a single adapter. It can also be restricted to specific namespaces by using the namespace filtering available in standard plug-in configuration.

Cache Hit Logic

The cache works by storing query results and making them available for later use. 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 of having Oracle Virtual Directory pull the information from the source.

The plug-in can also be configured to allow cache hits to be shared between users.


Important:

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. Careful planning should take place when sharing cache hits between users as it would 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.

Memory Management

The plug-in will periodically review the cache and check for any expired results, or entries that have been invalidated by a previous modify transaction. In the event that the cache quota is exceeded, the plug-in will attempt to trim memory by purging the queries that were least recently used (LRU).

Configuration Parameters

These include:

  • size

    The maximum number of entries that may be cached at any one time. (Default: 10000).

  • maxresultsize

    The maximum number of entries that may be cached for any particular query. (Default: 1000).

  • trimsize

    When the maximum cache size is exceeded, the amount by which the cache manager must reduce the balance. Note: when necessary, trimming is done by purging expired queries first followed by queries in order of least recent use. (Default: 10000).

  • maximumage

    The maximum age in seconds for any query/entry stored in the cache. (Default: 600).

  • maintenanceinterval

    The interval in seconds between when the cache manager will check for expired queries. (Default: 60).

  • zeroresults

    A flag (1 or 0) indicating whether or not to cache query results containing no entries. (Default: 0).

  • bysubject

    A flat (1 or 0) indicating whether cache results are not shared between subjects. A value of 1 indicates that results will not be shared between subjects. (Default: 1).

DynamicGroups

The DynamicGroups Plug-in enables Oracle Virtual Directory to process LDAP objectclasses that are both groupofuniquenames and groupofurls (which we will refer 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 & 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.

C:\>ldapsearch -D cn=admin -w manager -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

In the previous example, two groups are returned. The first group holds two static members and has a memberurl defining a particular directory subtree to also be members. Notice that the above query was run with the plug-in turned off.

The following query shows the results when the plug-in is enabled:

C:\>ldapsearch -D cn=admin -w manager -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 Membership Assertations

Very often, products such as policy servers need to check whether a particular person is a member of a group. This can be a high cost task if a group is very large and/or it is a dynamic group. Calculating and returning 10k or even millions of members can be very expensive.

Instead, the DynamicGroups plug-in detects a membership test query by detecting the presence of both cn and uniquemember filter terms. When present, it processes the query a little differently. The plug-in realizes that the client really only wants to test a membership assertion. The plug-in modifies the results and returns only the single user being tested as the member:

C:\>ldapsearch -D cn=admin -w manager -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

This plug-in has no configuration parameters. It is turned on simply by adding to a plug-in chain.

DumpTransactions

This plug-in will generate a record of all transactions for each LDAP operation and output it to the Oracle Virtual Directory console log. This plug-in may be configured to run on any log level. This plug-in is particularly useful for diagnosing mapping and integration efforts as logic flows through the Oracle Virtual Directory system. Think of the DumpTransactions as a protocol analyzer for Virtual Directory.

Configuration Parameters

This includes:

  • loglevel

    The log level the plug-in will log transactions at. (Default: Debug).

ObjectClass Mapper

The ObjectClass Mapper is a general mapping plug-in that makes one objectClass (such as inetOrgPerson) look like another objectClass (such as user). This is useful when an application is expecting a particular objectClass and attributes while the directory does not support that objectClass or attributes.

The ObjectClass Mapper plug-in performs several types of manipulations (based on configuration parameters):

  • Attribute mapping

  • Objectclass mapping

  • Adding attributes conditional on objectclass

  • Removing attributes

  • Filtering auxiliary classes

  • Handling activation & deactivation

Configuration Parameters

Note that where attribute mapping relationships occur, the prefix client- means client side, and source- means 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.

  • mapAttribute

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

    Property: mapAttribute

    Value: uniqueMember=member

    Multiple instances of this configuration allow for multiple mappings.

  • mapObjectClass

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

    Property: mapObjectclass

    Value: inetOrgPerson=user

    Multiple instances of this option may be used for multiple mappings.

  • addAttribute[-objectclassvalue]

    Add attributes for a user during the add process. An optional object class value may be added to the configuration name to only add the attribute for certain object classes. For example, to add a userAccountControl attribute, use:

    Property: addAttribute-user

    Value: userAccountControl=546


    Note:

    An attribute value may be referenced on the value side of the expression by supplying the attribute name with % around it.

  • filterAttribute[-objectclassvalue]

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

    Property: filterAttribute

    Value: objectsid,memberof,samaccountname

  • filterAuxiliaryClass

    Comma separated list of object classes that need to be removed on an add operation. Example: 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:

    Property: filterAuxiliaryClass

    Value: person,myorgPerson

  • activationAttribute

    Used when an application has no knowledge of the underlying directory's user activation system. This configuration tells Oracle Virtual Directory which incoming attribute contains the user activation flag. This flag is then mapped to a directory specific attribute and flag. For example:

    Property: activationAttribute

    Value: myuseraccountcontrol

  • activationValue

    The values of the activationAttribute that indicates this user should be marked as active.

  • deactivationValue

    The values of the activationAttribute that indicates this user should be marked as inactive.

  • directoryType

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

    Property: directoryType

    Value: ActiveDirectory

Dynamic Entry Tree

The Dynamic Entry Tree 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, this plug-in can insert new hierarchy using data present in the entry of the user. For example, uid=scarter,ou=accounting,ou=people,o=airius.com.

Configuration Parameters

This includes:

  • patterns

    This plug-in is configured by specifying matching patterns using the initialization parameter patterns.

    Syntax:

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

    This means that 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. This 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 matches objects under the adapter root (o=airius.com) who have dn components matching uid,ou. So, uid=scarter,ou=people,o=airius.com would be selected for mapping. When being returned, 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 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.

Flat Tree

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

This plug-in operates in two deployed modes. It can be deployed as part of any existing adapter to flatten the existing namespace. Or, it can be deployed as part of a Custom Adapter deployment. By using the adapter parameter, the adapter will fetch data from the designated adapter representing it as part of the custom namespace of the adapter.

Note that when configured this way, the adapter root object is NOT defined. This is useful, if you want to overlay multiple adapters on top of a parent adapter without creating duplicate parent nodes.

Configuration Parameters

These include:

  • criteria

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

  • adapter

    If not defined, then the plug-in will assume data will be retrieved through its parent adapter. When defined, adapter must be the name of another adapter in the Oracle Virtual Directory configuration. When defined, the plug-in will pull data from the other adapter and map the entries to its parent adapter's root. When running in this mode, the root object is not returned; only the child entries are returned.

Microsoft Active Directory and Microsoft ADAM

Active Directory has several features that many applications do not know how to handle. Oracle Virtual Directory bundles several plug-ins to allow applications to take full advantage of these features without affecting, recoding, otherwise reconfiguring the application it self. These plug-ins deal primarily with the following issues:

The following plug-ins each contribute a component to allowing an application to handle these Microsoft Active Directory features. The first two plug-ins: Active Directory Ranged Attributes and Active Directory Password; allow for particular functions to be used individually, while the InetAD plug-in combines the ObjectClass Mapper plug-in with both Active Directory Ranged Attributes and Active Directory Password to allow a single plug-in to be configured to handle all of the above features in a simpler configuration.

Active Directory Ranged Attributes

This plug-in detects attributes that Microsoft Active Directory or ADAM have "ranged" and automatically retrieves all values. Because the range of values are appended to the attribute name, the LDAP dn-attribute option configuration of the adapter is not applied.


Tip:

This plug-in determines what attributes on an adapter are marked as dn-attributes and performs the appropriate base mapping. For this reason, this plug-in can ONLY be configured as an adapter plug-in on an LDAP adapter.

Configuration Parameters

This plug-in has no configuration parameters. It is turned on simply by adding to a plug-in chain.

Active Directory Password

This plug-in helps administrators with the above password update rules when the application at hand is not built to use them and it is not advantageous to connect to Microsoft Active Directory or ADAM via SSL for all operations. By configuring this 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.


Tip:

This plug-in must be configured on an LDAP Proxy Adapter (typically against Microsoft Active Directory).

Configuration Parameters

These include:

  • adapter

    The name of the adapter this plug-in will reroute requests to if they contain a userPassword attribute. The named adapter must have its virtual root be the same as the current adapter and its Routing Visibility must be marked as Internal. If no value is set then the current adapter is used.

  • mapPassword

    Takes the value true or false. true if the password needs to be converted to the unicodePwd attribute, false if not (ADAM). (Default : true).

InetAD

The InetAD plug-in allows for Oracle Virtual Directory to make a Microsoft Active Directory or ADAM directory server appear to have inetOrgPerson schema. Based on configuration it can rename attributes and object classes and add needed attributes in order for a user in Active Directory to have all needed attributes. This all-in-one plug-in includes the capabilities of the Active Directory Password and Active Directory Ranged Attributes plug-ins. With no configuration parameters this plug-in will make a Microsoft Active Directory user or group appear to be an inetOrgPerson or groupOfUniqueNames object class.


Note:

Where attribute mapping relationships occur, the prefix client- means client side, and source- means 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

These include:

  • mapAttribute

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

    Property: mapAttribute

    Value: uniqueMember=member

    Multiple instances of this configuration property can be defined to allow for multiple mappings. (Default Values: uniqueMember=member, uid=samaccountname, ntgrouptype=grouptype).

  • mapObjectClass

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

    Property: mapObjectClass

    Value: inetOrgPerson=user

    Multiple instances of this option may be used for multiple mappings. (Default Values: groupOfUniqueNames=group, inetOrgPerson=user).

  • addAttribute[-objectclassvalue]

    Add attributes for a user during the add process. An optional object class value may be added to the configuration name to only add the attribute for certain object classes. For example, to add a userAccountControl, use:

    Property: addAttribute-user

    Value: userAccountControl=546

    Another attribute value may be substituted as an expression by supplying its name with % around it. Default Configuration:

    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. An object class value may additionally added to the name of the parameter to filter out attributes by object class.

  • filterAuxiliaryClass

    Comma-separated list of object classes that need to be removed on an add operation. Microsoft Active Directory for Windows 2000 does not allow auxiliary object classes to be listed while adding an entry. However, Active Directory and ADAM for Windows Server 2003 do allow for auxiliary classes to be listed. (Default: person, organizationalPerson).

  • sslAdapter

    The name of the adapter this plug-in will reroute requests to if they contain userPassword. If not set, then the current adapter is used. The adapter named in this option MUST have the same local base as the adapter this plug-in is configured on and have its Routing Visibility set to Internal.

  • mapPassword

    Takes the value true or false - true if the password needs to be mapped to unicodePwd, false if not (ADAM). (Default: true).

  • activationAttribute

    Used when an application has no knowledge of the underlying user activation system of the directory. This configuration tells Oracle Virtual Directory which incoming attribute contains the user activation flag. This flag is then mapped to a directory specific attribute and flag.

  • activationValue

    The values of the activationAttribute that indicates this user should be marked as active.

  • deactivationValue

    The values of the activationAttribute that indicates this user should be marked as inactive.

  • directoryType

    The directory to use when performing user activation. Allowable directory type values are SunOne, eDirectory, ADAM, and ActiveDirectory.