About the Connector

1.1 Connectors for Microsoft Active Directory

Oracle Identity Manager provides the following connectors for integration with Microsoft Active Directory:

The user management connector can be configured to run in either the identity reconciliation (trusted source) mode or the account management (target resource) mode.

In the identity reconciliation mode, Microsoft Active Directory is used as the trusted source and users are directly created and modified on it. During reconciliation from the trusted source, the user management connector fetches data about these target system users into Oracle Identity Manager. This data is used to create or update the corresponding OIM Users.

In the account management mode, Microsoft Active Directory is used as a target resource. During reconciliation from the target resource, the user management connector fetches into Oracle Identity Manager data about users created or modified directly on the target system. This data is used to add or modify resources allocated to OIM Users. In addition, the connector enables provisioning operations through which user data changes are propagated from Oracle Identity Manager to Microsoft Active Directory.
The password synchronization connector propagates password changes from Microsoft Active Directory to Oracle Identity Manager.

Depending on your business requirements, you can deploy one or both of these connectors to integrate Oracle Identity Manager with Microsoft Active Directory.

1.2 Functionality of the Microsoft Active Directory User Management and Password Synchronization Connectors

Table 1-1 describes the functionality of the user management and password synchronization connectors.

Event	Action Performed by the Connector
Trusted source reconciliation from Active Directory	Only user management connector installed: User data from Active Directory is matched with OIM Users Only password synchronization connector installed: NA Both user management and password synchronization connectors installed: The user management connector propagates user data changes (except for password changes) from Active Directory to the corresponding OIM Users. The password synchronization connector propagates password changes from Active Directory to the corresponding OIM Users.
Target resource reconciliation from Active Directory	Only user management connector installed: User data from Active Directory is matched with the Active Directory resource assigned to OIM Users Only password synchronization connector installed: NA Both user management and password synchronization connectors installed: The user management connector propagates user data changes (except for password changes) from Active Directory to the Active Directory resource assigned to OIM Users. The password synchronization connector propagates password changes from Active Directory to the corresponding OIM Users.
OIM User's password changed	Only user management connector installed and configured for the target resource mode: Depending upon the value of the Allow Password Provisioning IT resource parameter, the user management connector propagates to Active Directory and other resources allocated to the OIM User, password changes made to OIM Users. The Allow Password Provisioning parameter is an IT resource parameter for the user management connector. If you set this parameter to `yes`, then Oracle Identity Manager propagates the password change to all of the resources allocated (provisioned) to the OIM User. If you set this parameter to `no,` then Oracle Identity Manager does not propagate the password change to all of the resources allocated (provisioned) to the OIM User. Note: This applies only if pre-populate adapters have been configured to propagate passwords from OIM Users to the resources. Note: This does not apply to release 11.1.1.x of the connector. Only password synchronization connector installed: NA Both user management (configured for target resource mode) and password synchronization connectors installed: Same as what happens when the user management connector is installed and configured for the target resource mode. The password synchronization connector is not used here as this is a provisioning operation.
Password changed on Active Directory	Only user management connector installed: Passwords changed on Active directory are not propagated to Oracle Identity Manager Only password synchronization connector installed: Passwords changed on Active directory are propagated to Oracle Identity Manager Both user management and password synchronization connectors installed: Passwords changed on Active directory are propagated to Oracle Identity Manager

1.3 Certified Components

Table 1-2 lists the certified components for this connector.

Table 1-2 Certified Components

Item	Requirement
Oracle Identity Governance or Oracle Identity Manager	You can use one of the following releases of Oracle Identity Governance or Oracle Identity Manager: Oracle Identity Governance 12c (12.2.1.4.0) Oracle Identity Governance 12c (12.2.1.3.0) Oracle Identity Manager 11g Release 2 PS3 (11.1.2.3.0) Oracle Identity Manager 11g release 2 PS2 (11.1.2.2.0) and any later BP in this release track Oracle Identity Manager 11g release 2 PS1 (11.1.2.1.0) and any later BP in this release track Oracle Identity Manager 11g release 2 BP02 (11.1.2.0.2) and any later BP in this release track Note: In this guide, Oracle Identity Manager release 11.1.2.x has been used to denote all releases in the Release 2 track listed here, and future releases in the 11.1.2.x series that the connector supports. Oracle Identity Manager 11g release 1 PS2 (11.1.1.7.0) and any later BP in this release track Oracle Identity Manager 11g release 1 PS1 (11.1.1.5.0) and any later BP in this release track Oracle Identity Manager 11g release 1 (11.1.1.3.0) and any later BP in this release track Note: In this guide, Oracle Identity Manager release 11.1.1 has been used to denote Oracle Identity Manager 11g Release 1 (11.1.1). Oracle Identity Manager release 9.1.0.0 and any later BP in this release track Note: In this guide, Oracle Identity Manager release 9.1.0.x has been used to denote Oracle Identity Manager release 9.1.0.0 and future releases in the 9.1.0.x series that the connector supports.
Target systems	The target system can be any one of the following: Microsoft Active Directory 2003 (x86 or x64) Microsoft Active Directory 2008 (x86 or x64) Microsoft Active Directory 2008 R2 (x86 or x64) Microsoft Active Directory 2012 (x64) Microsoft Active Directory 2012 R2 (x64) Microsoft Active Directory 2016 (x64) Microsoft Active Directory 2019 (x64) Microsoft Active Directory 2022 (x64) Note: The minimum supported Microsoft Active Directory Password Synchronization connector one-off patch version is 9.1.1.5.17 (that is, patch 30856343). Ensure that you apply the one-off patch release 9.1.1.5.17 (that is, patch 30856343) by downloading it from My Oracle Support.
Other software	The following is the software that the computer hosting the Microsoft Active Directory domain controller on which you want to install the connector must be able to access: For Oracle Identity Manager release 9.1.0.x: SPML Web Service For Oracle Identity Manager release 11.1.1, 11.1.2.x, or 12c: SPML-DSML Service
Other consideration	The target system host computer must be able to ping the application server host using both IP address and host name.

