9 Configuring ICF Connectors
This chapter provides the information about the common customization procedures that needs to be performed for all ICF connectors.
The following are the topics discussed in this chapter:
9.1 Configuring Connector Load Balancer
A connector server is an application that enables remote execution of an Identity Connector. If there are multiple connector servers, then you must ensure the high availability of the connector server for the remote execution of the Identity connector and failover management. Therefore, you must configure a load balancer for a connector server.
This section contains the following topics:
9.1.1 About the Load Balancer Configuration
If there are multiple connector servers, then you must ensure the high availability of the connector server for the remote execution of the Identity connector and failover management.
Figure 9-1 depicts the typical configuration for a cluster of connector servers. The flow in the figure is based on the assumption that the required connector bundle is deployed across all the connector servers.
9.2 Configuring Validation of Data During Reconciliation and Provisioning
Configuring validation of data during reconciliation and provisioning is done by implementing the validation logic in a Java class.
This section contains the following topics:
9.2.1 About Validation of Data During Reconciliation and Provisioning
The Lookup.CONNECTOR_NAME.ProvValidations and Lookup.CONNECTOR_NAME.UM.ReconValidations lookup definitions hold single-valued data to be validated during provisioning and reconciliation operations, respectively.
For example, you can validate data fetched from the First Name attribute to ensure that it does not contain the number sign (#). In addition, you can validate data entered in the First Name field on the process form so that the number sign (#) is not sent to the target system during provisioning operations.
Note:
The Lookup.CONNECTOR_NAME.UM.ProvValidations and Lookup.CONNECTOR_NAME.UM.ReconValidations lookup definitions are optional and do not exist by default.
You must add these lookups as decode values to the Lookup.CONNECTOR_NAME.UM.Configuration lookup definition to enable exclusions during provisioning and reconciliation operations. See the respective connector guide for more information about setting up the lookup definition for user operations.
9.2.2 Configuring Validation of Data
Configuring validation of data during reconciliation and provisioning involves implementing the validate method in a validation class, creating lookup definitions for data validation, and uploading the validation class JAR file to the database.
To configure validation of data:
9.2.3 Sample Validation Class
You can implement the validate method in a sample validation class.
The following sample validation class checks if the value in the First Name attribute contains the number sign (#):
package com.validationexample; import java.util.HashMap; public class MyValidator { public boolean validate(HashMap hmUserDetails, HashMap hmEntitlementDetails, String sField) throws ConnectorException { /* You must write code to validate attributes. Parent * data values can be fetched by using hmUserDetails.get(field) * For child data values, loop through the * ArrayList/Vector fetched by hmEntitlementDetails.get("Child Table") * Depending on the outcome of the validation operation, * the code must return true or false. */ /* * In this sample code, the value "false" is returned if the field * contains the number sign (#). Otherwise, the value "true" is * returned. */ boolean valid = true; String sFirstName = (String) hmUserDetails.get(sField); for (int i = 0; i < sFirstName.length(); i++) { if (sFirstName.charAt(i) == '#') { valid = false; break; } } return valid; } }
9.3 Configuring Transformation of Data During User Reconciliation
Configuring transformation of data during user reconciliation is done by implementing the transform method in a transformation class.
This section contains the following topics:
9.3.1 About Transformation of Data During User Reconciliation
The Lookup.CONNECTOR_NAME.UM.ReconTransformations lookup definition holds single-valued user data to be transformed during reconciliation operations.
For example, you can use First Name and Last Name values to create a value for the Full Name field in Oracle Identity Manager.
Note:
The Lookup.CONNECTOR_NAME.UM.ReconTransformations lookup definition is optional and does not exist by default.
You must add this lookup as decode value to the Lookup.CONNECTOR_NAME.UM.Configuration lookup definition to enable exclusions during provisioning and reconciliation operations. See the respective connector guide for more information about setting up the lookup definition for user operations.
9.3.2 Configuring Transformation of Single-Valued User Data Fetched During Reconciliation
Configuring transformation of single-valued user data fetched during reconciliation involves implementing the transform method in a transformation class, creating lookup definitions, and uploading the transformation class JAR file to the database.
To configure transformation of single-valued user data fetched during reconciliation:
9.3.3 Sample Transformation Class
You can implement the transform method in a transformation class.
The following sample transformation class creates a value for the Full Name attribute by using values fetched from the First Name and Last Name attributes of the target system:
package com.transformationexample; import java.util.HashMap; public class MyTransformer { public Object transform(HashMap hmUserDetails, HashMap hmEntitlementDetails, String sField) throws ConnectorException { /* * You must write code to transform the attributes. * Parent data attribute values can be fetched by * using hmUserDetails.get("Field Name"). * To fetch child data values, loop through the * ArrayList/Vector fetched by hmEntitlementDetails.get("Child Table") * Return the transformed attribute. */ String sFirstName = (String) hmUserDetails.get("First Name"); String sLastName = (String) hmUserDetails.get("Last Name"); return sFirstName + "." + sLastName; } }
9.4 Configuring Resource Exclusion Lists
The Lookup.CONNECTOR_NAME.UM.ProvExclusionList and Lookup.CONNECTOR_NAME.UM.ReconExclusionList lookup definitions hold user IDs of target system accounts for which you do not want to perform provisioning and reconciliation operations, respectively.
This section contains the following topics:
9.4.1 About Resource Excursion Lists
Resource excursion list for provisioning and reconciliation operations is created by adding the Lookup.CONNECTOR_NAME.UM.ProvExclusionList and Lookup.CONNECTOR_NAME.UM.ReconExclusionList lookups as decode values to the Lookup.CONNECTOR_NAME.UM.Configuration lookup definition.
The Lookup.CONNECTOR_NAME.UM.ProvExclusionList and Lookup.CONNECTOR_NAME.UM.ReconExclusionList lookup definitions hold user IDs of target system accounts for which you do not want to perform provisioning and reconciliation operations, respectively.
The Lookup.CONNECTOR_NAME.UM.ProvExclusionList and Lookup.CONNECTOR_NAME.UM.ReconExclusionList lookup definitions are optional and do not exist by default.
You must add these lookups as decode values to the Lookup.CONNECTOR_NAME.UM.Configuration lookup definition to enable exclusions during provisioning and reconciliation operations. See the respective connector guide for more information about setting up the lookup definition for user operations.
9.4.2 Format of Values Stored in the Lookups
Enter decode key values as the values stored in the lookups.
The following is the format of the values stored in these lookups:
Code Key | Decode | Sample Values |
---|---|---|
User Login Id resource object field name |
User ID of a user |
Code Key: User Login Id Decode: User001 |
User Login Id resource object field name with the [PATTERN] suffix |
A regular expression supported by the representation in the |
Code Key: User Login Id[PATTERN] To exclude users matching any of the user ID 's User001, User002, User088, then: Decode: User001|User002|User088 To exclude users whose user ID 's start with 00012, then: Decode: 00012* See Also: For information about the supported patterns, visit:
|
9.5 Configuring SSL Communication
Configure and troubleshoot SSL communication between Connector Server and Oracle Identity Manager.
This section describes how to configure SSL communication between Connector Server and Oracle Identity Manager. It contains the following topics:
9.5.1 Setting SSL for Connector Server and Oracle Identity Governance
An SSL connection is required when establishing a connection for each SSL-enabled connector server.
To set up the SSL communication between Connector Server and Oracle Identity Manager:
-
Generate a new SSL key (or you can reuse your existing key):
keytool -genkey -alias keyconnserv -keyalg dsa -keystore <yourKeyStore.jks> -storepass <yourPassword> -validity 360
-
Export the newly generated public key:
keytool -export -keystore <yourKeyStore.jks> -storepass <yourPassword> -alias keyconnserv -file icfkey-public.cer
-
Configure your Connector Server for SSL, and start using the new keystore set in Step 1.
-
Import the public key generated in Step 2 (icfkey-public.cer) to OIM keystore.
-
Configure IT Resource such as host, port, and so on. These parameters will be passed on to Connector Server (an extra field of IT Resource).
-
Configure Connector Server, using SSL:
-
Deploy an SSL certificate to the Connector Server's system.
-
Configure your Connector Server to provide SSL sockets.
-
Configure your application to communicate with the Connector Server using SSL.
Refer to the target system's manual for specific notes on configuring connections to identity connector servers. You will indicate to your application that an SSL connection is required when establishing a connection for each SSL-enabled connector server. Additionally, if any of the SSL certificates used by your connector servers are issued by a non-standard certificate authority, your application must be configured to respect the additional authorities. Refer to your manual for notes regarding certificate authorities.
Note:
Java applications may solve the issue of non-standard certificate authorities by expecting the following Java system properties to be passed when launching the application:
-
javax.net.ssl.trustStorePassword
For example:
-Djavax.net.ssl.trustStorePassword=PASWORD
-
javax.net.ssl.trustStore
For example:
-Djavax.net.ssl.trustStore=/usr/myApp_cacerts
Alternately, the non-standard certificate authorities may be imported to the standard ${JAVA_HOME}/lib/security/cacerts directory.
-
-
-
Import the public key generated in Step 2 to OIM keystore.
If you follow to choose the default Weblogic keystore, perform the following:
keytool -import -trustcacerts -alias icfkey -file icfkey-public.cer -keystore <pathToYouKeystore>
For example default Weblogic keystores are: server/lib/DemoTrust.jks and server/lib/DemoIdentity.jks.
9.5.2 Troubleshooting SSL
Use the connector server logs and connector server setting in the configuration folder for troubleshooting issues related to SSL configuration.
The following is an example of exception in connector server logs:
java.net.SocketException: Default SSL context init failed: null
This means that the path to keystore is incorrect. To handle this exception, make sure you provide the following full/absolute path:
For UNIX
./connectorserver.sh /run "-J-Djavax.net.ssl.keyStore=/path/to/mykeystore.jks" "-J-Djavax.net.ssl.keyStorePassword=PASSWORD"
For Windows
./connectorserver.sh /run "-J-Djavax.net.ssl.keyStore=C:\path\to\mykeystore.jks" "-J-Djavax.net.ssl.keyStorePassword=PASSWORD"
You must also ensure the following check points:
-
Check your configuration folder for the setting of connector server configuration to use SSL
-
Restart your WLS after importing public keys from the connector server, if the public key present in OIM keystore
9.6 Adding Target System Attributes
Adding target system attributes includes adding attributes for provisioning, target resource reconciliation, and trusted source reconciliation.
This section contains the following topics:
Note:
If you add an attribute with a Date type field, make sure that you add the [Date]
suffix in the Lookup definition code key.
For example, if you add _LAST_PASSWORD_CHANGE_DATE_, when you make changes in the code key for Lookup.CONNECTOR_NAME.UM.ReconAttrMap or Lookup.CONNECTOR_NAME.UM.ProvAttrMap, specify the attribute as:
_LAST_PASSWORD_CHANGE_DATE_[Date]
9.6.1 Adding Target System Attributes for Provisioning
By default, the target system attributes are mapped for provisioning between Oracle Identity Manager and the target system.
If required, you can map additional attributes for provisioning by performing the steps described in this section.
Note:
In this section, the term "attribute" refers to the identity data fields that store user data.
Adding target system attributes for provisioning involves the following:
9.6.1.2 Adding the New Field to the Provisioning Mapping Lookup
After creating a new form field, you must add that field to the Provisioning Mapping Lookup. To do so:
9.6.2 Adding Target System Attributes for Target Reconciliation
By default, the target system attributes are mapped for reconciliation between Oracle Identity Manager and the target system.
If required, you can map additional attributes for target reconciliation as described in this section.
Note:
-
Perform this procedure only if you want to add new target system attributes for reconciliation.
-
In the following steps, a new attribute called BUILDING will be added, its connector attribute name is BUILDING, and the form field name is Building. Names are case-sensitive.
To add a new target system attribute for target reconciliation, follow these steps:
-
In the resource object definition, add a reconciliation field corresponding to the new attribute, as follows:
-
Open the Resource Objects form. This form is in the Resource Management folder.
-
Click Query for Records.
-
On the Resource Objects Table tab, double-click the CONNECTOR_NAME User resource object to open it for editing.
-
On the Object Reconciliation tab, click Add Field to open the Add Reconciliation Field dialog box.
-
Specify a value for the field name that is the name of the new Attribute on your Form.
For example: Building
-
From the Field Type list, select a data type for the field.
For example: String
-
Save the values that you enter, and then close the dialog box.
-
If required, repeat Steps d through g to map more fields.
-
Click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.
-
-
If a corresponding field does not exist in the process form, then add a new column in the process form, as follows:
-
Open the Form Designer form. This form is in the Development tools folder.
-
Query for the UD_CONNECTOR_NAMECON form.
-
Click Create New Version. The Create a New Version dialog box is displayed.
-
In the Label field, enter the name of the version.
-
Click Save and close the dialog box.
-
From the Current Version box, select the version name that you entered in the Label field in Step 3.
-
On the Additional Columns tab, click Add.
-
In the Name field, enter the name of the data field and then enter the other details of the field.
Note: Repeat Steps g and h if you want to add more attributes.
-
Click Save and then click Make Version Active.
-
-
Modify the process definition to include the mapping between the newly added attribute and the corresponding reconciliation field:
-
Open the Process Definition form. This form is in the Process Management folder of the Design Console.
-
Click the Query for Records icon.
-
On the Process Definition Table tab, double-click the CONNECTOR_NAME User process definition.
-
On the Reconciliation Field Mappings tab, click Add Field Map to open the Add Reconciliation Field Mapping dialog box.
-
From the Field Name list, select the name of the resource object that you added in Step 2e.
-
Double-click Process Data Field and select the corresponding process form field from the Lookup dialog box. Then, click OK.
-
Click Save and close the dialog box.
-
If required, repeat Steps c through g to map more fields.
-
-
Go to the reconciliation lookup, Lookup.CONNECTOR_NAME.UM.ReconAttrMap, and add a new record for the new attribute using the following values:
-
Code Key - Name of the reconciliation field
-
Decode - Name of the CONNECTOR_NAME attribute
-
-
In the Design Console, regenerate the reconciliation profile for the Resource Object.
9.6.3 Adding Target System Attributes for Trusted Reconciliation
By default, the attributes for trusted source reconciliation are mapped between Oracle Identity Manager and the target system.
If required, you can map additional attributes for trusted reconciliation as described in this section.
Note:
-
Perform this procedure only if you want to add new target system attributes for reconciliation.
-
In the following steps, a new attribute called BUILDING will be added, its connector attribute name is BUILDING, and the form field name is Building. Names are case-sensitive.
To add a new target system attribute for trusted reconciliation, follow these steps:
-
In the resource object definition, add a reconciliation field corresponding to the new attribute, as follows:
-
Open the Resource Objects form. This form is in the Resource Management folder.
-
Click Query for Records.
-
On the Resource Objects Table tab, double-click the CONNECTOR_NAME Trusted User resource object to open it for editing.
-
On the Object Reconciliation tab, click Add Field to open the Add Reconciliation Field dialog box.
-
Specify a value for the field name that is the name of the new Attribute on your Form.
For example: Building
-
From the Field Type list, select a data type for the field.
For example: String
-
Save the values that you enter, and then close the dialog box.
-
If required, repeat Steps d through g to map more fields.
-
Click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.
-
-
If a corresponding field does not exist in the process form, then add a new column in the process form, as follows:
-
Open the Form Designer form. This form is in the Development tools folder.
-
Query for the UD_CONNECTOR_NAMECON form.
-
Click Create New Version. The Create a New Version dialog box is displayed.
-
In the Label field, enter the name of the version.
-
Click Save and close the dialog box.
-
From the Current Version box, select the version name that you entered in the Label field in Step 3.
-
On the Additional Columns tab, click Add.
-
In the Name field, enter the name of the data field and then enter the other details of the field.
Note: Repeat Steps g and h if you want to add more attributes.
-
Click Save and then click Make Version Active.
-
-
Modify the process definition to include the mapping between the newly added attribute and the corresponding reconciliation field:
-
Open the Process Definition form. This form is in the Process Management folder of the Design Console.
-
Click the Query for Records icon.
-
On the Process Definition Table tab, double-click the CONNECTOR_NAME Trusted User process definition.
-
On the Reconciliation Field Mappings tab, click Add Field Map to open the Add Reconciliation Field Mapping dialog box.
-
From the Field Name list, select the name of the resource object that you added in Step 2e.
-
Double-click Process Data Field and select the corresponding process form field from the Lookup dialog box. Then, click OK.
-
Click Save and close the dialog box.
-
If required, repeat Steps c through g to map more fields.
-
-
Go to the reconciliation lookup, Lookup.CONNECTOR_NAME.UM.ReconAttrMap.Trusted, and add a new record for the new attribute using the following values:
-
Code Key - Name of the reconciliation field
-
Decode - Name of the CONNECTOR_NAME attribute
-