4 Developing Provisioning-Integrated Applications

4.2.1.1 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 send 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:

1. 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 command-line tools. The user information must be placed in the appropriate identity management realm.

2. The IDENTITY_ADD event is propagated from Oracle Internet Directory to the application. This assumes that the application subscribed to the IDENTITY_ADD event during creation of the provisioning subscription profile.

3. 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.

4. In Oracle Internet Directory, the user is subscribed to the application by using Oracle Delegated Administration Services.

5. 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.

6. On receiving this event, the application updates the identity record in its database indicating that this is also an authorized user.

4.2.1.2 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, 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.

4.2.1.3 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.

4.2.1.4 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 one of the following:

• INBOUND: from the application to Oracle Internet Directory

• OUTBOUND: from Oracle Internet Directory to the application

• 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.

4.2.1.5 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)

4.2.1.6 Provisioning the Employee Self Service Application for an Identity Management Realm

This is the most important step. 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, 
# it can be queried in a directory install.                                  
# This value is stored in the root Oracle Context of the directory.
# The value  is  stored  in the 'orcldefaultsubscriber'                                 
# attribute in 'dn: cn=Common,cn=Products,cn=OracleContext')
#  %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 :  directory server hostname
#  LDAP_PORT :  directory server port number
#  BINDDN    :  cn=orcladmin
#  BINDPASSWD:  Password for orcladmin
#
# After replacing the variables in the template this data can be loaded into the 
# directory 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  because 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 represented by this DN 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 represented by this DN 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 represented by this DN 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 represented by this DN 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 represented by this DN 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 represented by this DN 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 entry 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.

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)

4.2.1.7 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 two minutes, and a maximum of 100 events each time.

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 PL/SQL APIs to propagate or receive events.

4.2.1.8 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 that ESSA_INTF is 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 following types of Database connection formats are supported:

• Database Host: Listener Port: Database SID: DB Account: Password. This is the old format, which is still supported. Nevertheless, do not use it because SID support might soon be obsolete. In this case, the provisioning server uses JDBC thin driver to connect. For example:

  localhost: 1521: iasdb: scott: tiger
  
  

• Database Host: Listener Port: DB Service Name: DB Account: Password. This is recommended. In this case, the provisioning server uses JDBC thin driver to connect. For example:

  localhost: 1521: iasdb: scott: tiger
  

• For a database configured for active failover clusters, the connection information should be in one of the following two formats:

  DBSVC=netServiceName:User:Password
  
  

  In this case, the provisioning server uses JDBC OCI (thick) driver to connect. The net service name needs to be defined in the local tnsnames.ora file on which the provisioning server is running.

  DBURL=ldap://ldap_host:ldap_port/DBServiceName:UserName:Password
  
  

  In this case, the provisioning server uses JDBC thin driver to connect. Database Registration should already have occurred in the directory. the driver connects to the directory using the directory host and port. It retrieves the database connect information and then connects to the database.

4.2.1.9 Implementing the Interface Specification for the Employee Self Service Application

The interface is described in detail in Chapter 13, "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.

4.2.1.10 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,
telephonenumber)" \
event_subscription="IDENTITY:o=oracle,dc=com:DELETE" \
event_subscription="SUBSCRIPTION:cn=ESSA,cn=products,cn=oraclecontext,o=oracle,
dc=com:ADD(orclactivestartdate,orclactiveenddate,cn) \
event_subscription="SUBSCRIPTION:cn=ESSA,cn=prducts,cn=oraclecontext,o=oracle,
dc=com:MODIFY(orclactivestartdate,orclactiveenddate,cn) \
event_subscription="SUBSCRIPTION:cn=ESSA,cn=prducts,cn=oraclecontext,o=oracle,
dc=com:DELETE"

4.5.6.1 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

user_name

user_guid

user_dn

Return Value

Returns a positive number if the user exists

4.5.6.2 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

group_name

group_guid

group_dn

Return value

Returns a positive number if the group exists. Returns zero if the group does not exist.