9
Oracle Internet Directory Server Plug-in Framework

This chapter explains how to use the plug-in framework for the Oracle Internet Directory server to facilitate custom development.

This chapter contains these topics:

Introduction

The plug-in framework for Oracle Internet Directory enables developers to extend LDAP operations. For example:

To authenticate a user when the user information is not stored in the directory server.
To attach certain custom operations to an LDAP operation. For example, some LDAP users may have different LDAP data value validation. For each ldapadd operation, they may have different ways to validate the attribute values.

Prerequisite Knowledge

In order to develop Oracle Internet Directory plug-ins you should be familiar with:

Generic LDAP concepts
Oracle Internet Directory
Oracle Internet Directory integration with Oracle9i Application Server
Knowledge of SQL, PL/SQL, and database RPCs

Concepts

This section explains plug-in concepts.

This section contains these topics:

About Directory Server Plug-ins

To extend the capabilities of the Oracle Internet Directory server, you can write your own server plug-in. A server plug-in is a PL/SQL package, shared object or library, or a dynamic link library on Windows NT, containing your own functions. (Currently, we support PL/SQL.)

You can write your own plug-in functions to extend the functionality of the Oracle Internet Directory server using the following methods:

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 define password policy
You can be authenticated through external credential stores
You can replace an existing server module by defining your own server module. For example, you can implement your own password syntax checking and place it into Oracle Internet Directory server.
You can provide alternate syntax/matching rules when comparing certain attribute values.

On startup, the directory server loads your plug-in configuration and library, and calls your plug-in functions during the course of processing various LDAP requests.

About Server Plug-in Framework

Oracle Internet Directory server plug-in framework is the environment in which the plug-in user can 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 API (ODS.LDAP_PLUGIN package)

The steps to use the server plug-in framework are as follows:

Write a user-defined plug-in procedure. This plug-in module must be written in PL/SQL.

Note:
The PL/SQL language is currently supported.
Compile the plug-in module against the same database which serves as the Oracle Internet Directory backend database.
Grant execute permission of the plug-in module to ods_server.
Register the plug-in module through the configuration entry interface where the following are specified:
- Names of the plug-ins
- Type of the plug-ins
Restart the LDAP server.

Figure 9-1 Oracle Internet Directory Server Plug-in Framework

Text description of oiddg010.gif follows

Text description of the illustration oiddg010.gif

Operation-Based Plug-ins Supported in Oracle Internet Directory

For operation-based plug-ins, there are pre-operation, post-operation, and when-operation plug-ins.

Pre-Operation 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 can be 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, then Oracle Internet Directory server does not rollback the committed code in the plug-in modules.

Post-Operation 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 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 be rolled back.

If the associated LDAP request fails, then the post plug-in will still be executed.

When-Operation Plug-ins

The server calls when-operation plug-in modules in addition to standard processing. The main purpose of this type of plug-in is to augment existing functionality. Any extra operations that need to be thought of as part of an LDAP operation, that is, in the same LDAP transaction, must use the WHEN option. The when-operation plug-in is essentially in the same transaction as the associated LDAP request. If either the LDAP request or the plug-in program fails, then all the changes are rolled back.

There are different types of When-operation plug-ins.

Add-on
Replace

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 When Replace plug-in, Oracle Internet Directory does not execute its own compare code and 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.

When Replace operation plug-ins are only supported in ldapcompare and ldapmodify. When Add-on plug-ins are supported in ldapadd, ldapdelete, ldapmodify, ldapcompare, ldapbind, and ldapsearch.

Requirements

This section explains requirements for plug-ins.

This section contains these topics:

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 (through the LDAP PL/SQL API) statement, causes the plug-in to execute recursively until it has run out of resources.

Note:
Use plug-ins on the LDAP PL/SQL API judiciously. They are executed for every LDAP request every time the event occurs on which the plug-in is created

Types of Plug-in Operations

A plug-in can be associated with ldapbind, ldapadd, ldapmodify, ldapcompare, ldapsearch, and ldapdelete operations.

Naming Plug-ins

Plug-in names (PL/SQL package names) must be unique with respect to other plug-ins or stored procedures in the same database schema. Plug-in names do not need to be unique with respect to other database schema objects, such as tables and views. For example, a database table and a plug-in can have the same name (however, to avoid confusion, this is not recommended).

Creating Plug-ins

The process to create a plug-in module is the same as to create a PL/SQL package. There is a plug-in specification part and a plug-in body part. Oracle Internet Directory defines the plug-in specification because the specification serves as the interface between Oracle Internet Directory server and custom plug-ins.