1.4 Guidelines on Using the Connector

The following are the guidelines on using the connector:

If Microsoft Active Directory is the only authoritative source for passwords in your operating environment, then it is recommended not to propagate passwords from Oracle Identity Manager to Microsoft Active Directory.
If Oracle Identity Manager is the only authoritative source for passwords in your operating environment, then do not install the password synchronization connector.
If both Oracle Identity Manager and Microsoft Active Directory can function as authoritative sources for passwords in your operating environment, then the password policies set on Oracle Identity Manager and Microsoft Active Directory must be consistent.

1.5 Connector Architecture

The architecture of the connector is the blueprint for the functionality of the connector.

Figure 1-1 shows the architecture of the password synchronization connector.

Figure 1-1 Architecture of the Password Synchronization Connector

Description of "Figure 1-1 Architecture of the Password Synchronization Connector"

This section describes the connector architecture in the following topics:

1.5.1 Password Synchronization Process

Figure 1-2 shows the sequence of events that occur when the password is propagated from the target system to Oracle Identity Manager.

Figure 1-2 Sequence of Events That Occur During Password Synchronization

Description of "Figure 1-2 Sequence of Events That Occur During Password Synchronization"

The following is the sequence of events that take place during password synchronization:

A user changes the user's password on Microsoft Active Directory. The user can change the password in one of the following ways:
- Using Microsoft Management Console
- Pressing Ctrl+Alt+Del and then using the Change Password option on one of the client computers for the Microsoft Active Directory server
- Using a third-party application or custom utility for changing passwords on Microsoft Active Directory
The password change is successful on Microsoft Active Directory only when the password clears all the password checks on Microsoft Active Directory.
The local security authority (LSA) component of Microsoft Windows intercepts the password change on Microsoft Active Directory and passes the password (in plain-text format) and required user information to the password filter (oimadpwdsync10.dll file). The oimadpwdsync10.dll file is one of the files copied to the target system when you install the password synchronization connector.
The password filter encrypts the password and user information in a password change record and stores this record in the password change record queue.

This queue consists of password change records corresponding to each password change on Microsoft Active Directory. The password change record queue is held in memory, and it is also known as the in-memory queue.
The password update thread is created when the password filter is initialized. This thread performs the following tasks:
1. Picks up a password change record from the in-memory queue or persistent queue.
  
  Note:
  
  The persistent queue is explained later in this section.
2. Decrypts the password change record.
3. Creates and sends an SPML request to Oracle Identity Manager in the form of a SOAP packet.
  
  This SPML request contains the sAMAccountName of the target system user whose password must be updated on Oracle Identity Manager. On Oracle Identity Manager, the sAMAccountName value is compared with the OIM User attribute that you specify while installing the connector.
  
  See Also:
  
  The "SPML Web Service" chapter in Oracle Identity Manager Tools Reference for detailed information about the SPML Web Service

1.5.2 Processes Associated With Events for SPML Requests

The following sections describe the processes associated with each event that may occur when the SPML request is sent:

Note:

The update of a password on the target system does not depend on acceptance of the password by Oracle Identity Manager or the availability of Oracle Identity Manager.

1.5.2.1 First SPML Request Rejected

Oracle Identity Manager rejects the first SPML request if the corresponding OIM User matching the sAMAccountName of the target system user does not exist. If this event occurs, then the following error message is written to the Application log in the Microsoft Windows Event Log:

Unable to update sAMAccountName, the user does not exist in OIM

In addition, the following error message is written to the TIME_STAMPOIMMain.log file:

The user does not exist in OIM

See "Enabling and Disabling Logging" for information about the connector log files.

1.5.2.2 First SPML Request Accepted

Oracle Identity Manager accepts the first SPML request if an OIM User matching the sAMAccountName of the target system user is found. After the OIM User is found:

The SPML Web service sends a success response to the password update thread.
The password update thread sends a second SPML request to the SPML Web service in Oracle Identity Manager. This request contains the password of the OIM User.
The following sections discuss processes associated with each event that may occur when the second SPML request is sent:

1.5.2.2.1 Second SPML Request Rejected

