8
Developing Provisioning-Integrated Applications

This chapter explains how to develop applications that leverage services provided by the Oracle Provisioning Integration Service in the Oracle Directory Integration platform.

These applications can be either legacy or third-party applications that are based on the Oracle platform.

This chapter contains these topics:

• Prerequisite Knowledge

• Development Usage Model for Provisioning Integration

• Development Tasks for Provisioning Integration

• Provisioning Event Interface Description

Prerequisite Knowledge

You should be familiar with:

• Generic LDAP concepts

• Oracle Internet Directory

• Oracle Internet Directory integration with Oracle9i Application Server

• The Delegated Administration Service

• The user provisioning model as described in the chapter on the Oracle Provisioning Integration Service in the Oracle Internet Directory Administrator's Guide in the Oracle9i Application Server documentation set.

• The Oracle Directory Integration platform

• Knowledge of SQL, PL/SQL, and database RPCs

In addition, Oracle Corporation recommends that you understand Oracle9iAS Single Sign-On.

Development Usage Model for Provisioning Integration

This section gives an overview of the usage model for an agent for a provisioning-integrated application.

Figure 8-1 shows the lifecycle of the application that obtains provisioning events.

Figure 8-1 How an Application Obtains Provisioning Information by Using the Oracle Directory Synchronized Provisioning Platform

Text description of the illustration provisn2.gif

1. During application installation, the following information is provided to the Oracle Provisioning Integration Service:
   • Information to register the application entry in Oracle Internet Directory

   • Information to register the application-specific database connect information with Oracle Internet Directory

   • Information for the Oracle Provisioning Integration Service to service the application--for example, the kind of changes required, or scheduling properties

2. The Oracle Provisioning Integration Service retrieves from the Oracle Internet Directory change log the changes to user and group information. It determines which changes to send to the application.

3. The Oracle Provisioning Integration Service sends the changes to the application--based on the database connect information--by invoking a generic provisioning interface.

4. The generic provisioning interface invokes the application-specific logic.

5. The application-specific logic translates the generic provisioning event to one that is application-specific. It then makes the necessary changes in the application repository.

6. The administrator can either deinstall the application manually, or by using the automatic deinstallation process. During manual deinstallation of the application, the administrator uses the Provisioning Subscription tool to unsubscribe the application from the provisioning platform. The Provisioning Subscription tool is invoked from any ORACLE_HOME and is called oidprovtool.

Development Tasks for Provisioning Integration

To develop applications for synchronized provisioning, you perform these general tasks:

1. Develop application-specific logic to perform provisioning activities in response to events from the provisioning system.

2. Modify application installation procedures to enable the applications to subscribe to provisioning events.

This section contains these topics:

• Application Installation

• User Creation and Enrollment

• User Deletion

• Application Deinstallation

Application Installation

Modify the installation logic for each application to run a post-installation configuration tool.

During application installation, the application invokes the Provisioning Subscription tool, oidProvTool. The general pattern of invoking this tool is:

oidprovtool param1=<p1_value> param2=<p2_value> param3=<p3_value> ...

See Also: "Provisioning Subscription Tool Syntax" for a description of the tool's parameters and the values they can take on "Development Usage Model for Provisioning Integration" for details of what the post-installation tool should do

User Creation and Enrollment

First, create users in Oracle Internet Directory. Then enroll them in the application.

When using either of these interfaces, you must enable the Oracle Provisioning Integration Service to identify users presently enrolled in the application. This way, the delete events it sends correspond only to users enrolled in the application.

Implement the application logic so that the user_exists function verifies that a given user in Oracle Internet Directory is enrolled in the application.

User Deletion

The Oracle Provisioning Integration Service primarily propagates the user deletion events from Oracle Internet Directory to the various provisioning-integrated applications.

With the PL/SQL callback interface, then the application registers with the Oracle Provisioning Integration Service and provides:

• The name of a PL/SQL package the application is using

• The connect string to access that package

The Oracle Provisioning Integration Service in turn connects to the application database and invokes the necessary PL/SQL procedures.

Figure 8-2 illustrates the system interactions for the PL/SQL callback interface.

Figure 8-2 User Deletion Using a PL/SQL Callback-Based Approach

Text description of the illustration provisna.gif

As Figure 8-2 shows, the deletion of a user from an application comprises these steps:

1. The administrator deletes the user in Oracle Internet Directory by using Oracle Directory Manager or a similar tool.

2. The Oracle Provisioning Integration Service retrieves that change from the Oracle Internet Directory change-log interface.

3. To see if the user deleted from the directory was enrolled for this application, the Oracle Provisioning Integration Service invokes the user_exists() function of the provisioning event interface of the application.

4. If the user is enrolled, then the Oracle Provisioning Integration Service invokes the user_delete() function of the provisioning event interface.

5. The application-specific PL/SQL logic deletes the user and the related footprint from the application-specific repository.

Step 5 is the responsibility of the provisioning-integrated application developer.

Application Deinstallation

You must enable the de-installation logic for each provisioning-integrated application to run the Provisioning Subscription tool (oidprovtool) that unsubscribes the application from the Oracle Provisioning Integration Service.

Provisioning Event Interface Description

As stated in "Development Tasks for Provisioning Integration", you must develop logic to consume events generated by the Oracle Provisioning Integration Service. The interface between the application and the Oracle Provisioning Integration Service can be either table-based or use PL/SQL callbacks.

See Also: "Development Usage Model for Provisioning Integration" for information about how to use these interfaces

