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.

See Also:

The Configuring a Customized Password Policy Plug-Inchapter about the password policy plug-in in Administering Oracle Internet Directory. Tise chapter contains an example of how to implement your own password value checking and place it into the Oracle Internet Directory server.

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:

  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.

    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:

  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.

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:

  1. Invoke Oracle Directory Services Manager and connect to the Oracle Internet Directory server as described in 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.

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:

  1. Invoke Oracle Directory Services Manager and connect to the Oracle Internet Directory server as described in 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.

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:

  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.

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:

  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.

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.