For security purposes and for the integrity of the LDAP server, plug-ins can only be compiled in ODS database schema against the database which serves as the backend database of the Oracle Internet Directory server.

Plug-in Module Interface Package Specifications

For different types of plug-ins, there are different package specifications defined. You can name the plug-in package. However, you must follow the signatures defined for each type of plug-in procedure.

Table 9-1 Plug-in Module Interface

Plug-in Item	User Defined	Oracle Internet Directory-Defined
Plug-in Package Name	X	-
Plug-in Procedure Name	-	X
Plug-in Procedure Signature	-	X

The following table shows the parameters for different kinds of operation-based plug-ins.

Table 9-2 Operation-Based and Attribute-Based Plug-in Procedure Signatures

Invocation Context	Procedure Name	IN Parameters	OUT Parameters
Before ldapbind	PRE_BIND	Ldapcontext, Bind DN, Password	Return code, Error message
With ldapbind	WHEN_BIND	Ldapcontext, Bind DN, Password	Return code, Error message
After ldapbind	POST_BIND	Ldapcontext, Bind result, Bind DN, Password	Return code, Error message
Before ldapmodify	PRE_MODIFY	Ldapcontext, DN, Mod structure	Return code, Error message
With ldapmodify	WHEN_MODIFY	Ldapcontext, DN, Mod structure	Return code, Error message
With ldapmodify but replacing the default server behavior	WHEN_MODIFY_REPLACE	Ldapcontext, DN, Mod structure	Return code, Error message
After ldapmodify	POST_MODIFY	Ldapcontext, Modify result, DN, Mod structure	return code, error message
Before ldapcompare	PRE_COMPARE	Ldapcontext, DN, attribute, value	return code, error message
With ldapcompare	WHEN_COMPARE	Ldapcontext, DN, attribute, value	return code, error message
With ldapcompare but replacing the default server behavior	WHEN_COMPARE_REPLACE	Ldapcontext, Compare result, DN, attribute, value	compare result, return code, error message
After ldapcompare	POST_COMPARE	Ldapcontext, Compare result, DN, attribute, value	return code, error message
Before ldapadd	PRE_ADD	Ldapcontext, Entry	return code, error message
With ldapadd	WHEN_ADD	Ldapcontext, Entry	return code, error message
After ldapadd	POST_ADD	Ldapcontext, Add result, Entry	return code, error message
Before ldapdelete	PRE_DELETE	Ldapcontext, DN	return code, error message
With ldapdelete	WHEN_DELETE	Ldapcontext, DN	return code, error message
After ldapdelete	POST_DELETE	Ldapcontext, Delete result, DN	return code, error message
Before ldapsearch	PRE_SEARCH	Ldapcontext, Base DN, scope, filter	return code, error message
With ldapsearch	WHEN_SEARCH	Ldapcontext, Base DN, scope, filter	return code, error message
After ldapsearch	POST_SEARCH	Ldap context, Search result, Base DN, scope, filter	return code, error message

See Also:

Error Handling for valid values for the return code and error message
LDAP Server Error Code Reference for valid values for the OUT parameters return code
Plug-in Module Interface Specifications for complete supported procedure signatures

Compiling Plug-ins

Plug-ins are exactly the same as PL/SQL stored procedures. A PL/SQL anonymous block is compiled each time it is loaded into memory. Compilation involves the following stages:

Syntax checking: PL/SQL syntax is checked, and a parse tree is generated.
Semantic checking: Type checking and further processing on the parse tree.
Code generation: The pcode is generated.

If errors occur during the compilation of a plug-in, then the plug-in is not created. You can use the SHOW ERRORS statement in SQL*Plus or Enterprise Manager to see any compilation errors when you create a plug-in, or you can SELECT the errors from the USER_ERRORS view.

All plug-in modules must be compiled in the ODS database schema.

Dependencies

Compiled plug-ins have dependencies. They become invalid if an object depended upon, such as a stored procedure or function called from the plug-in body, is modified. Plug-ins that are invalidated for dependency reasons must be recompiled before the next invocation.

Recompiling Plug-ins

Use the ALTER PACKAGE statement to manually recompile a plug-in. For example, the following statement recompiles the my_plugin plug-in:

ALTER PACKAGE my_plugin COMPILE PACKAGE;

Granting Permission

Use the GRANT EXECUTE statement to grant execute permission to ods_server for the plug-in modules.

