Skip Headers
Oracle® Identity Manager Connector Guide for Microsoft Active Directory
Release 9.0.4

Part Number E10158-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

3 Configuring the Connector

After you deploy the connector, you must configure it to meet your requirements. This chapter discusses the following connector configuration procedures:

Note:

These sections provide both conceptual and procedural information about configuring the connector. It is recommended that you read the conceptual information before you perform the procedures.

Configuring Reconciliation

As mentioned earlier in this guide, reconciliation involves duplicating in Oracle Identity Manager additions of and modifications to user accounts on the target system. This section discusses the following topics related to configuring reconciliation:

Configuring Trusted Source Reconciliation

While configuring the connector, the target system can be designated as a trusted source or target resource. If you designate the target system as a trusted source, then both newly created and modified user accounts are reconciled in Oracle Identity Manager. If you designate the target system as a target resource, then only modified user accounts are reconciled in Oracle Identity Manager.

Note:

You can skip this section if you do not want to designate the target system as a trusted source for reconciliation.

To import the XML file for trusted source reconciliation:

Note:

Only one target system can be designated as a trusted source. If you import the xliADXLResourceObject.xml file while you have another trusted source configured, then both connector reconciliations would stop working.
  1. Open the Oracle Identity Manager Administrative and User Console.

  2. Click the Deployment Management link on the left navigation bar.

  3. Click the Import link under Deployment Management. A dialog box for locating files is displayed.

  4. Locate and open the xliADXLResourceObject.xml file, which is in the OIM_home/xellerate/XLIntegrations/ActiveDirectory/xml directory. Details of this XML file are shown on the File Preview page.

  5. Click Add File. The Substitutions page is displayed.

  6. Click Next. The Confirmation page is displayed.

  7. Click Import.

  8. In the message that is displayed, click Import to confirm that you want to import the XML file and then click OK.

After you import the XML file for trusted source reconciliation, you must set the value of the TrustedSource reconciliation scheduled task attribute to True. This procedure is described in the "Configuring the Reconciliation Scheduled Tasks" section.

Partial Reconciliation

By default, all target system records that are added or modified after the last reconciliation run are reconciled during the current reconciliation run. You can customize this process by specifying the subset of added or modified target system records that must be reconciled. You do this by creating filters for the reconciliation module.

For this connector, you create a filter by specifying values for the CustomizedReconQuery IT resource parameter while performing the procedure described in the "Defining IT Resources" section.

The following table lists the Microsoft Active Directory attributes, and the corresponding Oracle Identity Manager attributes, that you can use to build the query condition. You specify this query condition as the value of the CustomizedReconQuery parameter.

Oracle Identity Manager Attribute Microsoft Active Directory Attribute
User ID sAMAccountName
First Name givenName
Last Name sn
Middle Name initials
Full Name displayName
Groups memberOf

The following are sample query conditions:

  • givenName=John&sn=Doe

    With this query condition, records of users whose first name is John and last name is Doe are reconciled.

  • givenName=John&sn=Doe|initials=JD

    With this query condition, records of users who meet either of the following conditions are reconciled:

    • The user's first name is John or last name is Doe.

    • The user's initials are JD.

If you do not specify values for the CustomizedReconQuery parameter, then all the records in the target system are compared with existing Oracle Identity Manager records during reconciliation.

The following are guidelines to be followed while specifying a value for the CustomizedReconQuery parameter:

  • For the Microsoft Active Directory attributes, you must use the same case (uppercase or lowercase) as given in the table shown earlier in this section. This is because the attribute names are case-sensitive.

  • You must not include unnecessary blank spaces between operators and values in the query condition.

    A query condition with spaces separating values and operators would yield different results as compared to a query condition that does not contain spaces between values and operators. For example, the output of the following query conditions would be different:

    givenname=John&sn=Doe

    givenname= John&sn= Doe

    In the second query condition, the reconciliation engine would look for first name and last name values that contain a space at the start.

  • You must not include special characters other than the equal sign (=), ampersand (&), and vertical bar (|) in the query condition.

    Note:

    An exception is thrown if you include special characters other than the equal sign (=), ampersand (&), and vertical bar (|).

