|
Oracle® Identity Management Integration Guide
10g Release 2 (10.1.2) Part No. B14085-01 |
|
 Previous |
 Next |
|
Oracle® Identity Management Integration Guide
10g Release 2 (10.1.2) Part No. B14085-01 |
|
|
Previous |
Next |
This chapter discusses the Oracle directory integration and provisioning server and explains how to configure and manage it. It contains these topics:
Operational Information about the Oracle Directory Integration and Provisioning Server
Viewing Oracle Directory Integration and Provisioning Server Information
Managing Configuration Set Entries Used by the Oracle Directory Integration and Provisioning Server
Managing the SSL Certificates of Oracle Internet Directory and Connected Directories
Starting, Stopping, and Restarting the Oracle Directory Integration and Provisioning Server
Setting the Debug Level for the Oracle Directory Integration and Provisioning Server
Managing Oracle Directory Integration and Provisioning in a Replicated Environment
Manually Registering the Oracle Directory Integration and Provisioning Server
|
See Also: "Oracle Directory Integration and Provisioning Server" for a summary of the functions performed by the Oracle directory integration and provisioning server |
|
Note: For security reasons, Oracle Corporation recommends that you run the Oracle directory integration and provisioning server on the same host as the directory server. If you run them on different hosts, then run them by using SSL as described in the chapter on SSL and the directory in Oracle Internet Directory Administrator's Guide. |
This section introduces structural and operational information about the directory integration and provisioning server and contains these topics:
The Oracle Directory Integration and Provisioning Server and Configuration Set Entries
Standard Sequences of Directory Integration and Provisioning Server Events
In Oracle Directory Integration and Provisioning, you can create two types of profiles: a directory synchronization profile and a directory provisioning profile. A directory synchronization profile describes how synchronization is carried out between Oracle Internet Directory and an external system. You can create two types of directory synchronization profiles: an import profile and an export profile. An import profile imports changes from a connected directory to Oracle Internet Directory while an export profiles exports changes from Oracle Internet Directory to a connected directory. A directory provisioning profile describes the nature of provisioning-related notifications that Oracle Directory Integration and Provisioning sends to the directory-enabled applications. Each type of profiles is special kind of directory integration profile, which is an entry in Oracle Internet Directory that describes how Oracle Directory Integration and Provisioning communicates with external systems and what is communicated.
Each directory integration and provisioning server can execute a set of connectors either for:
Synchronizing between Oracle Internet Directory and connected directories. The set of connectors for synchronization is provided in the configuration set number entered in the command line when starting the Oracle directory integration and provisioning server.
Provisioning users, groups, and realms for Oracle components. The set of profiles for provisioning is provided in the grpID argument in the command line when starting the Oracle directory integration and provisioning server.
If the configuration set number is not specified, then the directory integration and provisioning server starts in the mode for processing provisioning profiles. If the configuration set number is specified, but there are no integration profiles in the directory for the specified configuration set number, then the directory integration and provisioning server waits indefinitely until integration profiles are added to that configuration set. This wait also occurs if integration profiles are configured for the configuration set but disabled.
If the configuration set specified in the command line does not exist in the directory, then the directory integration and provisioning server logs this information in the log file and exits. For provisioning profiles, the same behavior is followed for the grpID attribute, which is passed as an argument in the command line.
Whenever a connector is scheduled to do synchronization or provisioning, the directory integration and provisioning server starts a separate thread. This thread opens an LDAP connection to the directory server to read or write entries from Oracle Internet Directory, and then closes the connection before exiting.
The directory integration and provisioning server executes three types of threads in the process, and these are described in Table 4-1:
Table 4-1 Oracle Directory Integration and Provisioning Server Threads
| Thread | Description |
|---|---|
| Main thread | Daemon thread of the Oracle directory integration and provisioning server. To look for changed profiles and to refresh its cache, it starts up the scheduler and periodically sends refresh signals to it. This thread also looks for the shutdown signal from the OID Monitor (oidmon). This signal causes the thread to shut itself down after it sends a signal to the scheduler to shut down.
|
| Scheduler thread | Scheduler for the connectors for synchronization based on their specified scheduling interval. On receipt of a refresh signal from the main thread, this thread refreshes the synchronization profiles to the latest values. |
| Connector thread | In a synchronization, the thread that invokes the connector executable named in the profile, and maps and filters the attributes. It is spawned by the scheduler at the specified individual scheduling intervals. Once all the changes from the source directory are propagated to the destination directory, this thread exits. |
Each instance of the Oracle directory integration and provisioning server supports either provisioning or synchronization. The directory integration and provisioning server runs as a shared server process while handling the synchronization and provisioning event propagations.
The three threads described in Table 4-1 work together to create these typical process flow sequences:
Main Thread Process Sequence
On startup, the main thread comes up. This daemon thread of the server starts the scheduler. It verifies the registration of the instance in the directory. If the instance is not registered, then it is not started up by OID Monitor. Instead, it registers itself in Oracle Internet Directory with the configuration set number and the instance number details.
The main thread periodically checks for the refresh time and signals the scheduler to refresh. It also periodically checks for the shutdown signal. On receipt of the shutdown signal, it signals the scheduler thread to shutdown.
Once the scheduler thread shuts down, the main thread unregisters and shuts down.
Scheduler Thread Process Sequence
When it is started by the main thread, the scheduler thread reads the configuration set to determine which integration profiles to schedule. It creates a list of profiles to be scheduled and schedules them based on their specified scheduling interval. While creating the list of profiles, it validates the attributes. If any of the profile attributes have invalid values, the profile is not considered for synchronization or provisioning.
When it receives the refresh signal, the scheduler thread refreshes the integration profiles. When it receives the shutdown signal, the scheduler thread waits until all the connectors complete the synchronization or provisioning event propagation. It then returns control to the main thread.
Connector Thread Process Sequence for Synchronization
A synchronization thread follows this process:
Establishes connection with the connected directory and Oracle Internet Directory
In an import operation, executes any agent execution command that may be specified in the connector
Opens the DB/LDAP/LDIF/Tagged file if required
Reads the changes from the source one at a time
Filters the changes if applicable
Maps the changes as specified by the mapping rules
Creates the destination change record
Write the changes to the destination
After applying all the changes, closes the thread
Connector Thread Process Sequence for Provisioning
A provisioning thread follows this process:
Establishes a connection with the connected directory
Reads the changes from the source, one at a time
Filters the changes if applicable
Identifies the change as a specific event—that is:
USER Add/Modify/Delete
GROUP Add/Modify/Delete
Creates the event notification record
Invokes the given package to consume the event notification
In a multimaster Oracle Internet Directory replication environment, changes to directory integration profiles on one Oracle Internet Directory node are not automatically replicated on other Oracle Internet Directory nodes. For this reason, you must observe the considerations that are outlined in this section when implementing Oracle Directory Integration and Provisioning in a multimaster Oracle Internet Directory replication environment.
Because directory synchronization profiles on a primary Oracle Internet Directory node are not automatically replicated to secondary Oracle Internet Directory nodes, you should manually copy the profiles on the primary node to any secondary nodes on a periodic basis. This allows a directory synchronization profile to execute on a secondary node in the event of a problem on the primary node. However, the value assigned to the lastchangenumber attribute in a directory synchronization profile is local to the Oracle Internet Directory node where the profile is located. This means that if you simply copy a directory synchronization profile from one Oracle Internet Directory node to another, the correct state of synchronization or event propagation will not be preserved.
When copying import profiles from one node to another, the lastchangenumber attribute is irrelevant because the value is obtained from the connected directory. However, after copying an export profile to a target node, you must update the lastchangenumber attribute with the value from the target node as follows:
Stop the Oracle directory integration and provisioning server as explained in "Stopping the Oracle Directory Integration and Provisioning Server".
Obtain the value of the lastchangenumber attribute on the target node by following the instructions in "Viewing the Details of a Specific Synchronization Profile".
Copy the directory synchronization profiles from the primary node to the target nodes by following the procedures described in "Moving an Integration Profile to a Different Identity Management Node".
Use the Oracle Directory Integration and Provisioning Server Administration tool or the Directory Integration and Provisioning Assistant (dipassistant) to update the lastchangenumber attribute in the export profile you copied to the target node with the value you obtained in Step 2.
Start the Oracle directory integration and provisioning server as explained in "Starting the Oracle Directory Integration and Provisioning Server".
In a default multimaster Oracle Internet Directory replication environment, the Oracle directory integration and provisioning server is installed in the same location as the primary Oracle Internet Directory. If the primary node fails, event propagation stops for all profiles located on the node. Although the events are queued and not lost while the primary node is stopped, the events will not be propagated to any applications that expect them. In order to ensure that events continue to be propagated even when the primary node is down, you must copy the directory provisioning profiles to other secondary nodes in a multimaster Oracle Internet Directory environment. However, directory provisioning profiles should only be copied from the primary node to any secondary nodes immediately after an application is installed and before any user changes are made in Oracle Internet Directory.
To copy the directory provisioning profiles from a primary node to any secondary nodes, follow the procedures described in "Moving an Integration Profile to a Different Identity Management Node".
When the directory integration and provisioning server starts, it generates specific runtime information and stores it in the directory. This information includes:
The instance number of the directory integration and provisioning server
The host on which it is running
The configuration set with which the directory integration and provisioning server was started
The group identifier of the provisioning profile group it is running
You can view this information by using either the Oracle Directory Integration and Provisioning Server Administration tool or the ldapsearch utility, as described in the following topics:
Viewing Oracle Directory Integration and Provisioning Server Runtime Information by Using ldapsearch
To view runtime information for the directory integration and provisioning server instance by using the Oracle Directory Integration and Provisioning Server Administration tool:
In the navigator pane, expand the directory server instance.
Select Integration Profile Configuration. The Active Processes box appears in the right pane and displays the Oracle directory integration and provisioning server runtime information.
To view registration information for the directory integration and provisioning server instance by using the ldapsearch utility, perform a base search on its entry. For example:
ldapsearch -p 389 -h my_host -b cn=instance1,cn=odisrv,cn=subregistrysubentry -s base -v "objectclass=*"
This example search returns the following:
dn: cn=instance1,cn=odisrv,cn= subregistrysubentry cn: instance1 orclodipconfigdns: orclodipagentname=HRAgent,cn=subscriber profile,cn=changelog subscriber,cn=oracle internet directory orcldiaconfigrefreshflag: 0 orclhostname: my_host orclconfigsetnumber: 1 objectclass: top objectclass: orclODISInstance
You can create, modify, and view configuration set entries by using either the Oracle Directory Integration and Provisioning Server Administration tool or the Directory Integration and Provisioning Assistant. When a connector is registered, an integration profile is created and added to the given configuration set. This configuration set entry determines the behavior of the directory integration and provisioning server.
You can control the runtime behavior of the directory integration and provisioning server by using a different configuration set entry when you start it. For example, you can start instance 1 of the directory integration and provisioning server on host H1 with configset1, and instance 2 on host H1 with configset2. The behavior of instance 1 depends on configset1, and that of instance 2 depends on configset2. Dividing the agents on host H1 between two configuration set entries distributes the load between the two directory integration and provisioning server instances. Similarly, running different configuration sets and different instances on different hosts balances the load between the servers.
The Oracle directory integration and provisioning server can use SSL to connect to Oracle Internet Directory and connected directories. When using SSL with no authentication to connect to Oracle Internet Directory, no certificate is required. However, when connecting to connect to Oracle Internet Directory using SSL with server authentication, you need a trust point certificate to connect to the LDAP server. The Oracle directory integration and provisioning server expects the certificate to be in a wallet, which is a data structure used to store and manage security credentials for an individual entity. Oracle Wallet Manager is an application that wallet owners and security administrators use to manage and edit the security credentials in their wallets.
|
See Also: The chapter on Oracle Wallet Manager in Oracle Advanced Security Administrator's Guide |
The location of the wallet and the password to open it are stored in a properties file used by Directory Integration and Provisioning. This file is $ORACLE_HOME/ldap/odi/conf/odi.properties.
A typical odi.properties file has the entries described in Table 4-2. You must update the odi.properties file with values that are appropriate to your deployment.
Table 4-2 Entries in the odi.properties File
| Entry | Description |
|---|---|
RegWalletFile: odi/conf/srvWallet
|
This entry indicates the location of the registration information of Directory Integration and Provisioning with Oracle Internet Directory. The location of the file is in relation to the $ORACLE_HOME/ldap directory.
|
CertWalletFile: location_of_certificate_wallet
|
Location of the certificate wallet. The certificate wallet file is the location of the ewallet.p12 file.
|
CertWalletPwdFile: location_of_certificate_wallet_password_file
|
Location of the file containing the encrypted wallet password. You must update this password by using the Directory Integration and Provisioning Assistant.
See Also: The chapter on SSL and the directory in Oracle Internet Directory Administrator's Guide "Setting the Wallet Password for the Oracle Directory Integration and Provisioning Server" |
As an example, an odi.properties file can look like this:
RegWalletFile: /private/myhost/orahome/ldap/odi/conf CertWalletFile: /private/myhost/orahome/ldap/dipwallet CertWalletPwdFile: /private/myhost/orahome/ldap/
In the preceding example, the file locations are absolute path names. In this example, the wallet file ewallet.p12 is located in the directory /private/myhost/orahome/ldap/dipwallet.
This section tells you how to start, stop, and restart the Oracle directory integration and provisioning server. It contains these topics:
Starting the Oracle Directory Integration and Provisioning Server
Stopping the Oracle Directory Integration and Provisioning Server
Restarting the Oracle Directory Integration and Provisioning Server
|
Note: When the Oracle directory integration and provisioning server is invoked in the default mode, it supports only the Oracle Provisioning Service, and not the Oracle Directory Synchronization Service. |
Oracle Directory Integration and Provisioning can be installed as a component of Oracle Internet Directory or as a standalone installation. How you start the Oracle directory integration and provisioning server depends on whether you install Oracle Directory Integration and Provisioning as a component of Oracle Internet Directory as a standalone installation. This is explained in "Starting and Stopping an Oracle Directory Server Instance by Using the OID Control Utility".
If you install Oracle Directory Integration and Provisioning as a component of Oracle Internet Directory, an instance of the Oracle directory integration and provisioning server is started that only processes provisioning requests. To start an additional instance of Oracle directory integration and provisioning server that performs synchronization, follow the instructions in "Starting the Oracle Directory Integration and Provisioning Server by Using the OID Monitor and OID Control Utilities". To start a standalone installation of the Oracle directory integration and provisioning server, follow the instructions in "Starting the Oracle Directory Integration and Provisioning Server Without Using the OID Monitor and the OID Control Utility".
The way you stop the directory integration and provisioning server depends on whether you used the OID Monitor and the OID Control Utility to start it. This is explained in "Stopping the Oracle Directory Integration and Provisioning Server".
If you use OID Monitor and the OID Control utility, then you can both stop and restart the directory integration and provisioning server in a single RESTART command. This is useful when you want to refresh the server cache immediately, rather than at the next scheduled time. When the directory integration and provisioning server restarts, it maintains the same parameters it had before it stopped.
The Oracle directory integration and provisioning server can, with certain restrictions, execute in various high availability scenarios. This section discusses the Oracle directory integration and provisioning server as it operates in a Real Application Clusters environment and in an Oracle Application Server Cold Failover Cluster (Infrastructure). It contains these topics
The Oracle Internet Directory infrastructure is configured to work in a Real Application Clusters mode. In a Real Application Cluster, the Oracle directory integration and provisioning server can execute against any directory node.
A particular configuration set can be executed by only one instance of the Oracle directory integration and provisioning server. For this reason, during the default installation only one server instance—namely, instance 1—is started on the Real Application Clusters master node. This server instance executes configuration set 0. Although it is started only on the master node, the server is nevertheless registered on all the nodes.
If the master node fails, then the Oracle directory integration and provisioning server instance is started by the OID Monitor on a secondary node. If there are multiple secondary nodes, then the server is started by the first OID Monitor to recognize the master node failure.
When it starts the server, the OID Monitor uses the same instance number and configuration set that was used on the master node. This is a transparent to the end user, and, once it is done, the Oracle directory integration and provisioning server on the secondary node behaves as if it is the primary server. The server continues executing on the secondary node as long as that node is available.
Two separate instances of the Oracle directory integration and provisioning server running on two nodes cannot simultaneously execute the same configuration set. Although the OID Monitor does not check for this, the Oracle directory integration and provisioning server itself fails to start.
You can stop the Oracle directory integration and provisioning server at any time by using the OID Control utility. However, if you do this, then the server does not start automatically on any other node. To start it on another node, do so manually by using the OID Control utility.
If you execute the command opmnctl stopall, and subsequently execute opmnctl startall, then the Oracle directory integration and provisioning server starts.
In summary, unless an OID Control command stops the Oracle directory integration and provisioning server, OIDMON always ensures that the server is running.
The Oracle Internet Directory infrastructure is configured to work in an Oracle Application Server Cold Failover Cluster (Infrastructure). The Oracle directory integration and provisioning server executes on the active node.
If the active node fails, then the OID Monitor on a standby node starts the Oracle directory integration and provisioning server instance on the standby node. When it does this, it uses the same instance number and configuration set as previously used on the active node. This is a transparent to the end user. The server continues executing on the active node as long as the node is available. In an Oracle Application Server Cold Failover Cluster (Infrastructure), the server is registered once for both the active and standby nodes because the virtual host names are the same for both.
You can stop the Oracle directory integration and provisioning server at any time by using the OID Control utility. However, if you do this, then the server does not start again on this node. Moreover, if this node fails over, then the OID Monitor on the standby node does not start the Oracle directory integration and provisioning server. To start the server, you must use the OID Control utility.
If you execute the command opmnctl stopall, and subsequently execute opmnctl startall, then the Oracle directory integration and provisioning server starts.
In summary, unless an OID Control command stops the Oracle directory integration and provisioning server, OID Monitor always ensures that the server is running.
|
See Also: The chapters on Oracle Application Server Cold Failover Cluster (Infrastructure) in Oracle Internet Directory Administrator's Guide |
You set the debug level by specifying a value for the orclodipdebuglevel attribute in the profile. The value you assign to the orclodipdebuglevel attribute allows you to separately control the trace logging levels for the directory integration and provisioning server and that of each connector.
For server execution, tracing is stored in the $ORACLE_HOME/ldap/log/odisrv_xx.log file, where xx is the number of the started instance. For connectors, tracing is stored in the $ORACLE_HOME/ldap/odi/log/profilename.trc.
|
See Also: Appendix E, "Troubleshooting Oracle Directory Integration and Provisioning" for more information on how trace and log files |
Table 4-3 lists the server debugging levels you can assign to the orclodipdebuglevel attribute. If you specify a nonzero debug level, then each trace statement in the server log file includes these trace-statement types:
Main—Messages from the controller thread
Scheduler—Messages from the scheduler thread
Table 4-3 Server Debugging Levels
| Debug Event Type | Numeric Value |
|---|---|
| Starting and stopping of threads | 1 |
| Refreshing of profiles | 2 |
| Initialization, execution, and end details of connectors | 4 |
| Details during connector execution | 8 |
| Change record of the connector | 16 |
| Mapping details of the connector | 32 |
| Execution time details of the connector | 64 |
|
See Also: Chapter 7, "Administration of Directory Synchronization" for instructions on selectively debugging the threads |
If you do not set a value for the debug flag, then the default level is 0 (zero), and none of the debug events in Table 4-3 are logged. However, errors and exceptions are always logged.
You can set the debugging levels for each connector in the profile itself. Table 4-4 lists the connector debugging levels you can assign to the orclodipdebuglevel attribute.
Table 4-4 Connector Debugging Levels
| Debug Event Type | Numeric Value |
|---|---|
| Initializing and terminating | 1 |
| Searching within the connection | 2 |
| Processing of entries after searching | 4 |
| Creation of change records | 8 |
| Processing details of change records | 16 |
| Mapping details | 32 |
For provisioning and synchronization, the replicated directory is different from the master directory. Any profiles created in the original directory need to be re-created in the new directory, and all configurations must be performed as in the original directory. To
Execution details and debugging information are in the log file located in the $ORACLE_HOME/ldap/log/odisrvInstance_number.log directory.
For example, if the server was started as server instance number 3, then the log file would have this path name: $ORACLE_HOME/ldap/log/odisrv03.log.
Any other exceptions in the server are in the file odisrv_jvm_xxxx.log where xxxx is the identifier of the process running the directory integration and provisioning server in that table.
All the profile-specific debug events are stored in the profile-specific trace file in $ORACLE_HOME/ldap/odi/log/profile_name.trc.
The Oracle directory integration and provisioning server is registered with Oracle Internet Directory during installation of Directory Integration and Provisioning. This registration creates a footprint in the directory indicating the specified host as the one authorized to run Directory Integration and Provisioning.
There may be times when you need to perform this registration manually on the client side, as, for example, if there is a failure during installation. You can do this by using either the Oracle directory integration and provisioning server registration tool (odisrvreg) or Oracle Enterprise Manager 10g Application Server Control Console.
You must separately register each directory integration and provisioning server on each host by running odisrvreg on that host. To run this tool, you need privileges to administer a directory server.
|
See Also:
|
You can use Oracle Enterprise Manager 10g Application Server Control Console to configure Directory Integration and Provisioning in an Oracle Identity Management infrastructure. When you do this, Application Server Control Console registers the Oracle directory integration and provisioning server on that infrastructure.
On the main Application Server Control Console page, select the name of the Oracle Application Server instance you want to manage in the Standalone Instances section. The Oracle Application Server home page opens for the selected instance.
Select the Configure Components button, located just above the System Components table. The Select Component page appears.
|
Note: The Configure Component button is available only if you have installed but not configured any Oracle Application Server components. |
Select Oracle Directory Integration and Provisioning, then select Continue. The Login screen appears.
Enter the user name and password of the directory super user. The default user name is cn=orcladmin.
Select Finish to complete the registration.
