Developing Plug-ins for the Oracle Internet Directory Server

46 Developing Plug-ins for the Oracle Internet Directory Server

The following topics describe how to create a plug-in, register a plug-in using LDAP command-line utilities, and manage plug-ins using Oracle Directory Services Manager (ODSM) and Oracle Enterprise Manager Fusion Middleware Control:

46.1 Overview of Oracle Internet Directory Server Plug-in Framework

A server plug-in is a customized program that can be used to extend the capabilities of the Oracle Internet Directory server.

A server plug-in can be a PL/SQL package, Java program or package, shared object or library, or a dynamic link library on Windows. Each plug-in has a configuration entry in the Oracle Internet Directory Server. The configuration entry specifies the conditions for invoking the plug-in. The conditions for invoking a plug-in include:

An LDAP operation, such as ldapbind or ldapmodify
A timing, relative to the LDAP operation, such as pre_bind or post_modify

Directory server plug-ins can provide the directory server with the following kinds of added functionality, to mention just a few:

Validate data before the directory server performs an operation on it
Perform specified actions after the server performs an operation
Define password policies
Authenticate users through external credential stores

On startup, the directory server loads your plug-in configuration and library. Then, when it processes requests, it calls your plug-in functions whenever the specified event takes place.

In Figure 46-1, LDAP clients, each using a separate application, send information to and receive it from the Oracle directory server. Plug-in configuration tools likewise send information to the directory server. The directory server sends data to Plug-in Module 1, Plug-in Module 2, and Plug-in Module 3. Each plug-in module has both a plug-in module interface and plug-in logic. Each plug-in module sends information to and receives it from the LDAP API and the Plug-in LDAP.

Figure 46-1 Oracle Internet Directory Plug-in Framework

This illustration is described in the text.

The work that plug-ins perform depends on whether they execute before, after, or in addition to normal directory server operations.

This section contains the following topics:

46.1.1 Supported Languages for Server Plug-ins

As of 10g (10.1.4.0.1), Oracle Internet Directory supports plug-ins in Java and in PL/SQL.

This chapter provides information common to Java and PL/SQL plug-ins. PL/SQL Server Plug-in Developer's Reference provides additional information specific to PL/SQL plug-ins and Java Server Plug-in Developer's Reference provides additional information specific to Java plug-ins.

46.1.2 Prerequisites to Develop Server Plug-ins

To develop Oracle Internet Directory plug-ins, you should be familiar with the following topics:

Generic LDAP concepts
Oracle Internet Directory
Oracle Internet Directory integration with Oracle Application Server

You should have programming skills in one of the following areas:

SQL, PL/SQL, and database RPCs
Java

46.1.3 Benefits of Using Server Plug-ins

Some of the ways you can extend LDAP operations by using plug-ins include the following:

You can validate data before the server performs an LDAP operation on the data.
You can perform actions that you define after the server successfully completes an LDAP operation.
You can define extended operations.
You can authenticate users through external credential stores.
You can replace an existing server module with your own server module

On startup, the directory server loads your plug-in configuration and library. It calls your plug-in functions while processing various LDAP requests.

46.1.4 Guidelines for Designing Server Plug-ins

Use the following guidelines when designing plug-ins:

Use plug-ins to guarantee that when a specific LDAP operation is performed, related actions are also performed.
Use plug-ins only for centralized, global operations that should be invoked for the program body statement, regardless of which user or LDAP application issues the statement.
Do not create recursive plug-ins. For example, creating a pre_ldap_bind plug-in that itself issues an ldapbind statement would cause the plug-in to execute recursively until it has run out of resources.

Use plug-ins judiciously. They are executed every time the associated LDAP operation occurs.

46.1.5 Using the Server Plug-in Framework

The plug-in framework is the environment in which you develop, configure, and apply the plug-ins. Each individual plug-in instance is called a plug-in module.

The plug-in framework includes the following:

Plug-in configuration tools
Plug-in module interface
Plug-in LDAP APIs:
- PL/SQL package ODS.LDAP_PLUGIN
- Java package oracle.ldap.ospf

For both languages, you follow these general steps to use the server plug-in framework:

Write a user-defined plug-in procedure in PL/SQL or Java.
Compile the plug-in module.
Register the plug-in module through the configuration entry interface by using either the command line or Oracle Directory Services Manager.

Note:
Access to external network services in database is restricted. If DBMS_LDAP package is used in PL/SQL plug-ins, make sure that proper user access controls are configured in the database to enable external network calls by the plug-ins. See Managing Fine-Grained Access in PL/SQL Packages and Types to know about PL/SQL packages and Oracle Application Security access control lists (ACL).
Without following the procedure to configure user access controls, you may encounter "ORA-24247: network access denied by access control list (ACL)" while using OID PL/SQL plug-in.