Registering 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 an entry for the plug-in under cn=plugin,cn=subconfigsubentry.

The orclPluginConfig Object Class

A plug-in must have orclPluginConfig as one of its object classes. This is a structural object class, and its super class is top. Table 9-3 lists and describes its attributes.

Table 9-3 Plug-in Attribute Names and Values

Attribute Name	Attribute Value	Mandatory	Optional
Cn	Plug-in entry name	X	-
orclPluginName	Plug-in package name	X	-
orclPluginType	One of the following values: operational attribute password_policy syntax matchingrule See Also: Operation-Based Plug-ins Supported in Oracle Internet Directory	X	-
orclPluginKind	PL/SQL	-	X
orclPluginEnable	0 = disable (default) 1 = enable	-	X
orclPluginVersion	Supported plug-in version number	-	X
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.	-	X
orclPluginLDAPOperation	One of the following values: ldapcompare ldapmodify ldapbind ldapadd ldapdelete ldapsearch	-	X
orclPluginTiming	One of the following values: pre when post	-	X
orclPluginIsReplace	0 = disable (default) 1 = enable For WHEN timing plug-in only	-	X
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.	-	X

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

Plug-ins must be added to Oracle Internet Directory server so that the server is aware of additional operations that must be performed at the correct time.

When the plug-in successfully compiles against the Oracle Internet Directory backend database, create a new entry and place it under cn=plugin,cn=subconfigsubentry.

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

Example 1

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

Example 2

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.

Notes:

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

Managing Plug-ins

This section explains modifying plug-ins and debugging plug-ins.

Modifying Plug-ins

Similar to a stored procedure, a plug-in cannot be explicitly altered. It must be replaced with a new definition.

When replacing a plug-in, you must include the OR REPLACE option in the CREATE PACKAGE statement. The OR REPLACE option enables a new version of an existing plug-in to replace an older version without having an effect on grants made for the original version of the plug-in.

Alternatively, the plug-in can be dropped using the DROP PACKAGE statement, and you can rerun the CREATE PACKAGE statement.

If the plug-in name (the package name) is changed, then you must register the new plug-in again.

Debugging Plug-ins

You can debug a plug-in using the same facilities available for stored procedures.

Enabling and Disabling Plug-ins

To turn the plug-in on/off, modify the value of orclPluginEnable in the plug-in configuration object. For example, modify the value of orclPluginEnable in cn=post_mod_plugin, cn=plugins,cn=subconfigsubentry to be 1/0. You must restart the Oracle Internet Directory server after you modify the orclPluginEnable value.

Exception Handling

In each of the plug-in PL/SQL procedures, there must be an exception handling block to handle errors intelligently and recover from them, if possible.

See Also:

PL/SQL Programming, Error Handling manual for information about how to use exceptions in a PL/SQL programming block

Error Handling

Oracle Internet Directory requires that the return code (rc) and error message (errmsg) are set correctly in the plug-in procedures.

The valid values for the return code is as follows:

Error Code	Description
0	Success
Any number greater than zero (0)	Failure, See Also LDAP Server Error Code Reference
-1	Warning

The errmsg parameter is a string value that can pass a user's custom error message back to Oracle Internet Directory server. The size limit for errmsg is 1024 bytes. Each time Oracle Internet Directory runs the plug-in program, following the run, Oracle Internet Directory examines the return code to determine if it must display the error message.

For example, if the value for the return code is 0, then the error message value is ignored. If the value of the return code is -1 or greater than zero, then the following message is either logged in the log file or displayed on the standard output if the request came from LDAP command-line tools:

ldap addition info: customized error

Program Control Handling between Oracle Internet Directory and Plug-ins

When a plug-in exception is occurring, the following describes where the plug-in exception occurred and the Oracle Internet Directory server handling of the exception.

Table 9-4 Program Control Handling when a Plug-in Exception Occurs

Plug-in Exception Occurred in	Oracle Internet Directory Server Handling
PRE_BIND, PRE_MODIFY, PRE_ADD, PRE_SEARCH, PRE_COMPARE, PRE_DELETE	Depends on return code. If the return code is: Greater than zero (error), then no LDAP operation is performed -1 (warning), then proceed with the LDAP operation
POST_BIND, POST_MODIFY, POST_ADD, POST_SEARCH, WHEN_COMPARE, WHEN_DELETE	LDAP operation is completed. There is no rollback.
WHEN_BIND, WHEN_MODIFY, WHEN_ADD, WHEN_SEARCH, WHEN_COMPARE, WHEN_DELETE	Rollback the LDAP operation

