29
The Oracle Directory Provisioning Integration Service

The Oracle Directory Provisioning Integration Service enables applications to receive provisioning information from Oracle Internet Directory.

This chapter contains these topics:

• About the Oracle Directory Provisioning Integration Service
• Managing the Oracle Directory Provisioning Integration Service Environment
• Security and the Oracle Directory Provisioning Integration Service
• Troubleshooting the Oracle Directory Provisioning Integration Service

  See Also: The chapter on developing provisioning-integrated applications in Oracle Internet Directory Application Developer's Guide

About the Oracle Directory Provisioning Integration Service

This section describes how the components of an Oracle Directory Provisioning Integration Service environment interact throughout the provisioning process. It contains these topics:

• About Provisioning
• How the Oracle Directory Provisioning Integration Service Retrieves Changes from Oracle Internet Directory
• How an Application Obtains Provisioning Information by Using the Oracle Directory Provisioning Integration Service

About Provisioning

Provisioning is the process of notifying an application whenever user or group data changes in Oracle Internet Directory. Provisioning events arise whenever any change occurs to a relevant user's or group's status or information. An application subscribes to provisioning when it is first installed by creating a provisioning profile in the directory. Subscription occurs once for each application.

Provisioning involves--but is not the same as--synchronization. At times, you may want to synchronize all entities in an application-specific directory with those in the central directory, but provision the application to receive notification only about some of them. For example, the directory for Oracle Human Resources typically contains data for all employees in an enterprise, and you would probably want to synchronize all of that data with the central directory. However, you might want to provision your application to receive notification only when members join or leave a particular group.

Provisioning Procedures

In a directory-enabled environment, provisioning involves:

1. Creating the user in the central directory
2. Enrolling the user in the application--that is, creating application-specific user accounts and entitlements
3. Synchronizing those accounts and entitlements with the central directory

For example, provisioning a user to access an e-mail application involves:

1. Creating the user in the central directory
2. Enrolling the user in the e-mail application. This involves setting up an e-mail account and quota for that user and creating the necessary public folders.
3. Synchronizing the user information in the e-mail application with that in the central directory

You can change user and group information from any of the following:

• Oracle Human Resources or other applications integrated with the Oracle Directory Integration Platform
• Oracle Directory Manager
• Oracle Enterprise Manager tools--for example, Enterprise Security Manager

User Enrollment in Applications

User enrollment in an application can happen either automatically or manually.

Automatic Enrollment

An example of this is sometimes called "on-demand enrollment." Instead of continuously synchronizing with the central directory, the application creates the user footprint when the user first accesses the application. Oracle9iAS Single Sign-On enrolls a user accessing an application in this way.

Manual Enrollment

The administrator provides application-specific information by using an application-specific administrative tool.

For example, you might want users to obtain their manager's approval before enrollment. In this case, rather than use on-demand enrollment, you might want the application administrator to enroll the user manually after the necessary approvals are complete.

Provisioning Information

Provisioning a user typically involves creating two kinds of information:

• Shared user metadata in Oracle Internet Directory

  This data includes the user's identity, credentials, profiles, and preferences. It is represented by standard directory user attributes--for example, mailing address or language preferences.

• Application-specific user data in the application

  This could include, for example, data in the user's e-mail message folder, or, for the calendaring application, the user's appointment data. It is typically represented by using application-specific conventions either in the directory or in application-specific repositories.

How the Oracle Directory Provisioning Integration Service Retrieves Changes from Oracle Internet Directory

In an Oracle Directory Provisioning Integration Service environment:

• Oracle Internet Directory acts as the central repository for all user and group information
• Applications subscribe to receive the provisioning events by creating provisioning profiles in the directory
• The Oracle Directory Provisioning Integration Service monitors Oracle Internet Directory for any changes to user or group information, and conveys these changes to applications in the form of provisioning events

To retrieve changes from Oracle Internet Directory, the Oracle Directory Provisioning Integration Service subscribes to the Oracle Internet Directory change log. The changes in the change log are filtered so that only the needed changes get passed to the applications. For example, if an application is interested only in the events of a particular subtree, then the Oracle Directory Provisioning Integration Service notifies it of those changes only.

Figure 29-1 shows the relation between components in an Oracle Directory Provisioning Integration Service environment.

Figure 29-1 Typical Deployment of The Oracle Directory Provisioning Integration Service Environment

Text description of the illustration oidag073.gif

As Figure 29-1 shows:

• Oracle Internet Directory acts as the central repository for all user and group information
• Various components can add, modify, or delete user and group entries in Oracle Internet Directory. These components are:
  • Oracle Directory Integration Platform synchronizing with, for example, Oracle Human Resources or other repositories
  • The Delegated Administration Service
  • Oracle Directory Manager
  • Oracle Enterprise Manager tools--for example, the Enterprise Security Manager

  The Oracle Internet Directory change log records these changes.

