26 Oracle Internet Directory Plug-in Framework

This chapter describes how you can extend the capabilities of the Oracle directory server by using plug-ins developed by either Oracle Corporation or third-party vendors.

This chapter contains these topics:

About Directory Server Plug-ins
Creating Plug-ins
Registering and Managing Plug-ins

See Also:
The chapter on the Oracle Internet Directory server plug-in framework in Oracle Identity Management Application Developer's Guide.

26.1 About Directory Server Plug-ins

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 26-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 PL/SQL LDAP API and the Plug-in LDAP.

Figure 26-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. Table 26-1 explains the various kinds of operation-based plug-ins.

Table 26-1 T ypes of Operation-Based Plug-ins

Type of Plug-in	Description
Pre-operation	Plug-ins that the directory server calls before performing an LDAP operation. Typically, these plug-ins validate data before using it in an LDAP operation. If validation fails, then depending on the error or warning returned from the plug-in, the LDAP operation can decide to proceed or not. However, if the associated LDAP request fails later on, then Oracle Internet Directory does not roll back whatever the plug-in has already committed.
Post-operation	Plug-ins that the directory server calls after performing an LDAP operation. Typically, these plug-ins invoke a function, such as logging or notification, when the directory server performs a particular operation. If the plug-in fails, then the directory server does not roll back the associated LDAP operation. The plug-in executes regardless of whether the associated LDAP request fails.
When-operation	Plug-ins that the directory server calls in addition to standard processing. Typically, these plug-ins augment existing functionality, performing extra operations in the same transactions as the corresponding LDAP operations. If either the LDAP operation or the plug-in fails, then the directory server rolls back the changes. There are different types of When-operation plug-ins—namely, Add-on and Replace. The Add-on plug-in can perform ldapadd, ldapdelete, and ldapmodify operations. The Replace plug-in can perform ldapcompare, ldapbind, and ldapmodify operations. For example, for the ldapcompare operation, you can use the When Add-on type plug-in. Oracle Internet Directory server executes its server compare code and executes the plug-in module defined by the plug-in developer. For the Replace Type plug-in, Oracle Internet Directory does not execute its own compare code. Instead, it relies on the plug-in module to do the comparison and pass back the compare result. The server comparison procedures are replaced by the plug-in module.

Type of Plug-in

Description

Pre-operation

Plug-ins that the directory server calls before performing an LDAP operation. Typically, these plug-ins validate data before using it in an LDAP operation. If validation fails, then depending on the error or warning returned from the plug-in, the LDAP operation can decide to proceed or not. However, if the associated LDAP request fails later on, then Oracle Internet Directory does not roll back whatever the plug-in has already committed.

Post-operation

Plug-ins that the directory server calls after performing an LDAP operation. Typically, these plug-ins invoke a function, such as logging or notification, when the directory server performs a particular operation. If the plug-in fails, then the directory server does not roll back the associated LDAP operation. The plug-in executes regardless of whether the associated LDAP request fails.

When-operation

Plug-ins that the directory server calls in addition to standard processing. Typically, these plug-ins augment existing functionality, performing extra operations in the same transactions as the corresponding LDAP operations. If either the LDAP operation or the plug-in fails, then the directory server rolls back the changes.

There are different types of When-operation plug-ins—namely, Add-on and Replace.

The Add-on plug-in can perform ldapadd, ldapdelete, and ldapmodify operations.

The Replace plug-in can perform ldapcompare, ldapbind, and ldapmodify operations.

For example, for the ldapcompare operation, you can use the When Add-on type plug-in. Oracle Internet Directory server executes its server compare code and executes the plug-in module defined by the plug-in developer. For the Replace Type plug-in, Oracle Internet Directory does not execute its own compare code. Instead, it relies on the plug-in module to do the comparison and pass back the compare result. The server comparison procedures are replaced by the plug-in module.

26.2 Creating Plug-ins

