4
Developing Provisioning-Integrated Applications

This chapter explains how to develop applications that can use the Oracle Directory Provisioning Integration Service, a component of the Oracle Directory Integration and Provisioning platform. These applications can be either legacy or third-party applications that are based on the Oracle platform.

This chapter contains these topics:

Introduction to the Oracle Directory Provisioning Integration Service
Provisioning Integration Prerequisites
Development Usage Model for Provisioning Integration
Development Tasks for Provisioning Integration

See Also:
The chapter on the Oracle Directory Provisioning Integration Service in Oracle Internet Directory Administrator's Guide

Introduction to the Oracle Directory Provisioning Integration Service

A big challenge in directory administration is managing provisioning information for the myriad accounts and applications that each user might need. For example, adding a user to an information system typically requires a substantial amount of application provisioning. It can include setting up an e-mail account, which in turn has specific settings for a mail quota, some default folders, and perhaps some distribution lists. If there are other connectivity applications that the user needs, then managing that user's accounts and personal profile can be overwhelming for a large enterprise. To meet this challenge, the Oracle Directory Provisioning Integration Service provides a platform for integrating applications. It enables you to add a user seamlessly to many key systems in just one step.

The Oracle Directory Provisioning Integration Service serves as a passthrough for user account information. Rather than provisioning a user with each individual application, you simply register applications with the provisioning service. This enables them to send provisioning information directly to Oracle Internet Directory and receive information from it. Users can then be provisioned at once for a default set of integrated applications. In this way, the Oracle Directory Provisioning Integration Service eliminates redundant processing for each individual application.

In addition to a default set of provisioning events defined during installation, Oracle Internet Directory can define new events and propagate them appropriately to applications that subscribe to those events. The ability to both send and receive these provisioning events provides for seamless management of user accounts.

Developing Provisioning-Integrated Applications

Applications integrated with the Oracle Directory Provisioning Integration Service can be either legacy or third-party applications based on the Oracle platform. Once it has registered with Oracle Internet Directory, an application can send and receive provisioning information to and from Oracle Internet Directory.

To integrate an application with the directory provisioning integration service, you follow these general steps, each of which is explained more fully later in this chapter:

Register the application in Oracle Internet Directory.
Identify the identity management realm under which events are to be propagated or to be applied.
Determine whether the application needs to receive events, send events, or both.
List out the events that need to be sent or received.
List out attributes of interest that an event should contain.
Assign proper privileges to the application identity in the identity management realm so that the various events can be read from Oracle Internet Directory and propagated to it, and for applying change events to Oracle Internet Directory.
Determine the interface name, interface type, and interface connection information. This is required by the provisioning server to propagate events to the application and consume events from it.
Determine the other provisioning scheduling interval, maximum number of events per schedule, and so on.
Implement the interface specifications inside the application.
Create the provisioning profile in Oracle Internet Directory so that event propagation can start. Create this profile by using the provisioning subscription tool (oidprovtool).

To clearly explain these general steps, we will consider a sample application.

Example of a Provisioning-Integrated Application

This example of a provisioning-integrated application is called Employee Self Service Application (ESSA). In this discussion, the terms "user" and "identity" are used interchangeably.

Requirements of the Employee Self Service Application

This application requires that its entire user base be managed from Oracle Internet Directory. The application administrator creates, modifies, and deletes identities in Oracle Internet Directory. The identity information is propagated to the application as an event, namely, IDENTITY_ADD.

Although the application creates the identity as user data, this is not sufficient to authorize the employee to access the application. The presence of the identity in Oracle Internet Directory only facilitates a global login. The application must discover whether a particular identity is authorized to access the application. This is achieved by subscribing the identity for that application, a task that the application administrator can do. This subscribing triggers another event from Oracle Internet Directory to the application--namely, SUBSCRIPTION_ADD--indicating that the identity has now been subscribed in Oracle Internet Directory to use that application. The application can then query the directory to check whether a particular user is present in the application subscription lists before allowing the user access to the application.

In this example, the events for this application are received from Oracle Internet Directory. The application itself does not any events to the directory. It could, however, also send events to Oracle Internet Directory. To do this, the application identity needs more directory privileges for the various operations that it wants to perform on the directory. This is explained in "Determining Provisioning Mode for the Employee Self Service Application".

The steps are as follows:

