This appendix provides information on the plug-ins included in the Oracle Virtual Directory and contains the following sections:
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. |
This section documents the following general purpose plug-ins:
Caching
Dynamic Groups
Transaction Logger/Dumper
Objectclass Mapper
Dynamic Entry Tree
Flat Tree
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.
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 unlesspasscredentials 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
).
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.
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
).
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
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.
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.
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:
Ranging Attributes
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 form:
member;1-1000: somevalue
In order to get the next thousand entries, the client application must somehow know to repeat the query and request the attribute member;1001-2000. This requires applications to handle Microsoft Active Directory in a special way compared to other directory products.
Password Updates
Microsoft Active Directory and ADAM have special rules around how the password of a user may be updated by using LDAP:
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 Directroy does not use the userPassword
attribute, it uses the unciodePwd
attribute (which is in Unicode format).
ObjectClass Mapping
Most LDAP directories use the inetOrgPerson
and groupOfUniqueNames
object classes for users and groups. Microsoft Active Directory uses the user and group objectClasses with attributes specific to Active Directory NOS requirements of Microsoft.
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.
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.
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
).
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 prefixclient- means client side, and source- means data source side.
For example, mapping Active Directory server |
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
.