You specify a value for the CustomizedReconQuery parameter while performing the procedure described in the "Defining IT Resources" section.

Batched Reconciliation

During a reconciliation run, all changes in the target system records are reconciled into Oracle Identity Manager. Depending on the number of records to be reconciled, this process may require a large amount of time. In addition, if the connection breaks during reconciliation, then the process would take longer to complete.

You can configure batched reconciliation to avoid such problems.

To configure batched reconciliation, you must specify values for the following user reconciliation scheduled task attributes:

  • StartRecord: Use this attribute to specify the record number from which batched reconciliation must begin.

  • BatchSize: Use this attribute to specify the number of records that must be included in each batch.

  • NumberOfBatches: Use this attribute to specify the total number of batches that must be reconciled. If you do not want to use batched reconciliation, specify All Available as the value of this attribute.

    Note:

    If you specify All Available as the value of this attribute, then the values of the StartRecord and BatchSize attributes are ignored.

You specify values for these attributes by following the instructions described in the "User Reconciliation Scheduled Task" section.

After you configure batched reconciliation, if reconciliation fails during a batched reconciliation run, then refer to the log file for information about the batch at which reconciliation has failed.

Configuring the Reconciliation Scheduled Tasks

When you perform the procedure described in the "Step 5: Importing the Connector XML Files" section, the scheduled tasks for lookup fields and user reconciliations are automatically created in Oracle Identity Manager. To configure these scheduled tasks:

  1. Open the Oracle Identity Manager Design Console.

  2. Expand the Xellerate Administration folder.

  3. Select Task Scheduler.

  4. Click Find. The details of the predefined scheduled tasks are displayed on two different tabs.

  5. For the first scheduled task, enter a number in the Max Retries field. This number represents the number of times Oracle Identity Manager must attempt to complete the task before assigning the ERROR status to the task.

  6. Ensure that the Disabled and Stop Execution check boxes are not selected.

  7. In the Start region, double-click the Start Time field. From the date-time editor that is displayed, select the date and time at which you want the task to run.

  8. In the Interval region, set the following schedule parameters:

    • To set the task to run on a recurring basis, select the Daily, Weekly, Recurring Intervals, Monthly, or Yearly option.

      If you select the Recurring Intervals option, then you must also specify the time interval at which you want the task to run on a recurring basis.

    • To set the task to run only once, select the Once option.

  9. Provide values for the attributes of the scheduled task. Refer to the "Specifying Values for the Scheduled Task Attributes" section for information about the values to be specified.

    See Also:

    Oracle Identity Manager Design Console Guide for information about adding and removing task attributes
  10. Click Save. The scheduled task is created. The INACTIVE status is displayed in the Status field, because the task is not currently running. The task is run at the date and time that you set in Step 7.

  11. Repeat Steps 5 through 10 to create the second scheduled task.

Specifying Values for the Scheduled Task Attributes

This section provides information about the attribute values to be specified for the following scheduled tasks:

Lookup Fields Reconciliation Scheduled Task

You must specify values for the following attributes of the ADGroupLookupReconTask scheduled task.

Note:

  • Attribute values are predefined in the connector XML file that you import. Specify values only for those attributes that you want to change.

  • Values (either default or user-defined) must be assigned to all the attributes. If even a single attribute value were left empty, then reconciliation would not be performed.

Attribute Description Default/Sample Value
Server IT resource instance name of the Microsoft Active Directory server AD Server
LookupCodeName Lookup code that contains all the reconciled group names and the corresponding objectGUIDs Lookup.ADReconliation.GroupLookup

After you specify values for these scheduled task attributes, proceed to Step 10 of the procedure to create scheduled tasks.

User Reconciliation Scheduled Task

You must specify values for the following attributes of the ActiveDirectoryReconTask scheduled task.

Note:

  • Attribute values are predefined in the connector XML file that you import. Specify values only for those attributes that you want to change.

  • Values (either default or user-defined) must be assigned to all the attributes. If even a single attribute value were left empty, then reconciliation would not be performed.

Attribute Description Default/Sample Value
DeleteRecon Specifies whether or not Delete reconciliation is enabled

The value can be True or False. You must specify a value for this attribute.