• The Oracle Directory Provisioning Integration Service retrieves changes to user and group information from Oracle Internet Directory and sends them to subscribed applications. In this example, the applications are Oracle9iAS Portal, Oracle Unified Messaging, Oracle Internet File System, and third-party enrollees.

How an Application Obtains Provisioning Information by Using the Oracle Directory Provisioning Integration Service

The Oracle Directory Provisioning Integration Service monitors Oracle Internet Directory for any changes to user or group information. It conveys these changes to applications in the form of provisioning events.

Figure 29-2 shows the life cycle of an application that obtains the provisioning events.

Figure 29-2 How an Application Obtains Provisioning Information by Using the Oracle Directory Provisioning Integration Service

Text description of the illustration oidag074.gif

1. Subscription to the Oracle Directory Provisioning Integration Service occurs in one of two ways:
   • The application subscribes itself automatically during application installation by using the Provisioning Subscription Tool
   • The administrator manually subscribes it by using the Provisioning Subscription Tool.

   The Provisioning Subscription Tool, oidprovtool, is invoked from any ORACLE_HOME/bin.The general pattern of invoking this tool is:

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

   See Also: Appendix A, "Syntax for LDIF and Command-Line Tools" for the Provisioning Subscription Tool parameters and the values they can take on

2. This tool, in turn, requests information that the application needs to subscribe to the Oracle Directory Provisioning Integration Service, including:
   • The host name and port number of the Oracle directory server instance
   • The user name and password of the Oracle Internet Directory user
   • Information to register the application with Oracle Internet Directory
   • Information to register the 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

   Once the necessary configuration information is in Oracle Internet Directory, the Oracle Directory Provisioning Integration Service periodically sends the changes to the application. The changes it sends are based on application-specific database connect information.

3. De-installation from Oracle Directory Provisioning Integration Service occurs in one of two ways:
   • The application de-installs itself automatically
   • The administrator manually unsubscribes it by using the Provisioning Subscription Tool

Managing the Oracle Directory Provisioning Integration Service Environment

This section contains these topics:

• Overview: Deploying the Oracle Directory Provisioning Integration Service
• Managing the Oracle Directory Provisioning Integration Service

Overview: Deploying the Oracle Directory Provisioning Integration Service

To deploy the Oracle Directory Provisioning Integration Service, you perform these general steps:

1. Install Oracle Internet Directory--which includes the Oracle Directory Integration Platform--and load user information into it.
2. Install the applications and, when the Provisioning Subscription Tool prompts, supply the information that the applications need to subscribe to the Oracle Directory Provisioning Integration Service. This enables them to receive provisioning events.
3. Periodically monitor the status of the provisioning event propagation for each application.

Managing the Oracle Directory Provisioning Integration Service

This section describes:

• How to manage the Oracle directory integration server
• How to manage provisioning profiles

Managing the Oracle Directory Integration Server

The Oracle directory integration server runs the Oracle Directory Provisioning Integration Service to propagate provisioning events to subscribed applications.

Managing Provisioning Profiles

Use the Provisioning Subscription Tool to perform these activities:

• Create a new provisioning profile. A new provisioning profile is created and set to the enabled state so that the Oracle Directory Integration Platform can process it
• Disable an existing provisioning profile
• Enabled a disabled provisioning profile
• Delete an existing provisioning profile
• Get the current status of a given provisioning profile
• Clear all of the errors in an existing provisioning profile

Use the OID Server Manageability functionality in the Oracle Enterprise Manager to monitor provisioning profiles.

Security and the Oracle Directory Provisioning Integration Service

This section describes the principal entities involved in the provisioning integration process and the directory privileges that they need to complete various operations. It contains these topics:

• The Need to Control Access to Provisioning Profiles
• Entities Needing Access
• Entry-Level Privileges Granted to Entities
• Attribute Level Privileges Granted to Entities

The Need to Control Access to Provisioning Profiles

There are important reasons to control access to the provisioning profiles of applications:

• These profiles contain confidential information about the application--information that should not be viewable by unauthorized directory entities
• Providing provisioning events to applications consumes system resources. The number of those who can provision applications should be limited.

Entities Needing Access

The access that you grant to entities to operate on profiles depends on the delegation needs of the applications. Entities that need controlled access to the provisioning profiles are:

• The Oracle directory integration server group--that is, cn=odisgroup,cn=odi,cn=oracle internet directory
• Provisioning administrators--that is, cn=Provisioning Admins, cn=Provisioning Profiles...
• Application Entities--that is, users for whom the value of the orclGUID attribute is orclODIPProvisioningAppGUID)
• Provisioning profiles--that is, users identified by the DN of the provisioning profiles
• All other users