When an LDAP operation fails, the following describes the target and the Oracle Internet Directory server handling of the failure.

Table 9-5 Program Control Handling when an LDAP Operation Fails

LDAP Operation Fails in	Oracle Internet Directory Server Handling
PRE_BIND, PRE_MODIFY, PRE_ADD, PRE_SEARCH, WHEN_COMPARE, WHEN_DELETE	Pre-operation plug-in is completed. There is no rollback.
POST_BIND, POST_MODIFY, POST_ADD, POST_SEARCH, WHEN_COMPARE, WHEN_DELETE	Proceed with post-operation plug-in. The LDAP operation result is one of the IN parameters.
WHEN_BIND, WHEN_MODIFY, WHEN_ADD, WHEN_SEARCH, WHEN_COMPARE, WHEN_DELETE	When types of plug-in changes are rolled back.
WHEN Replacement	Changes made in the plug-in program body are rolled back.

Plug-in LDAP API

There are different methods for providing API access as follows:

Allow a user to utilize the standard LDAP PL/SQL APIs. If the program logic is not carefully planned, then this can cause an infinite loop of plug-in execution.

See Also:
The DBMS_LDAP User's Guide for information about use of the LDAP PL/SQL API
Oracle Internet Directory provides the Plug-in LDAP API, which does not cause a series of plug-in actions in the Oracle Internet Directory server, if there are plug-ins configured and associated to that LDAP request.

In the Plug-in LDAP API, Oracle Internet Directory provides APIs for connecting back to the same Oracle Internet Directory server within the plug-in module. In other words, within the plug-in module, if you want to connect to any external LDAP server, you can use the DBMS_LDAP API. If you want to connect to the same Oracle Internet Directory server that is executing this plug-in itself, then you must use the Plug-in LDAP API for binding and authentication.

Within each plug-in module, there is a ldapcontext passed from Oracle Internet Directory server. When we call the Plug-in LDAP API, we must pass this ldapcontext for security and binding purposes. When binding with this ldapcontext, Oracle Internet Directory server recognizes this LDAP request is coming from a plug-in module. For this type of plug-in bind, Oracle Internet Directory server does not trigger any subsequent plug-ins, and Oracle Internet Directory server handles this kind of plug-in bind as a super-user bind. Use this plug-in bind with discretion.

See Also:

Plug-in LDAP API Specifications for coding examples

Plug-in and Replication

There are cases that can cause an inconsistent state in a replication environment as follows:

Plug-in metadata replicated to other nodes
Ldapmodify, ldapadd, or any other LDAP operation that will change the entries in the directory are used in the plug-in program
Only some of the participating nodes install the plug-in
The plug-in implements extra checking that depends on the directory data

Plug-in and DB Tools

Bulk tools do not support server plug-ins.

Security

Some Oracle Internet Directory server plug-ins require you to supply the code that preserves tight security. For example, if you replace Oracle Internet Directory's ldapcompare or ldapbind operation with your own plug-in module, you must ensure that your implementation of this operation does not omit any functionality on which security relies.

To ensure tight security, the following must be done:

Create the plug-in packages
Only the LDAP administrator can restrict the database user
Use the access control list (ACL) to set the plug-in configuration entries to be accessed only by the LDAP administrator
Be aware of the program relationship between different plug-ins

Plug-in LDAP API Specifications

CREATE OR REPLACE  PACKAGE LDAP_PLUGIN AS
    SUBTYPE SESSION IS RAW(32);
    -- Initializes the LDAP library and return a session handler
    -- for use in subsequent calls.
    FUNCTION init (ldappluginctx IN ODS.plugincontext)
      RETURN SESSION;
    -- Synchronously authenticates to the directory server using
    -- a Distinguished Name and password.
    FUNCTION simple_bind_s (ldappluginctx IN ODS.plugincontext,
                            ld            IN SESSION)
      RETURN PLS_INTEGER;
END LDAP_PLUGIN;

Usage Model and Examples

This section contains two example situations about search query logging and synchronizing two directory information trees (DITs).

Example 1: Search Query Logging

Situation: A user wants to know if it is possible to log all the ldapsearch commands.

Solution: Yes. Using the POST ldapsearch operational plug-in then the user can log all the ldapsearch commands. They can either log all the ldapsearch requests, or log all the ldapsearch requests if the search occurs under certain DNs (under a specific subtree).