A user is added in Oracle Internet Directory through either the Oracle Internet Directory Self-Service Console or some other means such as synchronization from third party sources or through using command-line tools. The user information must be placed in the appropriate identity management realm.
The IDENTITY_ADD event is propagated from Oracle Internet Directory to the application. This assumes that the application subscribed to IDENTITY_ADD event during creation of the provisioning subscription profile.
On receiving the event, the application adds this identity to its database. In this example, however, this does not mean that the user is authorized to access the application. An additional event is required to subscribe the user as an authorized user of that application.
In Oracle Internet Directory, the user is subscribed to the application by using Oracle Delegated Administration Services.
The SUBSCRIPTION_ADD event is propagated from Oracle Internet Directory to the application. This assumes that the application subscribed to the SUBSCRIPTION_ADD event during creation of the provisioning subscription profile.
On receiving this event, the application updates the identity record in its database indicating that this is also an authorized user.

Registering the Employee Self Service Application in Oracle Internet Directory

The application must register itself as an application entity with its own identity entry in Oracle Internet Directory. You can decide which realm to create the application identity in, as long as that realm is a well-known location in the DIT. To create the necessary DIT elements in Oracle Internet Directory, you must follow a template described in this chapter.

The Oracle Context of the identity management realm has a container for the various application footprints. That container is: cn=products,cn=oraclecontext,identity management realm DN.

If the application is meant for only one realm, then Oracle Corporation recommends that you create the application identity DN in this form: orclApplicationName=application name,cn=application type,cn=products,cn=oraclecontext,identity management realm DN. The cn=application type element is called the application container.

If the application is meant for multiple realms, then you can create the application identity in the root Oracle Context, namely, cn=products,cn=oraclecontext.

In this example, the location and the content of the entry are as follows:

dn: \ 
orclApplicationCommonName=ESSA,cn=demoApps,cn=Products,cn=OracleContext,o=ACME,

dc=com
orclapplicationcommonname: ESSA
orclappfullname: Employee Self Service Application
userpassword: welcome123
description: This is an sample application for demonstration.
orclaci: access to entry by group="cn=odisgroup,cn=odi,cn=oracle internet direct
ory" (proxy) 
objectclass: orclApplicationEntity

In this example, the application type or application container is demoApps. The application name is ESSA.

All directory operations must be done on the behalf of the application by the provisioning server. Because the server does not have privileges to send or consume events under the domain, it must process events by impersonating the application identity. This, in turn, requires that the server be given the proxy privilege. In this example, it is assumed that the application identity already has the necessary privileges.

Identifying the Management Context for the Employee Self Service Application

All identity management realms are generally present under the identity management realm base in the root Oracle Context. The application must be provisioned for the appropriate realm--that is, proper privileges must be assigned to this application identity so that it can administer its information under this realm. In this example, let us assume that the appropriate realm is o=ACME,dc=com.

Determining Provisioning Mode for the Employee Self Service Application

You must decide whether the application only receives events or whether it also sends them to Oracle Internet Directory. The mode can be:

INBOUND: from the application to Oracle Internet Directory
OUTBOUND: from Oracle Internet Directory to the application, this is the default
BOTH

The default mode is OUTBOUND.

In this example, because the application is interested in only receiving events from Oracle Internet Directory, we specify the events as OUTBOUND only.

Determining Events for the Employee Self Service Application

During installation, a fixed set of events is predefined. You can define new events at runtime, but they can be propagated in the outbound mode only. The Oracle Directory Provisioning Integration Service can process only a fixed set of predefined events for the inbound mode.

In this example, we do not need to define any new events. The following events in Oracle Internet Directory must be propagated to our sample application:

Identity creation (IDENTITY_ADD)
Identity modification (IDENTITY_MODIFY)
Identity employee deletion (IDENTITY_DELETE)
Identity subscription addition (SUBSCRIPTION_ADD)
Identity subscription modification (SUBSCRIPTION_MODIFY)
Identity subscription deletion (SUBSCRIPTION_DELETE)

Provisioning the Employee Self Service Application for an Identity Management Realm

This is the most important step, and it involves assigning the proper privileges to the application identity in the identity management realm. These privileges enable the application to read and apply the various events from Oracle Internet Directory and to send change events to Oracle Internet Directory. Inbound events, which result in modifying Oracle Internet Directory, require more privileges.

Generally, predefined groups are created when the identity management realm is created. The groups have different privileges as described in this section.

The following template describes all the appropriate ACLs required for an application to send or receive provisioning events.

