Oracle® Identity Management Integration Guide 10g (10.1.4.0.1) Part Number B15995-01 |
|
|
View PDF |
This chapter discusses the Oracle directory integration server and explains how to configure and manage it. It contains these topics:
Operational Information About the Oracle Directory Integration Platform
Managing Configuration Set Entries Used by the Oracle Directory Integration Platform
Managing the SSL Certificates of Oracle Internet Directory and Connected Directories
Starting, Stopping, and Restarting the Oracle Directory Integration Platform
Starting and Stopping the Oracle Directory Integration Platform in a High Availability Scenario
Setting the Debugging Level for the Oracle Directory Integration Platform
Managing Oracle Directory Integration Platform in a Replicated Environment
Manually Registering the Oracle Directory Integration Platform
See Also: "Oracle Directory Integration Server" for a summary of the functions performed by the Oracle directory integration platform |
Note: For security reasons, Oracle recommends that you run the Oracle directory integration 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 about SSL and the directory in Oracle Internet Directory Administrator's Guide. |
This section introduces structural and operational information about the Oracle directory integration platform and contains these topics:
Oracle Directory Integration Platform and Configuration Set Entries
Standard Sequences of Oracle Directory Integration Platform Events
In Oracle Directory Integration Platform, 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 Platform 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 Platform communicates with external systems and what is communicated.
Each Oracle directory integration 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 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 server.
If the configuration set number is not specified, then the Oracle directory integration 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 Oracle directory integration server waits until integration profiles are added to that configuration set. This wait also occurs if integration profiles are configured for the configuration set but are disabled.
If the configuration set specified in the command line does not exist in the directory, then the Oracle directory integration 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 Oracle directory integration 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 Oracle directory integration platform executes three types of threads in the process, and these are described in Table 4-1.
Table 4-1 Oracle Directory Integration Platform Threads
Thread | Description |
---|---|
Main thread |
Daemon thread of the Oracle directory integration server. To look for changed profiles and to refresh its cache, it starts the scheduler and periodically sends refresh signals to it. This thread also looks for the shutdown signal from the OID Monitor ( |
Scheduler thread |
Scheduler for the connectors for synchronization based on their specified scheduling interval. This thread refreshes the synchronization profiles to the latest values after it receives a signal from the main thread. |
Connector thread |
In a synchronization, the thread that invokes the connector executable file named in the profile, and maps and filters the attributes. It is spawned by the scheduler at 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 server supports either provisioning or synchronization. The Oracle directory integration 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 by OID Monitor. Instead, it registers itself in Oracle Internet Directory with the configuration set number and the instance number.
The main thread periodically checks for the refresh time and signals the scheduler to refresh the main thread. It also periodically checks for the shutdown signal. When the shutdown signal is received, the scheduler thread shuts down.
After 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, the scheduler thread 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. Then, it returns control to the main thread.
Connector Thread Process Sequence for Synchronization
A synchronization thread follows this process:
Establishes a connection with the connected directory and Oracle Internet Directory.
In an import operation, executes any agent execution command that is 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.
Writes 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 you implement Oracle Directory Integration Platform 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 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.
Note: If the primary node running either the directory replication server (oidrepld ), or the Oracle directory integration server (odisrv ), or both fails, then the OID Monitor on the secondary node starts these processes on the secondary node after five minutes. However, when the primary node is restarted, these servers are not automatically restarted on the primary node.
Normal shutdown is not treated as a failover—that is, after a normal shutdown, the OID Monitor on the secondary node does not start these processes on the secondary node after five minutes. However, as in the case of a failure, when the primary node is restarted, these servers are not automatically restarted on the primary node. |
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 server as explained in "Stopping the Oracle Directory Integration Platform".
Get the value of the lastchangenumber
attribute on the target node by following the instructions in the dipassistant showprofile
section in the Oracle Directory Integration Platform tools chapter of Oracle Identity Management User Reference.
Copy the directory synchronization profiles from the primary node to the target nodes by following the instructions in the dipassistant reassociate
section of the Oracle Directory Integration Platform tools chapter of Oracle Identity Management User Reference.
Use the Oracle Directory Integration Server Administration tool or the Directory Integration 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 server as explained in "Starting the Oracle Directory Integration Platform".
In a default multimaster Oracle Internet Directory replication environment, the Oracle directory integration platform 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. 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 instructions in the dipassistant reassociate
command section in the Oracle Directory Integration Platform tools chapter of Oracle Identity Management User Reference.
When the Oracle directory integration server starts, it generates specific run-time information and stores it in the directory. This information includes:
The instance number of the Oracle directory integration server
The host on which it is running
The configuration set with which the Oracle directory integration 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 Server Administration tool or the ldapsearch
utility, as described in these topics:
To view runtime information for the Oracle directory integration server instance using the Oracle Directory Integration 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 platform runtime information.
To view registration information for the Oracle directory integration server instance using the ldapsearch
utility, perform a base search on its entry. For example:
ldapsearch -p 3060 -h my_host -D "mybinddn" -w mypassword -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 using either the Oracle Directory Integration Server Administration tool or the Directory Integration Assistant (dipassistant
). 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 Oracle directory integration server.
You can control the run-time behavior of the Oracle directory integration server by using a different configuration set entry when you start it. For example, you can start instance 1 of the Oracle directory integration 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 Oracle directory integration server instances. Similarly, running different configuration sets and different instances on different hosts balances the load between the servers.
The Oracle directory integration 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 Oracle Internet Directory using SSL with server authentication, you need a trust-point certificate to connect to the LDAP server. The Oracle directory integration 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 about 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 Oracle Directory Integration Platform. 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 |
---|---|
|
Identifies the location of the registration information of Oracle Directory Integration Platform with Oracle Internet Directory. The location of the file is in relation to the $ORACLE_HOME/ldap directory. |
|
Identifies the location of the certificate wallet. The certificate wallet file is the location of the ewallet.p12 file. |
|
Identifies the location of the file containing the encrypted wallet password. You must update this password by using the Directory Integration Assistant ( See Also: The chapter on SSL and the directory in Oracle Internet Directory Administrator's Guide |
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 /private/myhost/orahome/ldap/dipwallet directory.
This section tells you how to start, stop, and restart the Oracle Directory Integration Platform. It contains these topics:
Note: When the Oracle directory integration server is invoked in the default mode, it supports only the Oracle Directory Integration Platform Service, not the Oracle Directory Synchronization Service. |
Oracle Directory Integration Platform can be installed as a component of Oracle Internet Directory or as a standalone installation. How you start the Oracle directory integration server depends on whether you install Oracle Directory Integration Platform as a component of Oracle Internet Directory as a standalone installation.
To start Oracle Directory Integration Platform as a component of Oracle Internet Directory, you use the Oracle Internet Directory Monitor (oidmon
) and the Oracle Internet Directory Control Utility (oidctl
). You can start both utilities at the same time by using the Oracle Process Manager and Notification Server Control Utility (opmnctl
). When you install Oracle Directory Integration Platform as a component of Oracle Internet Directory, an instance of the Oracle directory integration server is started that only processes provisioning requests. To start an additional instance of Oracle directory integration server that performs synchronization, you must use the Oracle Internet Directory Control Utility (oidctl
). The oidmon
, oidctl
, and opmnctl
utilities are documented in the Oracle Identity Management server administration tools chapter of Oracle Identity Management User Reference.
To start a standalone installation of Oracle Directory Integration Platform, use the Oracle Directory Integration Server Control Tool (odisrv
), which is also documented in the Oracle Identity Management server administration tools chapter of the Oracle Identity Management User Reference. In a standalone installation of Oracle Directory Integration Platform, the Oracle directory integration server instance starts by default if no other Oracle directory integration server instance is running within the same Oracle Application Server infrastructure.
CAUTION: If you manually stop and then start the server within 30 seconds, the old server instance may not shut down before the new instance starts. This is because the Oracle directory integration server determines whether to shut down by polling the registration entry stored under |
How you stop the Oracle directory integration server depends on the utility you used to start it. If you started the server with either the oidctl
or the opmnctl
utility, then you must use the oidctl
utility to stop it. If you used the odisrv
utility to start the server, you must use the stopodiserver.sh
command to stop it. You can also use opmnctl
command to stop all running Oracle Internet Directory instances on a particular node, including directory servers, directory replication server, and Oracle directory integration server. The oidctl
, opmnctl
, odisrv
, and stopodiserver.sh
utilities are documented in the Oracle Identity Management server administration tools chapter of Oracle Identity Management User Reference.
To restart the Oracle directory integration server, first stop the server using the procedures described in "Stopping the Oracle Directory Integration Platform", wait 30 seconds, then start the server again using the procedures described in "Starting the Oracle Directory Integration Platform". You need to wait 30-seconds because the Oracle directory integration server determines whether to shut down by polling the registration entry stored under cn=odisrv,cn=subregistrysubentry
at 30 second intervals. If you start the server before the next polling interval, the first instance of the server will not be stopped, resulting in two running instances.
The Oracle directory integration platform can, with certain restrictions, execute in various high availability scenarios. This section discusses the Oracle directory integration server as it operates in an Oracle Real Application Clusters environment and in an Oracle Application Server Cold Failover Cluster (Infrastructure). It contains these topics:
In either type of high availability environment, there are two common scenarios for configuring Oracle Directory Integration Platform. They are:
Collocated–The Oracle directory integration server is located within the cluster on the same node as Oracle Internet Directory.
Outside the cluster–The Oracle directory integration server is installed on a separate node, outside the cluster.
The Oracle Internet Directory infrastructure is configured to work in an Oracle Real Application Clusters (Oracle RAC) mode. In Oracle RAC, the Oracle directory integration server can execute against any directory node.
A particular configuration set can be executed by only one instance of the Oracle directory integration server. For this reason, during the default installation only one server instance—namely, instance 1—is started on the Oracle RAC 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 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 transparent to the end user, and, once it is done, the Oracle directory integration 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 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 server itself fails to start.
You can stop the Oracle directory integration 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 opmnctl stopall
command, and subsequently execute the opmnctl startall
command, then the Oracle directory integration server starts.
In summary, unless an OID Control command stops the Oracle directory integration server, the OID Monitor ensures that the server is running.
In a collocated configuration, you can start Oracle Directory Integration Platform from any node in the cluster. Once the Oracle directory integration server is started on the first node, you do not need to start it on any other node. On failure of the Oracle directory integration server node, another node in OracleAS Cluster (Identity Management) will detect the failure and start the Oracle directory integration server. No additional OID Control command is required to register the Oracle directory integration platform.
In most cases, the Oracle Directory Integration Platform server communicates with only the single, default instance of the Oracle directory server. It is possible, however, to have manually configured the Oracle directory integration server to communicate with a second instance of the Oracle directory server. If the second instance of the Oracle directory server is not configured on the other nodes, then on failover, the surviving node will start both Oracle Directory Integration Platform and a second instance of the Oracle directory server.
In a collocated configuration, node failure is handled as follows: the OID Monitor on a surviving node keeps polling all other nodes every 10 seconds. When a node detects that one node is not responding, the OID Monitor on the surviving node starts the Oracle directory integration server and possibly the LDAP server (if it is not on the default node).
In an outside-the-cluster configuration, the Oracle directory integration server node does not have failover capability. In this configuration, you can configure Oracle Directory Integration Platform to connect to the Oracle Internet Directory LDAP server using a load balancer or virtual server in front of the multiple Oracle Internet Directory nodes.
In this configuration, you start the Oracle directory integration server with a virtual hostname. This is the default configuration on installation.
If the active node fails, then the OID Monitor on a standby node starts the Oracle directory integration 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 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 server. To start the server, you must use the OID Control utility.
If you execute the opmnctl stopall command
, and subsequently execute opmnctl startall
, then the Oracle directory integration server starts.
In summary, unless an OID Control command stops the Oracle directory integration server, OID Monitor ensures that the server is running.
See Also: The chapters on Oracle Application Server Cold Failover Cluster (Infrastructure) in Oracle Application Server High Availability Guide |
In a collocated configuration, start the Oracle Directory Integration Platform server using this command:
oidctl connect=connStr host=virtualHost server=odisrv instance=1 \ flags="host=virtualHost port=OIDPORT" start
In an outside-the-cluster configuration, to start the Oracle Directory Integration Platform server using this command:
oidctl connect=connStr server=odisrv instance=1 \ flags="host=OIDvirtualHost port=OIDPORT" start
Note: There are twohost parameters in the command-line examples for the collocated and outside-the-cluster configurations:
|
You set the debugging level by specifying a value for the orclodipdebuglevel
attribute in the profile. The value you assign to the orclodipdebuglevel
attribute enables you to separately control the trace logging levels for the Oracle directory integration server and that of each connector.
For server execution, tracing is stored in the $ORACLE_HOME/ldap/log/odisrv_nn.log file, where nn
is the number of the started instance. For connectors, tracing is stored in the $ORACLE_HOME/ldap/odi/log/profile_name.trc.
See Also: Appendix C, "Troubleshooting the Oracle Directory Integration Platform" for more information about 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 debugging 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
Debugging Event Type | Numeric Value |
---|---|
Starting and stopping threads |
1 |
Refreshing 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 about selectively debugging the threads |
If you do not set a value for the debugging flag, then the default level is 0
(zero), and none of the debugging 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
Debugging Event Type | Numeric Value |
---|---|
Initializing and terminating |
1 |
Searching within the connection |
2 |
Processing entries after searching |
4 |
Creating change records |
8 |
Processing details of change records |
16 |
Mapping details |
32 |
See Also: Theoidprovtool section in the Oracle Directory Integration Platform tools chapter of the Oracle Identity Management User Reference for information about the debug attribute for a synchronization profile |
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.
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_nnnn.log where nnnn
is the identifier of the process running the Oracle directory integration server in that table.
All the profile-specific debugging events are stored in the profile-specific trace file in $ORACLE_HOME/ldap/odi/log/profile_name.trc.
The Oracle directory integration server is registered with Oracle Internet Directory during installation of Oracle Directory Integration Platform. This registration creates a footprint in the directory indicating the specified host as the one authorized to run Oracle Directory Integration Platform.
There may be times when you need to perform this registration manually on the client side, for example, if there is a failure during installation. You can do this by using either the Oracle directory integration server registration tool (odisrvreg
) or Oracle Enterprise Manager 10g Application Server Control Console.
You must separately register each Oracle directory integration 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 Oracle Directory Integration Platform in an Oracle Identity Management infrastructure. When you do this, Application Server Control Console registers the Oracle directory integration 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.
Click Configure Components, 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 did not configure any Oracle Application Server components. |
Select Oracle Directory Integration Platform, 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
.
Click Finish to complete the registration.