46.1.6 LDAP Operations Supported by Oracle Internet Directory

The Oracle Internet Directory server supports plug-ins for the following LDAP operations:

ldapadd
ldapbind
ldapcompare
ldapdelete
ldapmoddn (Java only)
ldapmodify
ldapsearch

46.1.7 Understanding LDAP Timings Supported by Oracle Internet Directory

Oracle Internet Directory supports four operation timings for plug-ins:

pre
post
when
when_replace

This section contains the following topics:

46.1.7.1 About Pre-Operation Server Plug-ins

The server calls pre-operation plug-in modules before performing the LDAP operation. The main purpose of this type of plug-in is to validate data before the data is used in the LDAP operation.

When an exception occurs in the pre-operation plug-in, one of the following occurs:

When the return error code indicates warning status, the associated LDAP request proceeds.
When the return code indicates failure status, the request does not proceed.

If the associated LDAP request fails later on, the directory does not roll back the committed code in the plug-in modules.

46.1.7.2 About Post-Operation Server Plug-ins

The Oracle Internet Directory server calls post-operation plug-in modules after performing an LDAP operation. The main purpose of this type of plug-in is to invoke a function after a particular LDAP operation is executed. For example, logging and notification are post-operation plug-in functions.

When an exception occurs in the post-operation plug-in, the associated LDAP operation is not rolled back.

If the associated LDAP request fails, the post plug-in is still executed.

46.1.7.3 About When-Operation Server Plug-ins

The directory calls when-operation plug-in modules while performing standard LDAP operations. A when-operation plug-in executes immediately before the server's own code for the operation. The main purpose of this type of plug-in is to augment existing operations within the same LDAP transaction. If the when-operation plug-in fails, the standard LDAP operation does not execute. If the when-operation plug-in completes successfully, but the standard LDAP operation fails, then the changes made in the plug-in are not rolled back.

You can, for example, use a when-operation plug-in with the ldapcompare operation. The directory executes its server compare code and executes the plug-in module defined by the plug-in developer.

PL/SQL when-operation plug-ins are supported in ldapadd, ldapdelete, and ldapmodify. Java when_operation plug-ins are supported in ldapadd, ldapdelete, ldapmoddn, ldapmodify, and ldapsearch.

46.1.7.4 About When_Replace-Operation Server Plug-ins

A when_replace-operation plug-in executes instead of the server's code for the operation. You can, for example, use a when_replace plug-in with the ldapcompare operation. The directory does not execute its compare code. Instead it relies on the plug-in module to perform the comparison.

PL/SQL when_replace-operation plug-ins are supported only in ldapadd, ldapcompare, ldapdelete, ldapmodify, and ldapbind.

Java when_replace-operation plug-ins are supported in ldapadd, ldapbind, ldapcompare, ldapdelete, ldapmoddn, ldapmodify and ldapsearch.

46.1.8 Using Plug-ins in a Replication Environment

Use caution when deploying plug-ins in a replication environment.

The following bad practices can result in an inconsistent state:

Plug-in metadata replicated to other nodes
Plug-in installation on some, but not all, of the participating nodes
Implementation in the plug-in of extra checking that depends on the directory data
Changes to directory entries by plug-in programs or other LDAP operations

You can use plug-ins that change directory entries in a replication environment if you deploy the plug-in on all nodes and configure the plug-in so that changes caused by replication do not invoke the plug-in. You do that as follows:

Add the replica IDs of all the nodes to a group.
Include the group as a value in the plug-in attribute orclpluginrequestneggroup. For example:
```
orclpluginrequestneggroup: cn=pluginNegate,cn=groups,cn=oraclecontext. 
```
Whenever a plug-in detects that a change request has come from a member of the group cn=pluginNegate, the plug-in is not invoked.

46.1.9 Modifying JVM Options for Server Plug-ins

The Java server plug-ins run in a Java Virtual Machine (JVM) within the oidldapd server itself.

The JVM is implemented using the Java Native Interface (JNI). The oidldapd server passes options to the JVM when it invokes it. These JVM options are contained in the orcljvmoptions attribute of the DSA configuration entry. By default, the value of this attribute is -Xmx64M, which specifies a heap size of 64 MB. You can modify the options by changing the value of orcljvmoptions. Normally, you only need to do this if you add a plug-in that requires a greater heap size than the default of 64 M.

You can modify this attribute in the same way as other attributes of the DSA configuration entry, or by using Oracle Enterprise Manager Fusion Middleware Control. For more information, see Managing System Configuration Attributes by Using LDAP Tools and Managing JVM Options by Using Oracle Enterprise Manager Fusion Middleware Control.

46.2 Creating a Plug-in

This section describes the procedure to create a server plug-in.

To use the server plug-in framework, follow these steps:

Write a user-defined plug-in procedure in PL/SQL or Java.
Compile the plug-in module.
Register the plug-in module through the configuration entry interface by using either the command line or Oracle Directory Services Manager.

46.3 Registering a Plug-in From the Command Line

To enable the directory server to call a plug-in at the right time, you must register the plug-in with the directory server.

To register a plug-in, creatie an entry for the plug-in in the directory schema under cn=plugin,cn=subconfigsubentry.

This section contains the following topics:

46.3.1 Object Classes and Attributes to Create a Plug-in Configuration Entry

This section lists and describes the object classes and attributes you can specify in a plug-in configuration.

Table 46-1 lists and describes the object classes and attributes you can specify in a plug-in configuration.

Table 46-1 Plug-in Configuration Objects and Attributes

Name	Value	Mandatory?
`objectclass`	`orclPluginConfig`	Yes
`objectclass`	`top`	No
`dn`	Plug-in entry DN	Yes
`cn`	Plug-in entry name	Yes
`orclPluginAttributeList`	A semicolon-separated list of attribute names that controls whether the plug-in takes effect. If the target attribute is included in the list, then the plug-in is invoked. Only for `ldapcompare` and `ldapmodify` plug-ins.	No
`orclPluginEnable`	`0` = disable (default) `1` = enable	No
`orclPluginEntryProperties`	An `ldapsearch` filter type value. For example, if we specify `orclPluginEntryProperties: (&(objectclass=inetorgperson)(sn=Cezanne))`, the plug-in is not invoked if the target entry has `objectclass` equal to `inetorgperson` and `sn` equal to `Cezanne`.	No
`orclPluginIsReplace`	`0` = disable (default) `1` = enable For `when_replace` timing, enable this and set `orclPluginTiming` to `when`.	No
`orclPluginKind`	PL/SQL or Java (Default is PL/SQL)	No
`orclPluginLDAPOperation`	One of the following values: `ldapcompare` `ldapmodify` `ldapbind` `ldapadd` `ldapdelete` `ldapsearch` `ldapmoddn` (Java Only)	Yes
`orclPluginName`	Plug-in name	Yes
`orclPluginFlexfield`	Custom text information (Java only). To indicate a subtype, specify `orclPluginFlexfield;subtypename`, for example, `orclPluginFlexfield;minPwdLength: 8`	No
`orclPluginBinaryFlexfield`	Custom binary information (Java only).	No
`orclPluginSecuredFlexfield`	Custom text information that must never be displayed in clear text (Java only). To indicate a subtype, specify `orclPluginSecuredFlexfield;subtypename`, for example `orclPluginSecuredFlexfield;telephonenumber1: 650.123.456`. The value is stored and displayed in encrypted form. In a search result, it might appear as something like this: `orclPluginSecuredFlexfield;telephonenumber1: 1291zjs8134`. Be sure that Oracle Internet Directory has privacy mode enabled to ensure that users cannot retrieve this attribute in clear text. See "Privacy of Retrieved Sensitive Attributes" in Administering Oracle Internet Directory.	No
`orclPluginRequestGroup`	A semicolon-separated group list that controls if the plug-in takes effect. You can use this group to specify who can actually invoke the plug-in. For example, if you specify `orclpluginrequestgroup:cn=security,cn=groups,dc=oracle,dc=com` when you register the plug-in, the plug-in is not invoked unless the ldap request comes from the person who belongs to the group `cn=security,cn=groups,dc=oracle,dc=com`.	No
`orclPluginRequestNegGroup`	A semicolon-separated group list that controls if the plug-in takes effect. You can use this group to specify who cannot invoke the plug-in. For example, if you specify `orclpluginrequestgroup: cn=security,cn=groups,dc=oracle,dc=com`, when you register the plug-in, the plug-in is not invoked if the LDAP request comes from the person who belongs to the group `cn=security,cn=groups,dc=oracle, dc=com`.	No
`orclPluginResultCode`	An integer value to specify the ldap result code. If this value is specified, then plug-in is invoked only if the LDAP operation is in that result code scenario. This is only for the post plug-in type.	No
`orclPluginShareLibLocation`	File location of the dynamic linking library. If this value is not present, then Oracle Internet Directory server assumes the plug-in language is PL/SQL.	No
`orclPluginSubscriberDNList`	A semicolon separated DN list that controls if the plug-in takes effect. If the target DN of an LDAP operation is included in the list, then the plug-in is invoked.	No
`orclPluginTiming`	One of the following values: `pre` `when` `post` For when_replace timing, specify `when` and enable `orclPluginIsReplace`.	No
`orclPluginType`	One of the following values: `configuration` `attribute` `password_policy` `syntax` `matchingrule` See Also: "LDAP Operations Supported by Oracle Internet Directory".	Yes
`orclPluginVersion`	Supported plug-in version number	No
`orclPluginClassReloadEnabled`	If this value is 1, the server reloads the plug-in class every time it invokes the plug-in. If the value is 0, the server loads the class only the first time it invokes the plug-in.