True
UseFieldMapping Specifies whether or not field mappings from the FieldLookupCode attribute must be used

This attribute is used to enable the reconciliation of specific fields. The value can be True or False.

True
FieldLookupCode Name of the lookup definition that is used for custom reconciliation

This attribute is valid only when the UseFieldMapping attribute is set to True.

Lookup.ADReconciliation.FieldMap
MaintainHierarchy Specifies whether or not organization hierarchy must be maintained in Microsoft Active Directory

The value can be True or False. You must specify a value for this attribute.

True
XellerateObject Name of the Xellerate User resource object in Oracle Identity Manager on which trusted source reconciliation is to be performed

If you want trusted source reconciliation to be performed, then change the value to Xellerate User. Otherwise, change the value to False.

You must specify a value for this attribute.

Xellerate User
Object Name of the AD User resource object in Oracle Identity Manager on which reconciliation is performed

If you want AD User reconciliation to be performed, then change the value to AD User. Otherwise, change the value to False.

You must specify a value for this attribute.

AD User
Server Name of the IT resource representing the Microsoft Active Directory server

You must specify a value for this attribute.

AD Server
TransformLookupCode Lookup code used for the transformation class map kept in the lookup tables

This attribute is valid only when the UseTransformMapping attribute is set to True.

Lookup.ADReconciliation.TransformationMap
UseTransformMapping Specifies whether or not transform mappings accessed by using the TransformLookupCode attribute must be used

The value can be True or False.

True
XellerateOrg Oracle Identity Manager organization in which reconciled users are to be created

You must specify a value for this attribute.

Xellerate Users
MultiValueAttributes Comma-delimited list of all the multivalued Microsoft Active Directory attributes that must be reconciled

For AD Group reconciliation, enter memberOf.

You must specify a value for this attribute.

memberOf
GroupObject Name of the AD Group resource object in Oracle Identity Manager on which group reconciliation is being performed

If you want AD Group reconciliation to be performed, then change the value to AD Group. Otherwise, change the value to False.

You must specify a value for this attribute.

AD Group
StartRecord Specifies the start record for batching process

The default value is 0.

This attribute is also discussed in the "Batched Reconciliation" section.

1
BatchSize Specifies how many records must be there in a batch

The default value is 0.

This attribute is also discussed in the "Batched Reconciliation" section.

3
NumberOfBatches Specifies the number of batches that must be reconciled

If you specify the default value (All Available), then batched reconciliation is not performed.

This attribute is also discussed in the "Batched Reconciliation" section.

Default value: All Available (for reconciling all the users)

Sample value: 50


After you specify values for these scheduled task attributes, proceed to Step 10 of the procedure to create scheduled tasks.

Enabling Reconciliation in Oracle Identity Manager Release 9.0.1

If you are using Oracle Identity Manager release 9.0.1, then you must perform the following procedure to enable reconciliation:

See Also:

Oracle Identity Manager Design Console Guide
  1. Open the Design Console.

  2. Expand the Process Management folder.

  3. Open the Process Definition form for the AD User.

  4. Click the Reconciliation Field Mappings tab.

  5. For each field that is of the IT resource type:

    1. Double-click the field to open the Edit Reconciliation Field Mapping window for that field.

    2. Deselect Key Field for Reconciliation Matching.

Adding Custom Attributes for Reconciliation

Note:

This section describes an optional procedure. You need not perform this procedure if you do not want to add new attributes for provisioning.

By default, the attributes listed in the "Reconciliation Module" section are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can map additional attributes for reconciliation.

To add a custom attribute for reconciliation:

See Also:

Oracle Identity Manager Design Console Guide for detailed information about these steps
  1. Open the Oracle Identity Manager Design Console.

  2. Expand the Xellerate Administration folder.

  3. Double-click Lookup Definition.

  4. Search for the Lookup.ADReconciliation.FieldMap lookup definition by entering the name in the Code field and then clicking the Query icon.

  5. To open the Lookup.ADReconciliation.FieldMap field map, double-click Lookup.ADReconciliation.FieldMap.

  6. Add the required fields to the Lookup.ADReconciliation.FieldMap field map.

    The following fields are provided by default in the Lookup.ADReconciliation.FieldMap field map:

    • memberOf

    • instanceType

    • Organization

    • givenName

    • sAMAccountName

    • IT Resource

    • objectGUID

    • name

    • sn

    • cn

    • whenChanged (This is a mandatory field; it must be present in the field map)

    • distinguishedName

    • initials

    • displayName

    • Employee Type

    • userAccountControl

    • User Type