The application identity must be added to the appropriate group, but this, in turn, depends on the privileges it requires. For example, if an application is interested only in receiving events from Oracle Internet Directory, then it does not need to be added to groups that can create or modify entries in this realm.

The template accepts a few variables. Once the variables are instantiated, the template becomes a proper LDIF file that can be executed against Oracle Internet Directory. You can adjust the variables according to the needs of your deployment.

In this example, the identity management realm is o=ACME,dc=com. The template of the LDIF file looks like this:

# This creates The Application Identity subtree 
#
# The following variables are used :
# (Some of them are OPTIONAL where the values oidprov tool can get  default 

# values if not supplied.)
#
#  %s_IdentityRealm% : Identity Realm DN: 
#                      (MANDATORY: This is the domain in which all the related 
users and groups are present.
#                                  If Default Identity Realm needs to be used 
then in an OID install it can be queried.
#                                  This value is stored in Root Oracle Context 
in OID. This value is stored in 
#                                  'orcldefaultsubscriber' attribute in
#                                  'dn: cn=Common,cn=Products,cn=OracleContext' 
entry.)
#  %s_AppType% : Application Type (e.g EBusiness) 
#                       (MANDATORY : Name of the suite  )
#  %s_AppName% : Application Name (e.g HRMS,Financials,Manufacturing)
#                       (MANDATORY: Name of the Application in the suite.)
#  %s_SvcType% : Service Type (e.g Ebusiness) 
#                       (MANDATORY : Alias for name of suite. 
#                                   This value can be be same as %s_AppType%)
#  %s_SvcName% : Service Name (e.g HRMS,Financials,Manufacturing)
#                       (MANDATORY : Alias for name of Application.
#                                   This value can be same as %s_AppName%)
#  %s_AppURL% : Application URL if any. (set it to 'NULL' if there is nothing.)
#
#  Apart from these variables this LDIF templates would also need the following 
information to load this 
# data to Oracle Internet Directory:
#
#  LDAP_HOST :  OID server hostname
#  LDAP_PORT :  OID server port number
#  BINDDN    :  cn=orcladmin
#  BINDPASSWD:  Password for orcladmin
#
#  After replacing the variables in the template this data can be loaded in OID 
by running the following 
# command:
#  ldapmodify -h %LDAP_HOST% -p %LDAP_PORT% -D %BINDDN% \
#                  -w %BINDPWD% -f <this_template_file_name>
#  
#

# First we create the Application container. This needs to be created just once 
#initially. If this container is 
# existing  b'cos some application was already created using this template, 
#please remove this entry from the template/LDIF file.

dn: cn=%s_AppType%,cn=Products,cn=OracleContext,%s_IdentityRealm%
changetype: add
cn: %s_AppType%
objectclass: orclContainer

#  The application identity needs to created next. This is under the 
Applications container. This object is of # type "orclApplicationEntity"

dn: orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,
 %s_IdentityRealm%
changetype: add
orclapplicationcommonname: %s_AppName%
orclaci: access to entry by group="cn=odisgroup,cn=odi,cn=oracle internet 
directory"  
 (add,browse,delete,proxy)
objectclass: orclApplicationEntity



# The following ACLs are for giving privileges to the application entities for 
adding/modifying/deleting
#  users in the relevant realm.

# All members of the group below are allowed to create users in the relevant 
realm.

dn: cn=OracleDASCreateUser,cn=Groups,cn=OracleContext,%s_IdentityRealm%
changetype: modify
add: uniquemember
uniquemember: orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,
 %s_IdentityRealm%

# All members of the group below are allowed to delete users in the relevant 
realm.

dn: cn=OracleDASDeleteUser,cn=Groups,cn=OracleContext,%s_IdentityRealm%
changetype: modify
add: uniquemember
uniquemember: orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,
 %s_IdentityRealm%

# All members of the group below are allowed to edit users in the relevant 
realm.

dn: cn=OracleDASEditUser,cn=Groups,cn=OracleContext,%s_IdentityRealm%
changetype: modify
add: uniquemember
uniquemember: orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,
 %s_IdentityRealm%

# All members of the group below are allowed to create groups in the relevant 
realm.

dn: cn=OracleDASCreateGroup,cn=Groups,cn=OracleContext,%s_IdentityRealm%
changetype: modify
add: uniquemember
uniquemember: orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,
 %s_IdentityRealm%



# All members of the group below are allowed to delete groups in the relevant 
realm.

