Oracle® Identity Manager Administrative and User Console Guide Release 9.1.0.1 Part Number E14057-01 |
|
|
View PDF |
The guidelines explained in this chapter are aimed at ensuring that your custom connectors meet the compatibility requirements for using the connector installer and the Diagnostic Dashboard. These guidelines apply only to specific areas of custom connector development.
This chapter contains the following sections:
This section discusses the structure of the configuration XML file that is used during the connector installation process. Use the information in this section to create configuration XML files for your custom connectors.
The following is the recommended path for copying the installation files for the predefined connectors:
OIM_HOME/xellerate/ConnectorDefaultDirectory
When you install Oracle Identity Manager, the following files are copied into the ConnectorDefaultDirectory
directory:
ConnectorConfigTemplate.xml
This is a template of the configuration XML file. Use a copy of this file to create the configuration XML file.
ConnectorSchema.xsd
This is the XML schema document (XSD) against which you must validate the configuration XML file that you create.
Table 18-1 lists the elements in the configuration XML file. Use the links in this table to access sections on each element.
Table 18-1 Elements in the Configuration XML File
Root Element | Level 1 Element | Level 2 Element | Level 3 Element |
---|---|---|---|
See "Sample Configuration XML File" for the contents of a sample configuration XML file.
The following table summarizes the properties of the connector
element:
Property | Value |
---|---|
Parent Element | NA |
Attributes | NA
In the template XML file, do not change the values of attributes of this element. |
Child Elements | connector-name , connector-version , filecopy , configuration , pre-Install , and dependency-connector |
Number of Occurrences | One |
Element Value | NA |
The connector
element is the root element in the configuration XML file. See the following sections for information about the child elements of the connector
element:
The following table summarizes the properties of the connector-name
element:
Property | Value |
---|---|
Parent Element | connector |
Attributes | None |
Child Elements | None |
Number of Occurrences | One |
Element Value | Name of the connector |
Use the connector-name
element to specify the name of the target system of the connector. The connector name value is displayed on most of the connector installation pages.
Sample usage:
<connector-name>Active Directory</connector-name>
The following table summarizes the properties of the connector-version
element:
Property | Value |
---|---|
Parent Element | connector |
Attributes | None |
Child Elements | None |
Number of Occurrences | One |
Element Value | Release number of the connector |
Use the connector-version
element to specify the connector release number. The release number is displayed along with the name of the connector. It is also used to compare releases and provide upgrade guidelines to users.
Sample usage:
<connector-version>9.1.0</connector-version>
Apply the following guidelines whenever you specify a value for the connector-version
element:
Use only numerals and periods (.) to specify the connector release number.
Ensure that there are no spaces in the connector release number.
Trailing zeros in the connector release number are discarded when the release number of a connector is compared with the release number of another connector. For example, the values 9.1.0
and 9.1.0.0
are considered the same by the code that compares release numbers.
The following table summarizes the properties of the filecopy
element:
Property | Value |
---|---|
Parent Element | connector |
Attributes | None |
Child Elements | destination |
Number of Occurrences | One |
Element Value | NA |
The filecopy
element serves as the container for destination
elements, which hold details of the files to be copied from specific directories in the connector installation media directory.
The "destination Element" section discusses the child element of the filecopy
element.
The following table summarizes the properties of the destination
element:
Property | Value |
---|---|
Parent Element | filecopy |
Attributes | folder |
Child Elements | file |
Number of Occurrences | One for each type of file to be copied |
Element Value | The value can be JavaTasks , ScheduleTask , connectorResources , or ThirdParty . |
Use the folder
attribute of the destination
element to specify the name of the folder on the Oracle Identity Manager server into which a certain type of connector files must be copied. As mentioned in the table, you can specify any one of the following folders:
connectorResources
: Specify this folder if the connector installation media contains resource bundles.
JavaTasks
: Specify this folder if the connector installation media contains JAR files for provisioning.
ScheduleTask
: Specify this folder if the connector installation media contains JAR files for reconciliation.
ThirdParty
: Specify this folder if the connector installation media contains external code files that the connector requires for provisioning or reconciliation.
The "file Element" section discusses the child elements of the filecopy
element.
The following table summarizes the properties of the file
element:
Property | Value |
---|---|
Parent Element | destination or source
Note: The |
Attributes | None |
Child Elements | None |
Number of Occurrences | At least one |
Element Value | Name of file to be copied |
Use the file
element to specify the name of the file that must be copied into the folder specified by the parent destination
element. The case of the file name (uppercase and lowercase) that you specify must be the same as that of the actual name. For a given file name, the installation program searches the entire connector installation media directory to locate the file and then copies the file into the folder specified by the parent destination
element.
Sample usage:
<file>ActiveDirectory.properties</file>
If you want the same file to be copied into multiple directories, then you must specify the file name in file
elements under the required destination
elements. For example, suppose you want the connector.jar
file to be copied into both the JavaTasks
and ScheduleTask
directories, then add the following lines in the XML file:
<destination folder="JavaTasks"> <file>connector.jar</file> </destination> <destination folder="ScheduleTask"> <file>connector.jar</file> </destination>
The following table summarizes the properties of the configuration
element:
Property | Value |
---|---|
Parent Element | connector |
Attributes | None |
Child Elements | destination |
Number of Occurrences | One |
Element Value | NA |
The configuration
element is used to hold information about the XML files that are to be imported during the installation process.
The "source Element" section discusses the child element of the configuration
element.
The following table summarizes the properties of the source
element:
Property | Value |
---|---|
Parent Element | configuration |
Attributes | folder |
Child Elements | file
Note: The |
Number of Occurrences | One |
Element Value | xml |
The source
element is used to specify the xml
folder in the connector installation media directory in which the connector XML files are stored. During the installation process, the Deployment Manager is called to import these XML files.
The following sample code lines show how the configuration
, source
, and file
elements must be used:
<configuration> <source folder="xml"> <file>xliADResourceObject.xml</file> <file>xliADXLResourceObject.xml</file> </source> </configuration>
The following table summarizes the properties of the pre-Install
element:
Property | Value |
---|---|
Parent Element | connector |
Attributes | None |
Child Elements | title |
Number of Occurrences | One |
Element Value | NA |
You might need to perform certain tasks before you can start using some connectors. For example, the Microsoft Active Directory connector requires you to configure Secure Sockets Layer (SSL) to secure communication between Oracle Identity Manager and the target system. These prerequisite tasks can be displayed at the end of the connector installation process by using the child elements of the pre-Install
element.
If you do not want to display prerequisite tasks at the end of the connector installation process, then do not include the pre-Install
element in the XML file.
The "title Element" section discusses the child element of the pre-Install
element.
The following table summarizes the properties of the title
element:
Property | Value |
---|---|
Parent Element | pre-Install |
Attributes | description |
Child Elements | step |
Number of Occurrences | At least one |
Element Value | Key value of the resource bundle line that contains the text to be displayed |
In the resource bundle, there is a line that specifies the title of the section containing prerequisite tasks for the connector. Use the description
attribute of the title
element to specify the key value of this resource bundle line.
Note:
The key value of a resource bundle line is the text to the left of the equal sign (=) in the resource bundle. See Oracle Identity Manager Globalization Guide for more information about resource bundles.The "step Element" section discusses the child element of the title
element. The example in that section illustrates how you must use this element.
The following table summarizes the properties of the step
element:
Property | Value |
---|---|
Parent Element | title |
Attributes | None |
Child Elements | None |
Number of Occurrences | One |
Element Value | Key value of the resource bundle line that contains the text to be displayed |
Use the step
element to specify the key value of the resource bundle line that describes a single prerequisite task for the connector.
The following example uses the Microsoft Active Directory connector to illustrate how you must use the pre-Install
, title
, and step
elements:
The following is a partial listing of the prerequisite tasks that are displayed after the installation of the Microsoft Active Directory connector:
Enabling LDAPS - Ensure that Certificate Services are installed on the server. - Open the default group policy for the Domain Controller on the server (in Active Directory Users and Computers). - Right-click the domain node, and select Properties.Click the Group Policy tab. - Select Default Domain Policy. . . . Setting Up the Microsoft Active Directory Certificate as a Trusted Certificate - To make the Microsoft Active Directory certificate a trusted certificate, export the certificate and import it into the keystore of the Oracle Xellerate Identity Provisioning server as a trusted CA certificate. . . .
The following is a partial listing of the resource bundle lines that contain the prerequisite tasks that appear after the installation of the Microsoft Active Directory connector:
AD-connector.prerequisite.enablingldaps=Enabling LDAPS AD-connector.prerequisite.enablingldapsteps=<ul><li>Ensure that Certificate Services are installed on the server</li><li>Open the default group policy for the Domain Controller on the server (in Active Directory Users and Computers).</li><li>Right-click the domain node, and select Properties.</li><li>Click the Group Policy tab.</li><li>Select Default Domain Policy.</li>. . . </ul> AD-connector.prerequisite.setupad=Setting Up the Microsoft Active Directory Certificate as a Trusted Certificate AD-connector.prerequisite.setupadsteps=<ul><li>To make the Microsoft Active Directory certificate a trusted certificate, export the certificate and import it into the keystore of the Oracle Xellerate Identity Provisioning server as a trusted CA certificate.</li> . . .</ul>
To enable the display of these resource bundle lines at the end of the installation process, you must add the following lines in the configuration XML file:
<pre-Install> <title description="AD-connector.prerequisite.enablingldaps"> <step>AD-connector.prerequisite.enablingldapsteps</step> </title> <title description="AD-connector.prerequisite.setupad"> <step>AD-connector.prerequisite.setupadsteps</step> </title> </pre-Install>
The following table summarizes the properties of the dependency-connector
element:
Property | Value |
---|---|
Parent Element | connector |
Attributes | None |
Child Elements | dependency-connector-name , dependency-connector-version |
Number of Occurrences | At least one |
Element Value | NA |
You can start using certain connectors only after the installation of certain other connectors. For example, you can start using the Novell GroupWise connector only after you install the Novell eDirectory connector. In the Oracle Identity Manager context, the connector whose installation is a prerequisite is called the dependent connector. For example, the Novell eDirectory connector is the dependent (required) connector for the Novell GroupWise connector.
The dependency-connector
element is used to hold information about dependent connectors for your connector. If your connector has multiple dependent connectors, then add one dependency-connector
element in the XML file for each dependent connector.
The following sections discuss the child elements of the dependency-connector
element:
The following table summarizes the properties of the dependency-connector-name
element:
Property | Value |
---|---|
Parent Element | dependency-connector |
Attributes | None |
Child Elements | None |
Number of Occurrences | At least one |
Element Value | Name of the dependent connector |
Use the dependency-connector-name
element to specify the name of the dependent connector for your connector. The name that you specify must be the same as the name that is specified in the connector-name
element of the XML file for the dependent connector.
The "dependency-connector-version Element" section contains an example that illustrates how you must use the dependency-connector-name
element.
The following table summarizes the properties of the dependency-connector-version
element.
Property | Value |
---|---|
Parent Element | dependency-connector |
Attributes | None |
Child Elements | None |
Number of Occurrences | One for each occurrence of the dependency-connector-name element |
Element Value | Release number of the dependent connector |
Use the dependency-connector-version
element to specify the release number of the dependent connector for your connector. The release number that you specify must be the same as the release number that is specified in the connector-version
element of the configuration XML file for the dependent connector. Ensure that there are no spaces in the connector version value that you specify.
The following example illustrates how to use the dependency-connector
, dependency-connector-name
, and dependency-connector-version
elements.
DepConn1
and DepConn2
are dependent connectors for your connector. Their release numbers are 9.0.3 and 9.0.4.1, respectively. For these dependent connectors, you must add the following lines in the configuration XML file of your connector:
<dependency-connector> <dependency-connector-name>DepConn1<dependency-connector-name> <dependency-connector-version>9.0.3<dependency-connector-version> </dependency-connector> <dependency-connector> <dependency-connector-name>DepConn2</dependency-connector-name> <dependency-connector-version>9.0.4.1<dependency-connector-version> </dependency-connector>
If your connector has no dependent connectors, then you need not add the dependency-connector
element.
The following are the contents of a sample configuration XML file:
<?xml version="1.0" encoding="UTF-8" ?> <connector orderid="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\ConnectorSchema.xsd"> <connector-name>Active Directory</connector-name> <connector-version>9.1.0</connector-version> <filecopy> <destination folder="ConnectorResources"> <file>ActiveDirectory.properties</file> <destination folder="JavaTasks"> <file>connector.jar</file> </destination> <destination folder="ScheduleTask"> <file>connector.jar</file> </destination> </filecopy> <configuration> <source folder="xml"> <file>ActiveDirectory.xml</file> </source> </configuration> <pre-Install> <title description="AD-connector.prerequisite.enablingldaps"> <step>AD-connector.prerequisite.enablingldapsteps</step> </title> <title description="AD-connector.prerequisite.setupad"> <step>AD-connector.prerequisite.setupadsteps</step> </title> </pre-Install> <dependency-connector> <dependency-connector-name>DepConn1<dependency-connector-name> <dependency-connector-version>9.0.3<dependency-connector-version> </dependency-connector> <dependency-connector> <dependency-connector-name>DepConn2</dependency-connector-name> <dependency-connector-version>9.0.4.1<dependency-connector-version> </dependency-connector>
You must develop a test class for the connector. When you use the Diagnostic Dashboard to test connectivity, reconciliation, or provisioning, this class is used to run the test.
The following are guidelines on creating the test class:
The test class must implement the testBasicConnectivity
, testProvisioning
, and testReconciliation
methods. These methods must accept a hashmap parameter.
The name of the test class must be in the following format:
connector_nameConnectorTest.java
To apply this format, replace connector_name
with the value of the ITResourceDef
attribute of the SPD_KEY
element in the following file:
Connector_Pack_Directory/xml/xliconnector_nameResourceObject.xml
Remove spaces, if there are any, from the value of the ITResourceDef
attribute. For example, suppose the SPD_KEY
element in the XML file is as follows:
<SPD_KEY ITResourceDef="AD Server"/>
In this case, set the name of the test class to ADServerConnectorTest.java
.
Include the test class file in the connector JAR file, and then copy the JAR file into the lib
directory inside the connector pack directory.
After you create the connector files, you must place them in the directories described in Table 18-2. These directories are placed in the connector pack directory for your connector. For example, the connector pack directory for the Microsoft Active Directory connector is ActiveDirectory
.
Table 18-2 Structure of the Connector Pack Directory
Directory | Description |
---|---|
|
In this directory, place the configuration XML file to be used during the installation process. For example: |
|
In this directory, place all third-party JAR files. During the installation process, files in this directory are copied into the For example, the |
|
In this directory, place the JAR files required for reconciliation and provisioning operations. During the installation process, JAR files for reconciliation are copied into the For example: |
|
In this directory, place the resource bundles. During the installation process, these resource bundles are copied into the For example: |
|
In this directory, place the scripts that must be run as part of the manual connector configuration process. These scripts are not used during the installation process performed by using the Administrative and User Console. |
|
In this directory, place the connector XML files for trusted source and target resource reconciliation. During the installation process, the connector XML files mentioned in the configuration XML file are imported by the Deployment Manager. For example: |