Configuring Provisioning

As mentioned earlier in this guide, provisioning involves creating or modifying a user's account information on the target system through Oracle Identity Manager. Refer to the "Supported Functionality" section for a listing of the provisioning functions that are available with this connector.

Note:

You must perform the procedure described in this section if you want to use the provisioning features of the connector.

Configuring provisioning involves compiling the adapters that are used to implement provisioning functions.

See Also:

The "Supported Functionality" section for a listing of the provisioning functions that are available with this connector

The following adapters are imported into Oracle Identity Manager when you import the connector XML file:

You must compile these adapters before they can be used in provisioning operations.

To compile adapters by using the Adapter Manager form:

  1. Open the Adapter Manager form.

  2. To compile all the adapters that you import into the current database, select Compile All.

    To compile multiple (but not all) adapters, select the adapters you want to compile. Then, select Compile Selected.

    Note:

    Click Compile Previously Failed to recompile only those adapters that were not compiled successfully. Such adapters do not have an OK compilation status.
  3. Click Start. Oracle Identity Manager compiles the selected adapters.

  4. If Oracle Identity Manager is installed in a clustered environment, then copy the compiled adapters from the OIM_home/xellerate/Adapter directory to the same directory on each of the other nodes of the cluster. If required, overwrite the adapter files on the other nodes.

If you want to compile one adapter at a time, then use the Adapter Factory form.

See Also:

Oracle Identity Manager Tools Reference Guide for information about using the Adapter Factory and Adapter Manager forms

To view detailed information about an adapter:

  1. Highlight the adapter in the Adapter Manager form.

  2. Double-click the row header of the adapter, or right-click the adapter.

  3. Select Launch Adapter from the shortcut menu that is displayed. Details of the adapter are displayed.

Adding Custom Attributes for Provisioning

Note:

This section describes an optional procedure. You need not perform this procedure if you do not want to add new attributes for provisioning.

By default, the attributes listed in the "Provisioning Module" section are mapped for provisioning between Oracle Identity Manager and the target system. If required, you can map additional attributes for provisioning.

To add a custom attribute for provisioning:

See Also:

Oracle Identity Manager Design Console Guide for detailed information about these steps
  1. Add the attribute as a field in the UD_ADUSER or UD_ADGRP process form.

  2. Add the attribute in the AtMap.AD or AtMap.ADGroup lookup definition.

Configuring the Connector for Oracle Identity Manager Release 9.0.1.3

Note:

You must perform this procedure only if you are using Oracle Identity Manager release 9.0.1.3.

In Oracle Identity Manager release 9.0.1.3, user accounts that are disabled or enabled are not reconciled correctly into Oracle Identity Manager during nontrusted (target resource) reconciliation. If you are using this release of Oracle Identity Manager, then you must perform the following procedure to resolve this problem:

  1. Log in to the Design Console.

  2. Create the userAccountControl reconciliation field in the AD User resource object as follows:

    1. Expand the Resource Management folder.

    2. Open the Resource Objects form.

    3. Click the Search button.

    4. From the list of resource objects that is displayed, double-click AD User.

    5. On the Object Reconciliation tab, select the Reconciliation Fields tab.

    6. On the Reconciliation Fields tab, click Add Field and then enter the following values:

      • Field Name: Enter userAccountControl.

      • Field Type: Select String.

      • Required: Select this check box.

    7. Save the changes.

  3. Map the userAccountControl reconciliation field to the OIM_OBJECT_STATUS field as follows:

    1. Expand the Process Management folder.

    2. Open the Process Definition form.

    3. Click the Search button.

    4. From the list of process definitions that is displayed, double-click the AD User process definition.

    5. On the Reconciliation Field Mappings tab, double-click userAccountControl and then enter the following values:

      • Field Name: Select userAccountControl.

      • Field Type: Select String.

      • Process Data Field: Enter OIM_OBJECT_STATUS.

    6. Save the changes.