To log all the ldapsearch commands, do the following:

Preparation.

Log all of the ldapsearch results into a database table. This log table will have the following columns:

timestamp
baseDN
search scope
search filter
required attribute
search result

Use the following SQL script to create the table:

drop table search_log;
create table search_log

(timestamp varchar2(50),
basedn varchar2(256),
searchscope number(1);
searchfilter varchar2(256);
searchresult number(1));

drop table simple_tab;
create table simple_tab (id NUMBER(7), dump varchar2(256));
DROP sequence seq;
CREATE sequence seq START WITH 10000;
commit;

Create the plug-in package specification.

CREATE OR REPLACE PACKAGE LDAP_PLUGIN_EXAMPLE1 AS
PROCEDURE post_search

(ldapplugincontext IN  ODS.plugincontext,
result       IN  INTEGER,
baseDN       IN  VARCHAR2,
scope        IN  INTEGER,
filterStr    IN  VARCHAR2,
requiredAttr IN  ODS.strCollection,
rc           OUT INTEGER,
errormsg     OUT VARCHAR2
);

END LDAP_PLUGIN_EXAMPLE1;
/

Create plug-in package body.

CREATE OR REPLACE PACKAGE BODY LDAP_PLUGIN_EXAMPLE1 AS
PROCEDURE post_search

(ldapplugincontext IN  ODS.plugincontext,
result       IN  INTEGER,
baseDN       IN  VARCHAR2,
scope        IN  INTEGER,
filterStr    IN  VARCHAR2,
requiredAttr IN  ODS.strCollection,
rc           OUT INTEGER,
errormsg     OUT VARCHAR2
)

      IS
BEGIN
   INSERT INTO simple_tab VALUES

(to_char(sysdate, 'Month DD, YYYY HH24:MI:SS'), baseDN, scope, 
filterStr, result);

   -- The following code segment demonstrate how to iterate
   -- the ODS.strCollection 
   FOR l_counter1 IN 1..requiredAttr.COUNT LOOP
      INSERT INTO simple_tab
        values (seq.NEXTVAL, 'req attr ' || l_counter1 || ' = ' ||
                requiredAttr(l_counter1));
   END LOOP;
   rc := 0;
   errormsg := 'no post_search plguin error msg';
   COMMIT;
EXCEPTION
   WHEN others THEN
      rc := 1;
      errormsg := 'exception: post_search plguin';
END;
END LDAP_PLUGIN_EXAMPLE1;
/

Grant permission to ods_server.

GRANT EXECUTE ON LDAP_PLUGIN_EXAMPLE1 TO ods_server;

Use the following to construct an LDIF file (register_post_search.ldif):

cn=post_search,cn=plugin,cn=subconfigsubentry
objectclass=orclPluginConfig
objectclass=top
orclPluginName=ldap_plugin_example1
orclPluginType=operational
orclPluginTiming=post
orclPluginLDAPOperation=ldapsearch
orclPluginEnable=1
orclPluginVersion=1.0.1
cn=post_search
orclPluginKind=PLSQL

Using the ldapadd command-line tool to add this entry:

% ldapadd -p port_number -h host_name -D bind_dn -w passwd -v -f register_
post_search.ldif

Restart the Oracle Internet Directory server

Example 2: Synchronizing Two DITs

Situation: There are two dependent products under cn=Products, cn=oraclecontext where the users in these products have a one-to-one relationship in Oracle Internet Directory. If a user in the first DIT (product 1) is deleted, we want to delete the corresponding user in the other DIT (product 2) since a a relationship exists between these users.

Is there a way to set a trigger within Oracle Internet Directory that, on the event of deleting the user in the first DIT, will call or pass a trigger to delete the user in the second DIT?

Solution: Yes, we can use the POST ldapdelete operation plug-in to handle the second deletion occurring in the second DIT.

If the first DIT has the naming context of cn=DIT1,cn=products,cn=oraclecontext and the second DIT has the naming context of cn=DIT2,cn=products,cn=oraclecontext, then the relationship between the two users in the different DITs is that they share the same ID attribute. Basically, inside of the post ldapdelete plug-in module, we use LDAP_PLUGIN and DBMS_LDAP APIs to delete the corresponding user in the 2nd DIT.

We must set orclPluginSubscriberDNList to cn=DIT1,cn=products,cn=oraclecontext, so that whenever we delete entries under cn=DIT1,cn=products,cn=oraclecontext, the plug-in module is invoked.

Preparation.