dn: cn=OracleDASDeleteGroup,cn=Groups,cn=OracleContext,%s_IdentityRealm%
changetype: modify
add: uniquemember
uniquemember: orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,
 %s_IdentityRealm%

# All members of the group below are allowed to edit groups in the relevant 
realm.

dn: cn=OracleDASEditGroup,cn=Groups,cn=OracleContext,%s_IdentityRealm%
changetype: modify
add: uniquemember
uniquemember: orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,
 %s_IdentityRealm%

# The container is being created to hold the various subscription lists of the 
application 
# for this realm. This container will hold lots of subscription information and 
resides just # under the application identity.

dn: cn=subscriptions,orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,
 cn=OracleContext,%s_IdentityRealm%
changetype: add
cn: subscriptions
objectclass: orclContainer

# The following is the group that will hold administrators DNs for managing 
# subscription lists for this application. The application identity should also 
be in this list and # will be added here.

dn: cn=Subscription_Admins,cn=Subscriptions,orclApplicationCommonName=%s_
AppName%,
 cn=%s_AppType%,cn=products,cn=OracleContext,%s_IdentityRealm%
changetype: add
cn: Subscription_Admins
uniquemember: orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,
 %s_IdentityRealm%
objectclass: groupOfUniqueNames
objectclass: orclACPGroup
objectclass: orclprivilegegroup



# The following is the group that will hold  DNs of users who can just view the 
# subscription lists for this application. The application identity should also 
be in this list and # will be added here.

dn: cn=Subscription_Viewers,cn=Subscriptions,orclApplicationCommonName=%s_
AppName%,
 cn=%s_AppType%,cn=products,cn=OracleContext,%s_IdentityRealm%
changetype: add
cn: Subscription_Viewers
uniquemember: orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,
 %s_IdentityRealm%
objectclass: groupOfUniqueNames
objectclass: orclACPGroup
objectclass: orclprivilegegroup

# The following is just a container for the actual subscription lists.

dn: cn=subscription_data,cn=subscriptions,orclApplicationCommonName=%s_AppName%,
 cn=%s_AppType%,cn=Products,cn=OracleContext,%s_IdentityRealm%
changetype: add
cn: subscription_data
objectclass: orclContainer

# The following is a sample subscription list. We are calling it "cn=ACCOUNTS" 
since it # signifies accounts in the application.

dn: cn=ACCOUNTS,cn=subscription_
data,cn=subscriptions,orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,%s_IdentityRealm%
changetype: add
cn: cn=ACCOUNTS
uniquemember: cn=orcladmin
objectclass: groupOfUniqueNames
objectclass: orclGroup

# The following is a container for the service instance entries in the Root 
Oracle Context. An application 
# publishes itself as a service by creating a service instance  entriy under 
this container.  These service 
# instance entries are created outside any realm and in the root #Oracle 
Context.

dn: cn=%s_SvcType%,cn=Services,cn=OracleContext
changetype: add
cn: %s_SvcType%
objectclass: orclContainer



# The following is a container for the service instance entries in the Root 
Oracle Context for that service 
# type

dn: cn=ServiceInstances,cn=%s_SvcType%,cn=Services,cn=OracleContext
changetype: add
cn: ServiceInstances
objectclass: orclContainer

# The following is a service instance entry. An application publishes itself as 
a service by 
# creating this service instance 

dn: cn=%s_SvcName,cn=ServiceInstances,%,cn=%s_
SvcType%,cn=Services,cn=OracleContext
changetype: add
cn: %s_SvcName%
orclServiceType: %s_SvcType%
presentationAddress: %s_AppURL%
objectclass: orclServiceInstance

# The following is a container for service instance reference entry that resides 
in the relevant realm.

dn: cn=%s_SvcType%,cn=Services,cn=OracleContext,%s_IdentityRealm%
changetype: add
cn: %s_SvcType%
objectclass: orclContainer

# It is a  reference entry which actually points to the actual service instance 
entry as well as to the 
# subscription list container  for the application.

dn: cn=%s_SvcName%,cn=%s_SvcType%,cn=Services,cn=OracleContext,%s_IdentityRealm%
changetype: add
cn: %s_SvcName%
description: Link To the Actual Subscription Location for the Application and 
the actual Service instance.
orclServiceInstanceLocation: cn=%s_SvcName%,cn=%s_
SvcType%,cn=Services,cn=OracleContext
orclServiceSubscriptionLocation: cn=subscription_data,cn=subscriptions,
 orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,cn=OracleContext,
 %s_IdentityRealm%