Configuring the Connector for Multiple Installations of the Target System

Note:

Perform this procedure only if you want to configure the connector for multiple installations of Microsoft Active Directory.

You may want to configure the connector for multiple installations of Microsoft Active Directory. The following example illustrates this requirement:

The Tokyo, London, and New York offices of Acme Multinational Inc. have their own installations of Microsoft Active Directory. The company has recently installed Oracle Identity Manager, and they want to configure Oracle Identity Manager to link all the installations of Microsoft Active Directory.

To meet the requirement posed by such a scenario, you must configure the connector for multiple installations of Microsoft Active Directory.

To configure the connector for multiple installations of the target system:

  1. Create and configure one IT resource for each target system installation.

    The IT Resources form is in the Resource Management folder. An IT resource is created when you import the connector XML file. You can use this IT resource as the template for creating the remaining IT resources, of the same resource type.

  2. Configure reconciliation for each target system installation. Refer to the "Configuring Reconciliation" section for instructions. Note that you only need to modify the attributes that are used to specify the IT resource and to specify whether or not the target system installation is to be set up as a trusted source.

    You can designate either a single or multiple installations of Microsoft Active Directory as trusted sources.

  3. If required, modify the fields to be reconciled for the Xellerate User resource object.

See Also:

Oracle Identity Manager Design Console Guide for detailed instructions on performing each step of this procedure

When you use the Administrative and User Console to perform provisioning, you can specify the IT resource corresponding to the Microsoft Active Directory installation to which you want to provision the user.

Configuring the Connector and Password Synchronization Module

The connector for Microsoft Active Directory performs the following functions:

The password synchronization module for Microsoft Active Directory updates Oracle Identity Manager with passwords changed in Microsoft Active Directory.

The connector is deployed on the Oracle Identity Manager server, and the password synchronization module is deployed on the Microsoft Active Directory server. When they are deployed together (along with LDAP over SSL), the connector and the password synchronization module provide full, bidirectional synchronization of all user attributes, including passwords.

See Also:

Oracle Identity Manager Password Synchronization Module for Microsoft Active Directory Installation and Configuration Guide

The instructions in this section are aimed at solving a problem that was observed in release 9.0.3 of the connector and password synchronization module.

Creating a Custom Attribute in Microsoft Active Directory to Track Password Changes

You must create a custom attribute in Microsoft Active Directory to act as a flag for tracking password changes initiated by Oracle Identity Manager.

The following sections describe this procedure:

Ensuring That the Microsoft Active Directory Schema Snap-In Is Installed

The Microsoft Active Directory Schema snap-in is required to create a custom attribute. Before you can create the custom attribute, you must ensure that this snap-in is installed.

To check if the snap-in is installed:

  1. On the Microsoft Active Directory server, click Start and then click Run.

  2. Enter the following command, and then click OK:

    mmc /a
    
    

If the Microsoft Active Directory Schema snap-in is already installed, then its console is displayed when you run this command.

If the console is not displayed, then you must install the Microsoft Active Directory Schema snap-in as follows:

  1. Log in to the Microsoft Active Directory server as the administrator.

  2. Insert the Windows 2000 Server compact disc into your compact disc drive, and then click Browse this CD.

  3. Double-click the I386 folder, double-click Adminpak, and then follow the instructions displayed in the Windows 2000 Administration Tools Setup Wizard.

  4. Open the Microsoft Active Directory Schema snap-in console as follows:

    1. Click Start, and then click Run.

    2. Enter the following command, and then click OK:

      mmc /a
      
      
  5. On the Console menu, click Add/Remove Snap-in and then click Add.

  6. Double-click Active Directory Schema, and then click Close.

  7. To specify that you do not want to add any more snap-ins, click OK.

  8. To save the changes that you make, click Save.

Creating a Custom Attribute

