Install the Active Directory password synchronization plugin

The following steps install the password synchronization plugin on an Active Directory server:

Download the Active Directory password synchronization plugin.

Launch the installation wizard using one of the following methods:

In Windows Explorer, double-click the ad-passwordchange-handler-1.7.0.exe file.

From a Powershell command-line, enter the executable name (.\ad-passwordchange-handler-1.7.0.exe), and press Enter.

When starting the installation wizard from the command-line, the following options are available:

To save the settings in a configuration file, use the /saveinf switch:

PS C:\path\to\dir> .\ad-passwordchange-handler-1.7.0.exe /saveinf=C:\temp\adsync.inf

If you have a configuration file with installation parameters, you can install the password plugin in silent mode as follows:
```
PS C:\path\to\dir> .\ad-passwordchange-handler-1.7.0.exe /verysilent /loadinf=C:\temp\adsync.inf
```

In the Setup - OpenIDM Password Sync window, on the License Agreement page, you must accept the license agreement to continue, and then click Next.

Show Me

On the OpenIDM Information: Connection page, enter the applicable information in the following fields, and click Next.

Show Me

OpenIDM URL

The URL where IDM is deployed, including the query that targets each user account. For example:

https://localhost:8444/openidm/managed/user?_action=patch&_queryFilter=userName+eq+'${samaccountname}'

OpenIDM User Password attribute

The password attribute for the managed/user object, such as adPassword.

If the password attribute does not exist in the IDM managed/user object, the password sync service will return an error when it attempts to replay a password update that has been made in Active Directory. If your managed user objects do not include passwords, you can add an onCreate script to the Active Directory > Managed Users mapping that sets an empty password when managed user accounts are created. The following excerpt of a sample sync.json file shows such a script in the mapping:

"mappings" : [
    {
        "name" : "systemAdAccounts_managedUser",
        "source" : "system/ad/account",
        "target" : "managed/user",
        "properties" : [
            {
                "source" : "sAMAccountName",
                "target" : "userName"
            }
        ],
        "onCreate" : {
            "type" : "text/javascript",
            "source" : "target.password=''"
        },
        ...
    }
]

The onCreate script creates an empty password in the managed/user object, so that the password attribute exists and can be patched.

On the OpenIDM Information: Authentication page, enter the applicable information in the following fields, and click Next.

Show Me

User name

An administrative user that can authenticate to IDM. For example, openidm-admin.

Password

The above, specified user’s password.

OAuth2 Access Token URL

If you are using the authentication type OAuth2 Access Token, enter the token URL. For example:

https://am.example.com/am/oauth2/realms/root/access_token

OAuth2 Scope

If you are using the authentication type OAuth2 Access Token, enter the OAuth2 token scope. For example fr:idm:*.

Select authentication type

Select the authentication type that Active Directory will use to authenticate to IDM:

To use plain HTTP authentication, select OpenIDM Header.
To use mutual SSL authentication, select Certificate.
To use AM bearer tokens, select OAuth2 Access Token.

If you selected Certificate as the authentication type, complete this step; otherwise, skip to the next step.

On the OpenIDM Information: Certificate Authentication page, enter the applicable information in the following fields, and click Next.

Show Me

Select Certificate file...

Browse to select the certificate file that Active Directory will use to authenticate to IDM.

The certificate file must be configured with an appropriate encoding, cryptographic hash function, and digital signature. The password synchronization plugin can read a public or a private key from a PKCS #12 archive file.

For production purposes, you should use a certificate that has been issued by a certificate authority. For testing purposes, you can generate a self-signed certificate.

You must also import the certificate into the IDM keystore.jceks file. On the machine that is running IDM, enter the following command:

keytool \
-importkeystore \
-srckeystore /path/to/ad-pwd-plugin-localhost.p12 \
-srcstoretype PKCS12 \
-destkeystore keystore.jceks \
-deststoretype JCEKS

Private key alias

The certificate alias, such as ad-pwd-plugin-localhost. The password sync plugin sends the alias when communicating with IDM, which uses the alias to retrieve the corresponding private key in IDM’s keystore.

