Oracle Internet Directory Administrator's Guide 10g (10.1.4.0.1) Part Number B15991-01 |
|
|
View PDF |
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. As of 10g (10.1.4.0.1), Oracle Internet Directory supports plug-ins in Java as well as in PL/SQL.
This chapter contains these topics:
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. |
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 32-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.
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.
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.
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.
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.
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
.
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
.
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 Manager.
Creating a PL/SQL 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 PL/SQL 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.
Before you compile a Java plug-in, ensure that your CLASSPATH is set to $ORACLE_HOME/ldap/jlib/ospf.jar
.
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.
See Also:
for information about the attributes in the orclPluginConfig object class |
This section contains these topics:
Registering and Managing Plug-ins by Using Oracle Directory Manager
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 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, Mandatory Properties tab page and Optional Properties tab page, enter values in the fields. These fields are described in Table A-15 and Table A-16.
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.
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, Mandatory Properties tab page and Optional Properties tab page, modify the values in the appropriate fields. These fields are described in Table A-17 and Table A-18. To add attributes not shown on the Mandatory Properties tab page or Optional Properties tab page, use the Advanced tab page, described in Table A-19.
Choose OK.
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.
This section provides examples of how to create, modify, and delete plug-in configuration entries by using command-line tools.
See Also:
for information about the attributes in the orclPluginConfig object class |
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. |
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