objectclass: orclServiceInstanceReference


# This LDIF operation gives appropriate privileges to the subscription admin and 
subscription viewers 
# group. The groups have already been created earlier.

dn: cn=subscriptions,orclApplicationCommonName=%s_AppName%,cn=%s_
AppType%,cn=Products,
 cn=OracleContext,%s_IdentityRealm%
changetype: modify
replace: orclaci
orclaci: access to entry by group="cn=Subscription_
Admins,cn=Subscriptions,orclApplicationCommonName=%s_AppName%,
 cn=%s_AppType%,cn=products,cn=OracleContext,%s_IdentityRealm%" 
(browse,add,delete) by  group="cn=Subscription_
Viewers,cn=Subscriptions,orclApplicationCommonName=%s_AppName%,
 cn=%s_AppType%,cn=products,cn=OracleContext,%s_IdentityRealm%" (browse) 
orclaci: access to attr=(*) by group="cn=Subscription_
Admins,cn=Subscriptions,orclApplicationCommonName=%s_AppName%,
 cn=%s_AppType%,cn=products,cn=OracleContext,%s_IdentityRealm%" 
(search,read,write,compare) by  group="cn=Subscription_
Viewers,cn=Subscriptions,orclApplicationCommonName=%s_AppName%,
 cn=%s_AppType%,cn=products,cn=OracleContext,%s_IdentityRealm%" 
(search,read,compare)

Determining Scheduling Parameters for the Employee Self Service Application

The scheduling interval determines how often the provisioning servers send or receive events. The server sends or receives events, and, when it has finished sending or receiving all of them, it sleeps for a period specified in seconds in the scheduling interval. The number of events it can send or receive at one time is dictated by the "Maximum Events per Schedule" parameter.

Let us assume that we need events to be propagated every 2 minutes, and a maximum of 100 events each time.

Determining the Interface Connection Information for the Employee Self Service Application

Use the following to determine the interface connection information:

Interface Type: This is the event propagation medium. Currently, only PL/SQL is supported.
Interface Name: This is the name of the PL/SQL package that the application must implement and that the provisioning server invokes to send and receive events. For our sample application. let us assume ESSA_INTF to be the interface name.
Interface Connection information: This is used by the server to connect to the application database to invoke the PL/SQL interface.

The connection information is in this format:

Database Host: Listener Port: Database SID: DB Account: Password

For a high-availability, RAC-enabled database, the connection information should be in this format:

Database Host: Listener Port: Service Name: DB Account: Password; Database Host: 
Listener Port: Service Name: DB Account: Password; Database Host: Listener Port: 
Service Name: DB Account: Password

The entire string should be specified in one line as a single value.

For our sample application, the connection information is:

localhost: 1521: iasdb : scott : tiger

The Oracle directory integration and provisioning server uses JDBC to connect to the application database using the connect information provided, and then invokes the PLSQL APIs to propagate or receive events.

Implementing the Interface Specification for the Employee Self Service Application

The interface is described in detail in Chapter 11, "Provisioning Integration API Reference".

For outbound events--that is, events from Oracle Internet Directory to the application--the following interfaces must be implemented:

    PROCEDURE PutOIDEvent (event         IN  LDAP_EVENT,
                           event_status  OUT LDAP_EVENT_STATUS);

For inbound events--that is, events from application to Oracle Internet Directory--the following interfaces must be implemented:

    -- FUNCTION GetAppEvent(event OUT LDAP_EVENT)  RETURNING NUMBER;
    -- PROCEDURE PutAppEventStatus(event_status IN LDAP_EVENT_STATUS)

For our sample application, because we are handling only outbound events, we implement all interfaces concerning those events.

Creating the Provisioning Subscription Profile for the Employee Self Service Application

To create the provisioning subscription profile, use the following settings:

$ORACLE_HOME/bin/oidprovtool operation=create ldap_host=localhost \ 

ldap_port=389 ldap_user_dn=cn=orcladmin ldap_user_password=welcome \
organization_dn="o=ACME,dc=com" \
application_dn="orclApplicationCommonName=ESSA,cn=demoApps,cn=Products,\
cn=OracleContext,o=ACME,dc=com" \
interface_name=ESSA_INTF  interface_type=PLSQL \
interface_connect_info="localhost:1521:iasdb:scott:tiger" \
event_subscription="IDENTITY:o=oracle,dc=com:ADD(cn,sn,mail,description,