The PL/SQL callback interface requires you to develop a PL/SQL package that Oracle Provisioning Integration Service invokes in the application-specific database. Choose any name for the package, but be sure to use the same name when you register the package at subscription time. Implement the package by the following PL/SQL package specification:

Rem
Rem      NAME
Rem         ldap_ntfy.pks - Provisioning Notification Package Specification.
Rem

DROP TYPE LDAP_ATTR_LIST;
DROP TYPE LDAP_ATTR;

-- LDAP ATTR
----------------------------------------------------------------
--
--  Name        : LDAP_ATTR
--  Data Type   : OBJECT
--  DESCRIPTION : This structure contains details regarding 
--                an attribute. 
--
----------------------------------------------------------------
CREATE TYPE LDAP_ATTR AS OBJECT (                                
     attr_name        VARCHAR2(255),
     attr_value       VARCHAR2(2048),
     attr_bvalue      RAW(2048),
     attr_value_len   INTEGER,
     attr_type        INTEGER  -- (0 - String, 1 - Binary)
     attr_mod_op      INTEGER
);
/
 GRANT EXECUTE ON LDAP_ATTR to public;

-------------------------------------------------------------
--
--  Name        : LDAP_ATTR_LIST
--  Data Type   : COLLECTION
--  DESCRIPTION : This structure contains collection 
--                of attributes.
--
-------------------------------------------------------------
CREATE TYPE LDAP_ATTR_LIST AS TABLE OF LDAP_ATTR;
/
 GRANT EXECUTE ON LDAP_ATTR_LIST to public;

-------------------------------------------------------------------------------
--
--  NAME        : LDAP_NTFY
--  DESCRIPTION : This a notifier interface implemented by Provisioning System
--               clients to receive information about changes in OID.
--               The name of package can be customized as needed. 
--               The functions names within this package SHOULD NOT be changed.
--
--
-------------------------------------------------------------------------------
CREATE OR REPLACE PACKAGE LDAP_NTFY AS

    --
    -- LDAP_NTFY data type definitions
    --

    
    -- Event Types
    USER_DELETE               CONSTANT VARCHAR2(256) := 'USER_DELETE';
    USER_MODIFY               CONSTANT VARCHAR2(256) := 'USER_MODIFY';
    GROUP_DELETE              CONSTANT VARCHAR2(256) := 'GROUP_DELETE';
    GROUP_MODIFY              CONSTANT VARCHAR2(256) := 'GROUP_MODIFY';

    -- Return Codes (Boolean)
    SUCCESS                   CONSTANT NUMBER  := 1;
    FAILURE                   CONSTANT NUMBER  := 0;

    -- Values for attr_mod_op in LDAP_ATTR object.
    MOD_ADD                   CONSTANT NUMBER  := 0;
    MOD_DELETE                CONSTANT NUMBER  := 1;
    MOD_REPLACE               CONSTANT NUMBER  := 2;

LDAP_NTFY Function Definitions

FUNCTION user_exists

A callback function invoked by the Oracle Provisioning Integration Service yo check if a user is enrolled with the application

Syntax

FUNCTION user_exists ( user_name    IN VARCHAR2,

 user_guid    IN VARCHAR2,
 user_dn      IN VARCHAR2)

Parameters

Table 8-1 Function user_exists Parameters

Parameter	Description
user_name_	User identifier
user_guid	Global user identifier
user_dn	DN attribute of the user entry

Return Value

Returns a (any) positive number if the user exists

FUNCTION group_exists

A callback function invoked by the Oracle Provisioning Integration Service to check whether a group exists in the application.

Syntax

FUNCTION group_exists ( group_name IN VARCHAR2,

group_guid IN VARCHAR2,
group_dn   IN VARCHAR2)
RETURN NUMBER;

Parameters

Table 8-2 Function group_exists Parameters

Parameter	Description
group_name	Group simple name
group_guid	GUID of the group
group_dn	DN of the group entry

Return Value

Returns a positive number if the group exists. Returns zero if the group doesn't exists

FUNCTION event_ntfy

A callback function invoked by the Oracle Provisioning Integration Service to deliver change notification events for objects modeled in Oracle Internet Directory. Currently modify and delete change notification events are delivered for users and groups in Oracle Internet Directory. While delivering events for an object (represented in Oracle Internet Directory),the related attributes are also sent along with other details. The attributes are delivered as a collection (array) of attribute containers, which are in un-normalized form--that is, if an attribute has two values then two rows would be sent in the collection.

Syntax

FUNCTION event_ntfy ( event_type  IN VARCHAR2,

event_id    IN VARCHAR2,
event_src   IN VARCHAR2,
event_time  IN VARCHAR2,
object_name IN VARCHAR2,
object_guid IN VARCHAR2,
object_dn   IN VARCHAR2,
profile_id  IN VARCHAR2,
attr_list   IN LDAP_ATTR_LIST )
RETURN NUMBER;

Parameters

Table 8-3 Function event_ntfy Parameters

Parameter	Description
event_type	Type of event. Possible values: USER_DELETE, USER_MODIFY, GROUP_DELETE, GROUP_MODIFY'
event_id	Event id (change log number)
event_src	DN of the modifier responsible for this event
event_time	Time when this event occurred
object_name	Simple name of the entry.
object_guid	GUID of the entry.
object_dn	DN of the entry
profile_id	Name of the Provisioning Agent
attr_list	Collection of ldap attributes of the entry

Return Values

On success returns a positive number. On failure returns zero.