11 Developing Plug-ins for the Oracle Internet Directory Server

This chapter introduces Oracle Internet Directory server plug-ins and presents an overview of the plug-in framework for Oracle Internet Directory.

This chapter contains these topics:

• What is a Server Plug-in?

• Supported Languages for Server Plug-ins

• Server Plug-in Prerequisites

• Server Plug-in Benefits

• Guidelines for Designing Plug-ins

• What Is the Server Plug-in Framework?

• LDAP Operations and Timings Supported by the Directory

• Registering a Plug-in

• Managing Plug-ins by Using Oracle Directory Manager

11.1 What is a Server Plug-in?

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 plugin include:

• An LDAP operation, such as ldapbind or ldapmodify

• A timing, relative to the LDAP operation, such as pre_bind or post_modify

11.2 Supported Languages for Server Plug-ins

As of 10g (10.1.4.0.1), Oracle Internet Directory supports plug-ins in Java as well as in PL/SQL. This chapter provides information common to Java and PL/SQL plug-ins. Chapter 12 provides information specific to PL/SQL plug-ins and Chapter 13 provides information specific to Java plug-ins.

11.3 Server Plug-in Prerequisites

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

11.4 Server Plug-in Benefits

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.

See Also: The chapter about the password policy plug-in in Oracle Internet Directory Administrator's Guide. The chapter contains an example of how to implement your own password value checking and place it into the Oracle Internet Directory server.

11.5 Guidelines for Designing 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.

11.6 What Is 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:

1. Write a user-defined plug-in procedure in PL/SQL or Java.

2. Compile the plug-in module.

3. Register the plug-in module through the configuration entry interface by using either the command line or Oracle Directory Manager.

11.7 LDAP Operations and Timings Supported by the Directory

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

• ldapadd

• ldapbind

• ldapcompare

• ldapdelete

• ldapmoddn (Java only)

• ldapmodify

• ldapsearch

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

• pre

• post

• when

• when_replace

These are explained in the next four sections.

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

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

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

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

11.8 Registering a Plug-in

To enable the directory server to call a plug-in at the right time, you must register the plug-in with the directory server. You do this by creating an entry for the plug-in in the directory schema under cn=plugin,cn=subconfigsubentry.

11.8.1 Plug-in Configuration Entry

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

Table 11-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 Oracle Internet Directory Administrator's Guide.	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 will not be 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 will be 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: operational attribute password_policy syntax matchingrule See Also: "LDAP Operations and Timings Supported by the 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.

11.8.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: operational
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: operational
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 389 -h myhost -D binddn -w password -f my_ldif_file.ldif

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

11.9 Managing Plug-ins by Using Oracle Directory Manager

You can register, edit, and delete plug-ins by using Oracle Directory Manager.

11.9.1 Registering a Plug-in by Using Oracle Directory Manager

To register a plug-in:

1. In the navigator pane, expand Oracle Internet Directory Servers > directory server instance, then select Plug-in Management. The Plug-in Management window appears in the right pane.

2. Choose Create. The New Plug-in dialog box appears.

3. Enter values in the New Plug-in dialog box.

4. When you have finished entering the values, choose OK. This returns you to the Plug-in Management window. The plug-in you just created is listed in the Plug-in Entry Name column.

5. Choose Apply.

11.9.2 Editing a Plug-in by Using Oracle Directory Manager

To edit a plug-in entry:

1. In the navigator pane, expand Oracle Internet Directory Servers > directory server instance, then select Plug-in Management. The Plug-in Management window appears in the right pane.

2. In the right pane, select the name of the plug-in entry you want to edit, then choose Edit. The Plug-in dialog box appears.

3. In the Plug-in dialog box, modify the values in the appropriate fields.

4. Choose OK.

11.9.3 Deleting a Plug-in by Using Oracle Directory Manager

To delete a plug-in:

1. In the navigator pane, expand Oracle Internet Directory Servers > directory server instance, then select Plug-in Management. The Plug-in Management window appears in the right pane.

2. In the right pane, select the name of the plug-in you want to delete, then choose Edit. The Plug-in: dialog box appears.

3. In the Plug-in dialog box, choose Delete, and, when prompted, confirm your deletion. This returns you to the Plug-in Management window. The plug-in entry you deleted no longer appears in the list.