telephonenumber)" \
event_
subscription="IDENTITY:o=oracle,dc=com:MODIFY(cn,sn,mail,description,telephonenu
mber)" \
event_subscription="IDENTITY:o=oracle,dc=com:DELETE " \
event_subscription="SUBSCRIPTION:cn=ESSA,cn=prducts,cn=oraclecontext,o=oracle,
dc=com:ADD(orclactivestartdate,orclactiveenddate,cn) \
event_
subscription="SUBSCRIPTION:cn=ESSA,cn=prducts,cn=oraclecontext,o=oracle,dc=com:M
ODIFY(orclactivestartdate,orclactiveenddate,cn) \
event_
subscription="SUBSCRIPTION:cn=ESSA,cn=prducts,cn=oraclecontext,o=oracle,dc=com:

DELETE"

Provisioning Integration Prerequisites

Applications used with Oracle Directory Provisioning Integration Service must be Oracle RDBMS-based and enabled for Oracle Application Server Single Sign-On.

As an application developer, you should be familiar with:

General LDAP concepts
Oracle Internet Directory
Oracle Internet Directory integration with Oracle Application Server
Oracle Delegated Administration Services
The user provisioning model as described in the chapter on the Oracle Directory Provisioning Integration Service in the Oracle Internet Directory Administrator's Guide in the Oracle Application Server documentation set.
The Oracle Directory Integration and Provisioning platform
Knowledge of SQL, PL/SQL, and database RPCs

In addition, Oracle Corporation recommends that you understand Oracle Application Server Single Sign-On concepts.

Development Usage Model for Provisioning Integration

This section gives an overview of the usage model for an agent for a provisioning-integrated application. It contains these topics:

Initiating Provisioning Integration

During application installation, the following information is provided to the Oracle Directory 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 Directory Provisioning Integration Service to service the application--for example, the kind of changes required, or scheduling properties. Figure 4-1 shows the first phase of provisioning--namely, passing user events from Oracle Internet Directory through the Oracle Directory Integration and Provisioning platform provisioning filter to the application.

Figure 4-1 How an Application Obtains Provisioning Information by Using the Oracle Directory Provisioning Integration Service

Text description of oiddg013.gif follows

Text description of the illustration oiddg013.gif

In Figure 4-1:

The Oracle Directory Provisioning Integration Service retrieves the changes to user and group information from the Oracle Internet Directory change log. It determines which changes to send to the application.
The Oracle Directory Provisioning Integration Service sends the changes to the application--based on the database connect information--by invoking a generic provisioning interface.
The generic provisioning interface invokes the application-specific logic. 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.

Returning Provisioning Information to the Directory

It is now possible to return provisioning information to the Oracle Internet Directory. Figure 4-2 shows the steps involved in this process, which is essentially the reverse of the provisioning process.

The application repository generates the application event data and sends it to the Oracle Directory Integration and Provisioning platform.
The Oracle Directory Integration and Provisioning platform filters the event data and returns the change information to the directory server.
The change is applied in Oracle Internet Directory.

The updated information is stored in the Oracle Internet Directory, ready to be accessed by other applications.

Figure 4-2 How an Application Returns Provisioning Information to Oracle Internet Directory Provisioning Service

Text description of oiddg014.gif follows

Text description of the illustration oiddg014.gif

Figure 4-3 shows the relationship between the services and the subscribed applications in a provisioning-integrated deployment.

Figure 4-3 Provisioning Services and Their Subscribed Applications in a Typical Deployment

Text description of oiddg017.gif follows

Text description of the illustration oiddg017.gif

Figure 4-3 shows a DIT in which the entries for two services--Oracle Human Resources and Oracle Financials--point to their corresponding subscription list containers.

Oracle Human Resources is represented as
cn=HRMS,cn=EBusiness,cn=Services,dc=com.

It points to its subscription list: cn=Accounts,cn=subscription_data, cn=subscriptions,orclapplicationcommonname=HRMS, cn=EBusiness,cn=Products,cn=OracleContext.
Oracle Financials is represented as cn=Financials,cn=EBusiness,cn=Services,dc=com.

It points to its subscription list: cn=Accounts,cn=subscription_data,cn=subscriptions,orclapplicationcommonname=FINANCIALS, cn=EBusiness,cn=Products,cn=OracleContext.