Oracle Identity Manager rejects the second SPML request for one of the following reasons:

The password does not meet password policies set on Oracle Identity Manager

Note:

Password policies set on the target system may not be consistent with password policies set on Oracle Identity Manager.
The password contains special characters that are not supported by Oracle Identity Manager.
The user ID of an OIM User contains characters in the non-native encoding of the Microsoft Active Directory system.

If Oracle Identity Manager rejects the second SPML request, then:

In both scenario, the following error message is written to the Application log in the Microsoft Windows Event Log:
```
Unable to update USER_NAME_OF_THE_OIM_USER. The OIM server rejected the setPasswordRequest. Please check the OIM server log for more details.
```
This error message is also recorded in the TIME_STAMPOIMMain.log file. In addition, the exception stack trace is recorded in the debug log file of Oracle Identity Manager. The stack trace provides details about the reason for the password change rejection. See "Enabling and Disabling Logging" for information about the connector log files.
The SPML Web Service sends an SPML response indicating that the password update operation has failed.
The password change record (contains the password along with the user information in encrypted format) is stored in the persistent queue. This queue is located in the ou=oimpwdsyncDOMAIN_NAME,BASE_DN container of Microsoft Active Directory.
The password update thread increments the retry count for the password change record by one and resends SPML requests to Oracle Identity Manager.

Note:

A value for the retry count is specified during connector installation.
If Oracle Identity Manager accepts the password change, then the password change record is removed from the persistent queue. The rest of the steps mentioned in this section are not performed.
If Oracle Identity Manager rejects the password change, then the password update thread keeps resending SPML requests until the retry count reaches the maximum number of retries.

If Oracle Identity Manager becomes unavailable after it rejects the password and before the maximum number of retries for a rejected password is reached, then:
- The password along with user information is stored in the persistent queue in encrypted format.
- The password update thread attempts to update the password of the corresponding OIM User without incrementing the retry count. When Oracle Identity Manager becomes available, this retry attempt continues and the retry count resumes incrementing from this point onward.
When the retry count reaches the maximum number of retries:
- The password change record is deleted from the persistent queue.
- The following error message is written to the Application log in the Microsoft Windows Event Log:
```
Unable to update USER_NAME_OF_THE_OIM_USER. The OIM server rejected the setPasswordRequest. Please check the OIM server log for more details.
```
  This error message is also recorded in the TIME_STAMPOIMMain.log file. In addition, the exception stack trace is recorded in the debug log file of Oracle Identity Manager. The stack trace provides details about the reason for the password change rejection. See "Enabling and Disabling Logging" for information about the connector log file.

1.5.2.2.2 Second SPML Request Accepted

If Oracle Identity Manager accepts the second SPML request (containing the password change), then the password of the OIM User is updated successfully. The process ends here.

1.5.2.2.3 Oracle Identity Manager Is Not Available

See "Oracle Identity Manager Is Not Available" for information about events that occur if Oracle Identity Manager is not available after the response to the first SPML request is received and before the second SPML request is sent.

1.5.2.3 Oracle Identity Manager Is Not Available

If Oracle Identity Manager is not available at the start of the password synchronization operation, then:

The following error message is written to the Application log in the Microsoft Windows Event Log:
```
Unable to update sAMAccountName. The OIM SPML Web Service is unreachable. Please verify the availability of the web service or the configuration parameters.
```
This error message is also recorded in the TIME_STAMPOIMMain.log file.
The password along with the user information is encrypted and stored in the persistent queue.
The password update thread picks up the password change record from the persistent queue and resends SPML requests to Oracle Identity Manager (without incrementing the retry count).
As long as Oracle Identity Manager is not available, Steps 2 and 3 are repeated until the first SPML request is sent to Oracle Identity Manager.
When Oracle Identity Manager becomes available, the first SPML request is sent. The next set of steps depends on which of the following events takes place:
- First SPML Request Rejected
- First SPML Request Accepted

1.5.3 Password Synchronization Connector in a Multi-Domain Controller Environment

In a multi-domain controller environment, if one of the domain controllers is unavailable and if a Password Change request is sent to it, then the Password Change request is re-routed to a domain controller that is available. The domain controller that is available then sends the password to the OIM User.

Note:

The Password Change request that is stored in the memory queue of a domain controller is lost if that domain controller crashes. If this happens, then the Password Change request cannot be retrieved.

The following example illustrates how the connector works in a multi-domain controller environment:

Suppose the operating environment consists of two domain controllers, DC1 and DC2. If DC1 becomes unavailable and a user for example, John Doe, changes his password on the target system, then the connector on DC2 propagates the new password to the corresponding OIM User.

1.6 Roadmap for Deploying and Using the Connector

The following is the organization of information in the rest of this guide:

Deploying the Connector describes procedures that you must perform on Oracle Identity Manager and the target system during each stage of connector deployment.
Removing the Connector describes the procedure to uninstall the connector.
Troubleshooting the Connector lists solutions to errors that you may encounter while using the connector.
Known Issues and Workarounds lists known issues associated with this release of the connector.
PrepAD.ldif provides information about the PrepAD.ldif file.