46.3.2 Adding a Plug-in Configuration Entry by Using Command-Line Tools

To add a plug-in configuration entry from the command line, create an LDIF file containing the plug-in configuration. Specify a DN under cn=plugin,cn=subconfigsubentry.

The following two-part LDIF file, my_ldif_file.ldif, creates an entry for an operation-based plug-in called my_plugin1:

dn: cn=when_comp,cn=plugin,cn=subconfigsubentry
objectclass: orclPluginConfig
objectclass: top
orclPluginName: my_plugin1
orclPluginType: configuration
orclPluginTiming: when
orclPluginLDAPOperation: ldapcompare
orclPluginEnable: 1
orclPluginVersion: 1.0.1
orclPluginIsReplace: 1
cn: when_comp
orclPluginKind: PLSQL
orclPluginSubscriberDNList: dc=COM,c=us;dc=us,dc=oracle,dc=com;dc=org,dc=us;
 o=IMC,c=US
orclPluginAttributeList: userpassword

dn: cn=post_mod_plugin, cn=plugin,cn=subconfigsubentry
objectclass: orclPluginConfig
objectclass: top
orclPluginName: my_plugin1
orclPluginType: configuration
orclPluginTiming: post
orclPluginLDAPOperation: ldapmodify
orclPluginEnable: 1
orclPluginVersion: 1.0.1
cn: post_mod_plugin
orclPluginKind: PLSQL

Add this file to the directory with a command similar to this:

ldapadd -p 3060 -h myhost -D binddn -q -f my_ldif_file.ldif

Note:

The plug-in configuration entry is not replicated. Replicating it would create an inconsistent state.

46.4 Managing Plug-ins by Using Oracle Directory Services Manager and Oracle Enterprise Manager Fusion Middleware Control

Use Oracle Directory Services Manager to register, edit, and delete plug-ins.

This section contains the following topics:

46.4.1 Creating a Plug-in by Using Oracle Directory Services Manager

This section describes the procedure to create a plug-in using Oracle Directory Services Manager.

To create a new plug-in, follow these steps:

Invoke Oracle Directory Services Manager and connect to the Oracle Internet Directory server as described in Invoking Oracle Directory Services Manager.
From the task selection bar, select Advanced.
Expand Plug-in. Entries appear in the left panel.
To enable a plug-in management configuration entry, select it.
Click the Create icon.The New Plug-in window appears in the right pane.
Select Plug-in Enable if you want to enable the plug-in now.
Enter the Plug-in Name.
Select values for the other mandatory properties.
When you have finished entering the values, select OK. The plug-in you just created is now listed on the left side of the page.

46.4.2 Registering a Plug-in by Using Oracle Directory Services Manager

This section describes the procedure to register a plug-in using Oracle Directory Services Manager.

To register a plug-in, follow these steps:

Invoke Oracle Directory Services Manager and connect to the Oracle Internet Directory server as described in Invoking Oracle Directory Services Manager.
From the task selection bar, select Advanced.
Expand Plug-in. Entries appear in the left panel.
To enable a plug-in management configuration entry, select it. The Plug-in Management tab appears in the right pane.
Select Plug-in Enable.
Click Apply.
When you have finished entering the values, select OK. The plug-in you just created is now listed on the left side of the page.

46.4.3 Editing a Plug-in by Using Oracle Directory Services Manager

This section describes the procedure to edit a plug-in using Oracle Directory Services Manager.

To edit a plug-in entry, follow these steps:

From the task selection bar, select Advanced.
Expand Plug-in. Entries appear in the left panel.
To modify a plug-in management configuration entry, select it.
Enter changes to Mandatory Properties and Optional Properties on the right side of the page.
Click Apply.

46.4.4 Deleting a Plug-in by Using Oracle Directory Services Manager

This section describes the procedure to delete a plug-in using Oracle Internet Directory Services Manager.

To delete a plug-in, follow these steps:

From the task selection bar, select Advanced.
Expand Plug-in. Entries appear in the left panel.
Select the plug-in entry you want to delete.
Click the Delete icon. The plug-in entry you deleted no longer appears in the list.

46.4.5 Managing JVM Options by Using Oracle Enterprise Manager Fusion Middleware Control

JVM options are contained in the orcljvmoptions attribute of the DSA configuration entry. The default value is -Xmx64M, which sets the heap size to 64M. If you need to allocate more heap, update this attribute.

To modify this attribute by using Oracle Enterprise Manager Fusion Middleware Control, see Configuring Shared Properties. To modify it from the command line, see Managing Entries by Using LDAP Command-Line Tools.