Assume the entries under both DITs have been added into the directory. For example, the entry id=12345,cn=DIT1,cn=products,cn=oraclecontext is in DIT1, and id=12345,cn=DIT2,cn=products,cn=oraclecontext is in DIT2.

Create the plug-in package specification.

CREATE OR REPLACE PACKAGE LDAP_PLUGIN_EXAMPLE2 AS
PROCEDURE post_delete

(ldapplugincontext IN  ODS.plugincontext,
result   IN  INTEGER,
dn       IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

END LDAP_PLUGIN_EXAMPLE2;
/

Create plug-in package body.

CREATE OR REPLACE PACKAGE BODY LDAP_PLUGIN_EXAMPLE2 AS
PROCEDURE post_delete

(ldapplugincontext IN  ODS.plugincontext,
result   IN  INTEGER,
dn       IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
)

    IS
     retval       PLS_INTEGER;
     my_session   DBMS_LDAP.session;
     newDN        VARCHAR2(256);
BEGIN
   retval         := -1;
   my_session := LDAP_PLUGIN.init(ldapplugincontext);
   -- bind to the directory
   retval := LDAP_PLUGIN.simple_bind_s(ldapplugincontext, my_session);
   -- if retval is not 0, then raise exception
   newDN := REPLACE(dn, `DIT1', `DIT2');
   retval := DBMS_LDAP.delete_s(my_session, newDN);
   -- if retval is not 0, then raise exception
   rc := 0;
   errormsg := 'no post_delete plguin error msg';
EXCEPTION
   WHEN others THEN
      rc := 1;
      errormsg := 'exception: post_delete plguin';
END; 
END LDAP_PLUGIN_EXAMPLE2;
/

Use the following to construct a LDIF file (register_post_delete.ldif):

cn=post_delete,cn=plugin,cn=subconfigsubentry
objectclass=orclPluginConfig
objectclass=top
orclPluginName=ldap_plugin_example2
orclPluginType=operational
orclPluginTiming=post
orclPluginLDAPOperation=ldapdelete
orclPluginEnable=1
orclPluginSubscriberDNList=cn=DIT1,cn=oraclecontext,cn=products
orclPluginVersion=1.0.1
cn=post_delete
orclPluginKind=PLSQL

Use the ldapadd command-line tool to add the following entry:

% ldapadd -p port_number -h host_name -D bind_dn -w passwd -v -f register_
post_delete.ldif

Restart the Oracle Internet Directory server

Type Definition & Usage Model

This section gives examples of database object type definitions and LDAP_PLUGIN API Specifications.

This section contains these topics:

Database Object Type Definitions

This section contains the object definitions for those object types introduced in the Plug-in LDAP API. All these definitions are in Oracle Directory Server (ODS) database schema.

create or replace type strCollection as TABLE of VARCHAR2(512);
/

create or replace type pluginContext as TABLE of VARCHAR2(512);
/

create or replace type attrvalType as TABLE OF VARCHAR2(4000);
/
create or replace type attrobj as object (
attrname varchar2(2000),
attrval attrvalType
);
/

create or replace type attrlist as table of attrobj;
/

create or replace type entryobj as object (
entryname varchar2(2000),
attr      attrlist
);
/

create or replace type entrylist as table of entryobj;
/

create or replace type bvalobj as object (
length integer,
val    varchar2(4000)
);
/

create or replace type bvallist as table of bvalobj;
/

create or replace type modobj as object (
operation integer,
type      varchar2(256),
vals      bvallist
);
/

create or replace type modlist as table of modobj;
/

Plug-in Module Interface Specifications

You must follow the procedure signature to use ldapbind, ldapsearch, ldapdelete, ldapadd, ldapcompare, and ldapmodify plug-ins.

CREATE or replace PACKAGE plugin_test1 AS

PROCEDURE pre_add (ldapplugincontext IN  ODS.plugincontext,


dn       IN  VARCHAR2,
entry    IN  ODS.entryobj,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE when_add (ldapplugincontext IN ODS.plugincontext,

dn       IN  VARCHAR2,
entry    IN  ODS.entryobj,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE post_add (ldapplugincontext IN ODS.plugincontext,

result   IN  INTEGER,
dn       IN  VARCHAR2,
entry    IN  ODS.entryobj,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE pre_modify (ldapplugincontext IN ODS.plugincontext,

dn       IN  VARCHAR2,
mods     IN  ODS.modlist,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE when_modify (ldapplugincontext IN ODS.plugincontext,

dn       IN  VARCHAR2,
mods     IN  ODS.modlist,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE when_modify_replace (ldapplugincontext IN ODS.plugincontext,

dn       IN  VARCHAR2,
mods     IN  ODS.modlist,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE post_modify (ldapplugincontext IN ODS.plugincontext,

result   IN  INTEGER,
dn       IN  VARCHAR2,
mods     IN  ODS.modlist,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE pre_compare (ldapplugincontext IN ODS.plugincontext,

dn       IN  VARCHAR2,
attrname IN  VARCHAR2,
attrval  IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE when_compare (ldapplugincontext IN ODS.plugincontext,

dn       IN  VARCHAR2,
attrname IN  VARCHAR2,
attrval  IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE when_compare_replace (ldapplugincontext IN ODS.plugincontext,

result   OUT INTEGER,
dn       IN  VARCHAR2,
attrname IN  VARCHAR2,
attrval  IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE post_compare (ldapplugincontext IN ODS.plugincontext,

result   IN  INTEGER,
dn       IN  VARCHAR2,
attrname IN  VARCHAR2,
attrval  IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE pre_delete (ldapplugincontext IN ODS.plugincontext,

dn       IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE when_delete (ldapplugincontext IN ODS.plugincontext,

dn       IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE post_delete (ldapplugincontext IN ODS.plugincontext,

result   IN  INTEGER,
dn       IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);

PROCEDURE pre_search (ldapplugincontext IN ODS.plugincontext,

baseDN       IN  VARCHAR2,
scope        IN  INTEGER,
filterStr    IN  VARCHAR2,
requiredAttr IN  ODS.strCollection,
rc           OUT INTEGER,
errormsg     OUT VARCHAR2
);

PROCEDURE when_search (ldapplugincontext IN ODS.plugincontext,

baseDN       IN  VARCHAR2,
scope        IN  INTEGER,
filterStr    IN  VARCHAR2,
requiredAttr IN  ODS.strCollection,
rc           OUT INTEGER,
errormsg     OUT VARCHAR2
);

PROCEDURE post_search (ldapplugincontext IN ODS.plugincontext,

result       IN  INTEGER,
baseDN       IN  VARCHAR2,
scope        IN  INTEGER,
filterStr    IN  VARCHAR2,
requiredAttr IN  ODS.strCollection,
rc           OUT INTEGER,
errormsg     OUT VARCHAR2
);

PROCEDURE pre_bind (ldapplugincontext IN ODS.plugincontext,

dn IN VARCHAR2,
passwd IN VARCHAR2,
rc OUT INTEGER,
errormsg   OUT VARCHAR2
);

PROCEDURE when_bind (ldapplugincontext IN ODS.plugincontext,

dn IN VARCHAR2,
passwd IN VARCHAR2,
rc OUT INTEGER,
errormsg   OUT VARCHAR2
);

PROCEDURE post_bind (ldapplugincontext IN ODS.plugincontext,

result IN INTEGER,
dn IN VARCHAR2,
passwd IN VARCHAR2,
rc OUT INTEGER,
errormsg OUT VARCHAR2
);

END plugin_test1; /

LDAP Server Error Code Reference

  
--------------------------------------------------------------------------------      
---Package specification for DBMS_LDAP
---     This is the primary interface used by various clients to
---     make LDAP requests
------------------------------------------------------------------------
CREATE OR REPLACE PACKAGE DBMS_LDAP AS   
-- ...
     -- possible error codes we can return from LDAP server
     --
     SUCCESS                   CONSTANT NUMBER := 0;
     OPERATIONS_ERROR          CONSTANT NUMBER := 1;
     PROTOCOL_ERROR            CONSTANT NUMBER := 2;
     TIMELIMIT_EXCEEDED        CONSTANT NUMBER := 3;
     SIZELIMIT_EXCEEDED        CONSTANT NUMBER := 4;
     COMPARE_FALSE             CONSTANT NUMBER := 5;
     COMPARE_TRUE              CONSTANT NUMBER := 6;
     STRONG_AUTH_NOT_SUPPORTED CONSTANT NUMBER := 7;
     STRONG_AUTH_REQUIRED      CONSTANT NUMBER := 8;
     PARTIAL_RESULTS           CONSTANT NUMBER := 9;
     REFERRAL                  CONSTANT NUMBER := 10;
     ADMINLIMIT_EXCEEDED       CONSTANT NUMBER := 11;
     UNAVAILABLE_CRITIC        CONSTANT NUMBER := 12;
      NO_SUCH_ATTRIBUTE         CONSTANT NUMBER := 16;
     UNDEFINED_TYPE            CONSTANT NUMBER := 17;
     INAPPROPRIATE_MATCHING    CONSTANT NUMBER := 18;
     CONSTRAINT_VIOLATION      CONSTANT NUMBER := 19;
     TYPE_OR_VALUE_EXISTS      CONSTANT NUMBER := 20;
     INVALID_SYNTAX            CONSTANT NUMBER := 21;
     NO_SUCH_OBJECT            CONSTANT NUMBER := 32;
     ALIAS_PROBLEM             CONSTANT NUMBER := 33;
     INVALID_DN_SYNTAX         CONSTANT NUMBER := 34;
     IS_LEAF                   CONSTANT NUMBER := 35;
     ALIAS_DEREF_PROBLEM       CONSTANT NUMBER := 36;
     INAPPROPRIATE_AUTH        CONSTANT NUMBER := 48;
     INVALID_CREDENTIALS       CONSTANT NUMBER := 49;
     INSUFFICIENT_ACCESS       CONSTANT NUMBER := 50;
     BUSY                      CONSTANT NUMBER := 51;
     UNAVAILABLE               CONSTANT NUMBER := 52;
     UNWILLING_TO_PERFORM      CONSTANT NUMBER := 53;
     LOOP_DETECT               CONSTANT NUMBER := 54;
     NAMING_VIOLATION          CONSTANT NUMBER := 64;
     OBJECT_CLASS_VIOLATION    CONSTANT NUMBER := 65;
     NOT_ALLOWED_ON_NONLEAF    CONSTANT NUMBER := 66;
     NOT_ALLOWED_ON_RDN        CONSTANT NUMBER := 67;
     ALREADY_EXISTS            CONSTANT NUMBER := 68;
     NO_OBJECT_CLASS_MODS      CONSTANT NUMBER := 69;
     RESULTS_TOO_LARGE         CONSTANT NUMBER := 70;
     OTHER                     CONSTANT NUMBER := 80;
     SERVER_DOWN               CONSTANT NUMBER := 81;
     LOCAL_ERROR               CONSTANT NUMBER := 82;
     ENCODING_ERROR            CONSTANT NUMBER := 83;
     DECODING_ERROR            CONSTANT NUMBER := 84;
     TIMEOUT                   CONSTANT NUMBER := 85;
     AUTH_UNKNOWN              CONSTANT NUMBER := 86;
     FILTER_ERROR              CONSTANT NUMBER := 87;
     USER_CANCELLED            CONSTANT NUMBER := 88;
     PARAM_ERROR               CONSTANT NUMBER := 89;
     NO_MEMORY                 CONSTANT NUMBER := 90;
 }

9 Oracle Internet Directory Server Plug-in Framework

Introduction

Prerequisite Knowledge

Concepts

About Directory Server Plug-ins

About Server Plug-in Framework

Figure 9-1 Oracle Internet Directory Server Plug-in Framework

Operation-Based Plug-ins Supported in Oracle Internet Directory

Pre-Operation Plug-ins

Post-Operation Plug-ins

When-Operation Plug-ins

Requirements

Designing Plug-ins

Types of Plug-in Operations

Naming Plug-ins

Creating Plug-ins

Plug-in Module Interface Package Specifications

Table 9-1 Plug-in Module Interface

Table 9-2 Operation-Based and Attribute-Based Plug-in Procedure Signatures

Compiling Plug-ins

Dependencies

Recompiling Plug-ins

Granting Permission

Registering Plug-ins

The orclPluginConfig Object Class

Table 9-3 Plug-in Attribute Names and Values

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

Example 1

Example 2

Managing Plug-ins

Modifying Plug-ins

Debugging Plug-ins

Enabling and Disabling Plug-ins

Exception Handling

Error Handling

Program Control Handling between Oracle Internet Directory and Plug-ins

Table 9-4 Program Control Handling when a Plug-in Exception Occurs

Table 9-5 Program Control Handling when an LDAP Operation Fails

Plug-in LDAP API

Plug-in and Replication

Plug-in and DB Tools

Security

Plug-in LDAP API Specifications

Usage Model and Examples

Example 1: Search Query Logging

Example 2: Synchronizing Two DITs

Type Definition & Usage Model

Database Object Type Definitions

Plug-in Module Interface Specifications

LDAP Server Error Code Reference

9
Oracle Internet Directory Server Plug-in Framework