Update the IDM secret store (conf/secrets.json) to add this certificate alias to the idm.default secretId:

{
    "stores" : [
        {
            "name" : "mainKeyStore",
            "class" : "org.forgerock.openidm.secrets.config.KeyStoreSecretStore",
            "config" : {
            ...
            "mappings" : [
                {
                    "secretId" : "idm.default",
                    "types" : [
                        "ENCRYPT",
                        "DECRYPT"
                    ],
                    "aliases" : [
                        "&{openidm.config.crypto.alias|openidm-sym-default}",
                        "ad-pwd-plugin-localhost"
                    ]
                },
            ...
            ]
            }
        },
        ...
    ],
    ...
}

For more information about secret stores, refer to Secret stores.

Password to open certificate file

The keystore password (changeit, in the previous example).

On the Password Encryption page, enter the applicable information in the following fields, and click Next.

Show Me

Select Certificate file...

Browse to select the certificate that will be used for password encryption. The certificate format must be PKCS #12.

The certificate file must be configured with an appropriate encoding, cryptographic hash function, and digital signature. The plugin can read a public or a private key from a PKCS #12 archive file.

For production purposes, you should use a certificate that has been issued by a certificate authority. For testing purposes, you can generate a self-signed certificate.

You must also import the certificate into the IDM truststore. On the machine that is running IDM, enter the following command:

keytool \
 -importkeystore \
 -srckeystore /path/to/ad-pwd-plugin-localhost.p12 \
 -srcstoretype PKCS12 \
 -destkeystore truststore \
 -deststoretype JKS

Private key alias

Update the IDM secret store (conf/secrets.json) to add this certificate alias to the idm.default secretId:

"mappings": [
    {
        "secretId": "idm.default",
        "types": [ "ENCRYPT", "DECRYPT" ],
        "aliases": [ "&{openidm.config.crypto.alias|openidm-sym-default}", "ad-pwd-plugin-localhost" ] },
        ...
    }
]

For more information about secret stores, refer to Secret stores.

Password to open certificate file

The password to access the PFX keystore file, such as changeit, from the previous example.

Select encryption...

The encryption standard to use when encrypting the password value (AES-128, AES-192, or AES-256).

On the Data Storage page, enter the applicable information in the following fields, and click Next.

Show Me

Select the folder in which Service will store its output data files

Browse to select the folder for data output files. The server should prevent access to this folder except for the Password Sync service.

The path name cannot include spaces.

Directory poll interval (seconds)

The number of seconds between calls to check whether IDM is available. For example, 60, to poll IDM every minute.

On the Log Storage page, enter the applicable information in the following fields, and click Next.

Show Me

Select the folder in which Service will store its log files

Browse to select the folder for log files.

The path name cannot include spaces.

Select logging level

The severity of messages to log: error, info, warning, fatal, or debug.

On the Select Destination Location page, browse to select the installation folder (default C:\Program Files\OpenIDM Password Sync), and click Next.

Show Me
On the Ready to Install page, verify the details are acceptable, and click Install to continue. If you need to change any installation options, click Back.

Show Me
On the Completing the OpenIDM Password Sync Setup Wizard page, select one of the following, and click Finish:

Show Me
- Yes, restart the computer now
- No, I will restart the computer later
  
  If you select this option, you must restart the computer before you continue.
If you selected Certificate as the authentication type during setup, complete Add a Certificate to the Windows Certificate Store; otherwise, your setup is now complete.

Password synchronization should now be configured and working. To test that the setup was successful, change a user password in Active Directory. That password should be synchronized to the corresponding IDM managed user account, and you should be able to query the user’s own entry in IDM using the new password.

Generate a self-signed certificate

For production purposes, you should use a certificate that has been issued by a certificate authority. For testing purposes, you can generate a self-signed certificate.

On the Active Directory host, generate a private key, which will be used to generate a self-signed certificate with the alias ad-pwd-plugin-localhost:

> keytool.exe ^
 -genkey ^
 -alias ad-pwd-plugin-localhost ^
 -keyalg rsa ^
 -dname "CN=localhost, O=AD-pwd-plugin Self-Signed Certificate" ^
 -keystore keystore.jceks ^
 -storetype JCEKS