Applications do not automatically have the rights to create provisioning profiles. Rather, only an LDAP identity with privileges to administer provisioning profiles can create them.

Provisioning administrators are modeled as a group and can perform any operation on the provisioning profiles. All other identities have lesser privileges.

Entry-Level Privileges Granted to Entities

Table 29-1 shows the entry-level privileges granted to each entity.

Table 29-1  Entry-Level Privileges

User Category	Browse	Add	Delete	Explanation
Oracle directory integration server	Yes	No	Yes	Oracle directory integration servers need to: Browse all provisioning profiles Delete some rogue provisioning profiles that the applications did not bother to delete However, Oracle directory integration servers should not have access to add new provisioning profiles.
Provisioning administrators	Yes	Yes	Yes	The provisioning administrators group requires all privileges.
Application entities	Yes	No	Yes	Application entities themselves cannot create provisioning profiles, nor can they view another application's profiles. However, once a profile has been created, they can browse, modify, and delete their own profiles.
Provisioning profiles	Yes	No	No	Provisioning profiles also have an identity in the directory. For Release 9.2, this identity is not used, and hence it has the privilege only to perform a self-browse.
All other users	No	No	No	All other users should not be able to either browse, add, or delete provisioning profiles.

Attribute Level Privileges Granted to Entities

Provisioning profiles contain security-sensitive attributes that need protection from unauthorized access. Table 29-2 describes them.

Table 29-2   Attribute Level Privileges Granted to Entities

Attribute	Description
userpassword	Stores the directory user password
orclPasswordAttribute	Stores the clear text version of the directory user password
orclODIPProfileInterfaceConnectInformation	Stores details of the connection information to the target application, including the password to the target system
orclODIPProfileInterfaceAdditionalInformation	Stores any interface-specific information

Table 29-3 describes the access control for the secure attributes for the main entities operating on the provisioning profiles.

Table 29-3  Access Control for Secure Attributes

User Category	Read	Write	Search	Compare	Explanation
Oracle directory integration servers	Yes	No	Yes	Yes	Oracle directory integration servers need access to the secure attributes to complete their processing cycles. However, they do not need write access to them because these attributes should only be controlled by the Application Entities as well as Provisioning Admins.
Provisioning administrators	Yes	Yes	Yes	Yes	Provisioning administrators must be able to solve integration problems, and this requires full access to the secure attributes.
Application entities	Yes	Yes	Yes	Yes	Application entities are the real owners of the secure attributes, and this requires full access to the secure attributes.
Provisioning profiles	Yes	No	Yes	No	Provisioning profiles do not need to write or compare these attributes. As a result, they need only read and search privileges.
All other users	No	No	No	No	All other users receive no privileges.

Table 29-4 shows the access control for all other attributes in the provisioning profiles.

Table 29-4  Access Control for All other Attributes

User Category	Read	Write	Search	Compare
Oracle directory integration servers	Yes	Yes	Yes	Yes
Provisioning administrators	Yes	Yes	Yes	Yes
Application entities	Yes	Yes	Yes	Yes
Provisioning profiles	Yes	Yes	Yes	Yes
All other users	No	No	No	No

Unlike secure attributes, the other attributes require a less strict access control. Full access is given to all entities involved in the provisioning process: Oracle directory integration servers, provisioning administrators, application entities, and provisioning profiles. All other users receive no access to these attributes.

Troubleshooting the Oracle Directory Provisioning Integration Service

This section lists and describes the provisioning error messages you may see, and discusses actions to resolve them. These messages appear in the provisioning error messages attribute.

Table 29-5  Provisioning Error Messages

Message	Reason	Remedial Action
LDAP Connection Failure	The Oracle Directory Integration Platform failed to connect to the directory server.	Check the connection to the directory server. See Also: "Viewing Active Server Instance Information" to get information about directory server connections
LDAP Authentication Failure	The provisioning profile is not able to connect to the LDAP Server as administrator	Verify Oracle directory integration server entry in the directory. Re-register the Oracle directory integration server by using odisrvreg. See Also: "Registering the Oracle Directory Integration Server"
Initialization Failure	Problem in connecting to the directory server using JNDI.	Look at the trace file for stack trace in $ORACLE_HOME/ldap/odi/log/PROFILE_NAME.trc
Database Connection Failure	Problem connecting to the database with the given account information. Either the database is not running or there is an authentication problem.	Look at the trace file for stack trace in $ORACLE_HOME/ldap/odi/log/PROFILE_NAME.trc
Exception while calling SQL Operation	Problem in executing the package.	Verify the package usability.