Development Tasks for Provisioning Integration

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

Develop application-specific logic to perform provisioning activities in response to events from the provisioning system.
Modify application installation procedures to enable the applications to subscribe to provisioning events.

This section contains these topics:

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:

"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 Directory 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 Directory 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 Directory 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 Directory Provisioning Integration Service in turn connects to the application database and invokes the necessary PL/SQL procedures.

Figure 4-3 illustrates the system interactions for the PL/SQL callback interface.

Figure 4-4 PL/SQL Callback Interface

Text description of oiddg012.gif follows

Text description of the illustration oiddg012.gif

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

The administrator deletes the user in Oracle Internet Directory by using Oracle Directory Manager or a similar tool.
The Oracle Directory Provisioning Integration Service retrieves that change from the Oracle Internet Directory change-log interface.
To see if the user deleted from the directory was enrolled for this application, the Oracle Directory Provisioning Integration Service invokes the user_exists() function of the provisioning event interface of the application.
If the user is enrolled, then the Oracle Directory Provisioning Integration Service invokes the user_delete() function of the provisioning event interface.
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.

Extensible Event Definitions

This feature allows you to extend the abilities of the Oracle Directory Provisioning Integration Service to return predefined sets of provisioning information to applications. Configure the following events at installation to propagate them to the appropriate applications.

Table 4-1 Extensible Event Definitions

Event Definition	Attribute
Event Object Type (`orclODIPProvEventObjectType`)	Specifies the type of object the event is associated with--for example, `USER`, `GROUP`, or `IDENTITY`.
LDAP Change Type (`orclODIPProvEventChangeType`)	Indicates what kinds of LDAP operations can generate an event for this type of object--for example, `ADD`, `MODIFY`, or `DELETE`)
Event Criteria (`orclODIPProvEventCriteria`)	The additional selection criteria that qualifies an LDAP entry to be of a specific object type. For example, `Objectclass=orclUserV2` means that any LDAP entry that satisfies this criteria can be qualified as this object type, and any change to this entry can generate appropriate event(s).

Application Deinstallation

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

LDAP_NTFY Function Definitions

FUNCTION user_exists

A callback function invoked by the Oracle Directory Provisioning Integration Service to 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 4-2 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 Directory 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 4-3 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 does not exist.

FUNCTION event_ntfy

A callback function invoked by the Oracle Directory 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 4-4 Parameters for FUNCTION event_ntfy

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

Success returns a positive number. Failure returns zero.

4 Developing Provisioning-Integrated Applications

Introduction to the Oracle Directory Provisioning Integration Service

Developing Provisioning-Integrated Applications

Example of a Provisioning-Integrated Application

Requirements of the Employee Self Service Application

Registering the Employee Self Service Application in Oracle Internet Directory

Identifying the Management Context for the Employee Self Service Application

Determining Provisioning Mode for the Employee Self Service Application

Determining Events for the Employee Self Service Application

Provisioning the Employee Self Service Application for an Identity Management Realm

Determining Scheduling Parameters for the Employee Self Service Application

Determining the Interface Connection Information for the Employee Self Service Application

Implementing the Interface Specification for the Employee Self Service Application

Creating the Provisioning Subscription Profile for the Employee Self Service Application

Provisioning Integration Prerequisites

Development Usage Model for Provisioning Integration

Initiating Provisioning Integration

Figure 4-1 How an Application Obtains Provisioning Information by Using the Oracle Directory Provisioning Integration Service

Returning Provisioning Information to the Directory

Figure 4-2 How an Application Returns Provisioning Information to Oracle Internet Directory Provisioning Service

Figure 4-3 Provisioning Services and Their Subscribed Applications in a Typical Deployment

Development Tasks for Provisioning Integration

Application Installation

User Creation and Enrollment

User Deletion

Figure 4-4 PL/SQL Callback Interface

Extensible Event Definitions

Table 4-1 Extensible Event Definitions

Application Deinstallation

LDAP_NTFY Function Definitions

FUNCTION user_exists

Syntax

Parameters

Table 4-2 Function user_exists Parameters

Return Value

FUNCTION group_exists

Syntax

Parameters

Table 4-3 Function group_exists Parameters

Return value

FUNCTION event_ntfy

Syntax

Parameters

Table 4-4 Parameters for FUNCTION event_ntfy

Return Values

4
Developing Provisioning-Integrated Applications