After you ensure that the Microsoft Active Directory Schema snap-in is installed, add the custom attribute in Microsoft Active Directory as follows:

  1. Open the Active Directory Schema snap-in as follows:

    1. On the Microsoft Active Directory server, click Start and then click Run.

    2. Enter the following command, and then click OK:

      mmc /a
      
      
  2. In the console tree, right-click Attributes and then select Create Attribute.

  3. Set the attribute type to Integer.

  4. In the console tree, select Classes.

  5. Right-click User, and then select Properties.

  6. On the Attribute tab, select Add to add the attribute to the "User" class.

Creating a Custom Attribute in Oracle Identity Manager

You must create a custom attribute in Oracle Identity Manager to act as a flag for tracking password changes initiated by Microsoft Active Directory.

To create a custom attribute (user-defined field) in Oracle Identity Manager:

See Also:

Oracle Identity Manager Design Console Guide
  1. Open the Design Console.

  2. Expand the Administration folder.

  3. Select User Defined Field Definition.

  4. Click the Search icon.

  5. Select USR from the results that are displayed, and then click Add.

  6. In the User Defined Fields dialog box, enter the following values:

    • Label: Enter a label for the field. For example: PWDCHANGEDINDICATION

    • Field Size: 20

      The user-defined field that you create will hold either ADSYNC_TRUE or ADSYNC_FALSE.

    • DataType: String

    • Column Name: Enter a column name for the field.

      It is recommended that you enter the same value as that you enter in the Label field. For example: PWDCHANGEDINDICATION

      Oracle Identity Manager automatically appends USR_UDF_ to the column name that you specify. So, for example, if you specify PWDCHANGEDINDICATION as the column name, then the actual column name is changed to USR_UDF_PWDCHANGEDINDICATION.

  7. Click Save.

Specifiying Values for IT Resource Parameters

While performing the procedure described in the "Defining IT Resources" section, you must specify values for the following parameters:

  • AD Sync installed (yes/no)

    If you are going to install and use the Microsoft Active Directory Password Synchronization module, then specify yes as the value of this parameter. Otherwise, specify no. The default value is no.

  • OIM User UDF

    Specify the name of the user-defined field that you create in Oracle Identity Manager.

    You must specify a value for this parameter only if you specify yes as the value of the AD Sync installed (yes/no) parameter.

    Note: You must specify the column name and not the field label that you enter while adding the custom attribute in Oracle Identity Manager. For example, if you enter the label PWDCHANGEDINDICATION, then the column name that you must specify is USR_UDF_PWDCHANGEDINDICATION. Oracle Identity Manager adds the USR_UDF_ prefix while creating a column.

  • Custom Attribute Name

    Specify the name of the custom attribute that you create in Microsoft Active Directory.

    You must specify a value for this parameter only if you specify yes as the value of the AD Sync installed (yes/no) parameter.

Sequence of Events That Occur During a Password Change

This section describes the sequence of events that take place during a password change operation.

Suppose user John Doe changes his password in Microsoft Active Directory. This action initiates the following sequence of events:

  1. The password synchronization module changes the user's password in Oracle Identity Manager.

  2. The password synchronization module changes the value of the Oracle Identity Manager user-defined field to ADSYNC_TRUE.

  3. Because the value of the Oracle Identity Manager user-defined field is ADSYNC_TRUE, the Password Updated process task does not change the password in Microsoft Active Directory.

  4. The password synchronization module changes the value of the Oracle Identity Manager user-defined field back to ADSYNC_FALSE.

Suppose user Jane Doe changes her password in Oracle Identity Manager. This action initiates the following sequence of events:

  1. The Password Updated process task changes the user's password in Microsoft Active Directory.

  2. The Password Updated process task changes the value of the Microsoft Active Directory custom attribute to 1.

  3. Because the value of the Microsoft Active Directory custom attribute is 1, the password synchronization module does not change the password in Oracle Identity Manager.

  4. The Password Updated process task changes the value of the Microsoft Active Directory custom attribute back to 0.

Configuring the xlconfig.xml File for the Password Synchronization Module

After you install the Microsoft Active Directory connector, you must make changes in the xlconfig.xml of the password synchronization to reflect the properties of the connector.

This is part of the installation procedure for the password synchronization module. It is described in the "Configuring the xlconfig.xml File After Installing the Connector" of Oracle Identity Manager Password Synchronization Module for Microsoft Active Directory Installation and Configuration Guide.