Enter keystore password:changeit
Re-enter new password: changeit
Enter key password for <ad-pwd-plugin-localhost>
      <RETURN if same as keystore password>

Now use the private key, stored in the keystore.jceks file, to generate the self-signed certificate:

> keytool.exe ^
 -selfcert ^
 -alias ad-pwd-plugin-localhost ^
 -validity 365 ^
 -keystore keystore.jceks ^
 -storetype JCEKS ^
 -storepass changeit

Export the certificate. In this case, the keytool command exports the certificate in a PKCS #12 archive file format, used to store a private key with a certificate:

> keytool.exe ^
 -importkeystore ^
 -srckeystore keystore.jceks ^
 -srcstoretype jceks ^
 -srcstorepass changeit ^
 -srckeypass changeit ^
 -srcalias ad-pwd-plugin-localhost ^
 -destkeystore ad-pwd-plugin-localhost.p12 ^
 -deststoretype PKCS12 ^
 -deststorepass changeit ^
 -destkeypass changeit ^
 -destalias ad-pwd-plugin-localhost ^
 -noprompt

The PKCS #12 archive file is named ad-pwd-plugin-localhost.p12. Import the contents of the keystore contained in this file to the system that hosts IDM. To do so, import the PKCS #12 file into the IDM keystore file, named truststore , in the /path/to/openidm/security directory.

Add a certificate to the Windows certificate store

If you selected Certificate as the authentication type during setup, you must complete this procedure.

The Password Sync Service uses Windows certificate stores to verify IDM’s identity. The certificate that IDM uses must therefore be added to the list of trusted certificates on the Windows machine.

In a production environment, use a certificate that has been issued by a certificate authority. For test purposes, you can use the self-signed certificate that is generated by IDM on first startup.

To add the IDM certificate to the list of trusted certificates, use the Microsoft Management Console:

Click the Start Menu, type mmc, and click mmc Run Command.
In the Console window, select File > Add/Remove Snap-in.
From the Available snap-ins area, select Certificates, and click Add >.
In the Certificates snap-in window, select My user account, and click Finish.
From the Available snap-ins area, select Certificates, and click Add >.
In the Certificates snap-in window, select Service account, and click Next >.
In the Select Computer window, select Local Computer, and click Next >.
In the Cerificates snap-in window, select the service account OpenIDM Password Sync Service, and click Finish.
From the Available snap-ins area, select Certificates, and click Add >.
In the Certificates snap-in window, select Computer account, and click Next >.
In the Select Computer window, select Local Computer, and click Finish.
In the Add or Remove Snap-ins window, verify that you have three certificates in the Selected snap-ins area, and click OK. If you are missing any certificates, please review the earlier steps in this procedure, and add the missing certificate(s).

For each of the following nodes, import the certificate, as follows:

List of Nodes
Certificates - Current User > Personal
Certificates - Current User > Trusted Root Certification Authorities
Certificates - Service > OpenIDM Password Sync\Personal
Certificates - Service > OpenIDM Password Sync\Trusted Root Certification Authorities
Certificates > Local Computer > Personal
Certificates > Local Computer > Trusted Root Certification Authorities

Expand the node, and select the appropriate item. For example, Certificates - Current User > Personal:
From the menu bar, select Action > All Tasks > Import.
In the Certificate Import Wizard window, click Next.
On the File to Import page, click Browse, locate the IDM certificate, and then click Next. If you exported IDM’s self-signed certificate, the certificate is openidm-localhost.crt.
On the Certificate Store page, leave the default option selected, and click Next. For example:
On the final page of the wizard, review the details, and click Finish. For example:
The Certificate Import Wizard window displays the success or failure of the import, click OK.

The main window of the Microsoft Management Console now displays the added certificate in a sub-node. For example:

Make sure to repeat this sub-procedure for all required nodes.

PingIDM 7.5.0

Install the Active Directory password synchronization plugin

Generate a self-signed certificate

Add a certificate to the Windows certificate store