44 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:

44.1 Introduction to Developing Plug-ins for the Oracle Internet Directory Server

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

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 44-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 44-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. The next section explains the various kinds of operation-based plug-ins.

44.1.1 Passing Options to the JVM

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 Section 9.4, "Managing System Configuration Attributes by Using LDAP Tools" and Section 44.4.5, "Managing JVM Options by Using Oracle Enterprise Manager Fusion Middleware Control."

44.1.2 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. Appendix F provides additional information specific to PL/SQL plug-ins and Appendix E provides additional information specific to Java plug-ins.

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

44.1.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 Fusion Middleware Administrator's Guide for Oracle Internet Directory. The chapter contains an example of how to implement your own password value checking and place it into the Oracle Internet Directory server.

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

44.1.6 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 Services Manager.

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

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

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

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

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

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

44.2 Creating a Plug-in

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

44.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. You do this by creating an entry for the plug-in in the directory schema under cn=plugin,cn=subconfigsubentry.

44.3.1 Creating a Plug-in Configuration Entry

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

Table 44-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 Fusion Middleware Administrator's Guide for 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 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.

 

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

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

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

This section contains the following topics:

  1. Section 44.4.1, "Creating a New Plug-in by Using Oracle Directory Services Manager"

  2. Section 44.4.2, "Registering a Plug-in by Using Oracle Directory Services Manager"

  3. Section 44.4.3, "Editing a Plug-in by Using Oracle Directory Services Manager"

  4. Section 44.4.4, "Deleting a Plug-in by Using Oracle Directory Services Manager"

  5. Section 44.4.5, "Managing JVM Options by Using Oracle Enterprise Manager Fusion Middleware Control"

44.4.1 Creating a New Plug-in by Using Oracle Directory Services Manager

To create a new plug-in:

  1. Invoke Oracle Directory Services Manager and connect to the Oracle Internet Directory server as described in Section 7.4.5, "Invoking Oracle Directory Services Manager."

  2. From the task selection bar, select Advanced.

  3. Expand Plug-in. Entries appear in the left panel.

  4. To enable a plug-in management configuration entry, select it.

  5. Click the Create icon.The New Plug-in window appears in the right pane.

  6. Select Plug-in Enable if you want to enable the plug-in now.

  7. Enter the Plug-in Name.

  8. Select values for the other mandatory properties.

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

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

To register a plug-in:

  1. Invoke Oracle Directory Services Manager and connect to the Oracle Internet Directory server as described in Section 7.4.5, "Invoking Oracle Directory Services Manager."

  2. From the task selection bar, select Advanced.

  3. Expand Plug-in. Entries appear in the left panel.

  4. To enable a plug-in management configuration entry, select it. The Plug-in Management tab appears in the right pane.

  5. Select Plug-in Enable.

  6. Click Apply.

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

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

To edit a plug-in entry:

  1. From the task selection bar, select Advanced.

  2. Expand Plug-in. Entries appear in the left panel.

  3. To modify a plug-in management configuration entry, select it.

  4. Enter changes to Mandatory Properties and Optional Properties on the right side of the page.

  5. Click Apply.

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

To delete a plug-in:

  1. From the task selection bar, select Advanced.

  2. Expand Plug-in. Entries appear in the left panel.

  3. Select the plug-in entry you want to delete.

  4. Click the Delete icon. The plug-in entry you deleted no longer appears in the list.

44.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 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 Section 9.2.2, "Configuring Shared Properties." To modify it from the command line, seeSection 13.3, "Managing Entries by Using LDAP Command-Line Tools."