Creating a plug-in module is like creating a PL/SQL package. Both have a specification part and a body part. The directory, not the plug-in, defines the plug-in specification because the specification serves as the interface between Oracle Internet Directory and the custom plug-in.

For security reasons and for the integrity of the LDAP server, you can compile plug-ins only in the ODS database schema. You must compile them in the database that serves as the backend database of Oracle Internet Directory.

26.3 Registering and Managing Plug-ins

To enable the directory server to call a plug-in at the right moment, you must register the plug-in with the directory server. Do this by creating a configuration entry for the plug-in under cn=plugin,cn=subconfigsubentry. This plug-in must have orclPluginConfig as one of its object classes.

26.3.1 Registering and Managing Plug-ins by Using Oracle Directory Manager

This section provides examples of how to create, modify, and delete plug-in configuration entries by using Oracle Directory manager.

26.3.1.1 Adding a Plug-in Configuration Entry by Using Oracle Directory Manager

To register a plug-in:

In the navigator pane, expand Oracle Internet Directory Servers, then directory server instance.
Select Plug-in Management. The Plug-in Management window appears in the right pane.
Choose Create. The New Plug-in dialog box appears.
In the New Plug-in dialog box, enter values in the fields. These fields are described in Table A-15.
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.
Choose OK.

26.3.1.2 Editing a Plug-in by Using Oracle Directory Manager

To edit a plug-in entry:

In the navigator pane, expand Oracle Internet Directory Servers, then directory server instance.
Select Plug-in Management. The Plug-in Management window appears in the right pane.
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.
In the Plug-in: dialog box, modify the values in the appropriate fields. These fields are described in Table A-15.
Choose OK.

26.3.1.3 Deleting a Plug-in by Using Oracle Directory Manager

To delete a plug-in:

In the navigator pane, expand Oracle Internet Directory Servers, then directory server instance.
Select Plug-in Management. The Plug-in Management window appears in the right pane.
In the right pane, select the name of the plug-in you want to delete, then choose Edit. The Plug-in: dialog box appears.
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.

26.3.2 Registering and Managing Plug-ins by Using Command-Line Tools

This section provides examples of how to create, modify, and delete plug-in configuration entries by using command-line tools.

26.3.2.1 Examples: Adding a Plug-in Configuration Entry by Using Command-Line Tools

In the following examples, an entry is created for an operation-based plug-in called my_plugin1. The LDIF file is named my_ldif_file.ldif.

26.3.2.1.1 Example 1: Creating an Operation-Based Plug-in Entry for Compare Operations

The following is an example LDIF file to create such an object:

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

26.3.2.1.2 Example 2: Creating an Operation-Based Plug-in Entry for Modify Operations

The following is an example LDIF file to create such an object:
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 the following command:

ldapadd -p 389 -h myhost -D binddn -w password -f my_ldif_file.ldif

When you have added this entry to the directory, the directory server validates the plug-in by quickly executing it and checking for compilation or access privilege errors. It then gathers more information about this plug-in—such as timing and the type of LDAP operation related to the plug-in.

Note:

To avoid creating an inconsistent state, metadata for the plug-in configuration entry, cn=plugin, cn=subconfigsubentry, is not replicated in the replication environment.

26.3.2.2 Example: Modifying a Plug-in Configuration Entry by Using Command-Line Tools

This is an example of disabling a plug-in:

ldapmodify -h  host_name -p  port_number -D cn=orcladmin -w orcladminpwd <<EOF
dn: cn=post_mod_plugin,cn=plugin,cn=subconfigsubentry
changetype: modify
replace: orclPluginEnable
orclPluginEnable: 0
EOF

26.3.2.3 Example: Deleting a Plug-in Configuration Entry by Using Command-Line Tools

This is an example of deleting a plug-in:

ldapdelete -h  host_name -p port_number -D cn=orcladmin \
           -w orcladminpwd "cn=post_mod_plugin,cn=plugin,cn=subconfigsubentry"