6.5. Managing Synchronization Agreements

6.5.1. Creating Synchronization Agreements

Synchronization agreements are created on the IdM server using the ipa-replica-manage connect command because it creates a connection to the Active Directory domain. To establish an encrypted connection to Active Directory, IdM must to trust the Windows CA certificate.
  1. Copy the root certificate authority (CA) certificate to the IdM server:
    1. If your Active Directory CA certificate is self-signed:
      1. Export the Active Directory CA certificate on the Windows server.
        1. Press the Super key+R combination to open the Run dialog.
        2. Enter certsrv.msc and click OK.
        3. Right-click on the name of the local Certificate Authority and choose Properties.
        4. On the General tab, select the certificate to export in the CA certificates field and click View Certificate.
        5. On the Details tab, click Copy to File to start the Certificate Export Wizard.
        6. Click Next, and then select Base-64 encoded X.509 (.CER).
        7. Specify a suitable directory and file name for the exported file. Click Next to export the certificate, and then click Finish.
        8. Copy the exported certificate to the IdM server machine.
    2. If your Active Directory CA certificate is signed by an external CA:
      1. To find out what certificate is the CA root certificate, display the certificate chain: 
        # openssl s_client -connect adserver.example.com:636
CONNECTED(00000003)
depth=1 C = US, O = Demo Company, OU = IT, CN = Demo CA-28
verify error:num=20:unable to get local issuer certificate
verify return:0
---
Certificate chain
 0 s:/C=US/O=Demo Company/OU=IT/CN=adserver.example.com
   i:/C=US/O=Demo Company/OU=IT/CN=Demo CA-1
 1 s:/C=US/O=Demo Company/OU=IT/CN=Demo CA-1
   i:/C=US/O=Demo Company/OU=IT/CN=Demo Root CA 2
        The previous example shows that the Active Directory server's CA certificate is signed by CN=Demo CA-1, which is signed by CN=Demo Root CA 2. This means that CN=Demo Root CA 2 is the root CA.
      2. Copy the CA certificate to the IdM server.
  2. Remove any existing Kerberos credentials on the IdM server. 
    $ kdestroy
  3. Use the ipa-replica-manage command to create a Windows synchronization agreement. This requires the --winsync option. If passwords will be synchronized as well as user accounts, then also use the --passsync option and set a password to use for Password Synchronization.
    The --binddn and--bindpw options give the user name and password of the system account on the Active Directory server that IdM will use to connect to the Active Directory server. 
    $ ipa-replica-manage connect --winsync \
	--binddn cn=administrator,cn=users,dc=example,dc=com \
	--bindpw Windows-secret \
	--passsync secretpwd \
	--cacert /etc/openldap/cacerts/windows.cer \
	adserver.example.com -v
    • --winsync: Identifies this as a Windows synchronization agreement.
    • --binddn: IdM uses this DN of an Active Directory account to bind to the remote directory and synchronize attributes.
    • --bindpw: Password for the synchronization account.
    • --cacert: Full path and file name to the:
      • Active Directory CA certificate, if the CA was self-signed.
      • external CA certificate, if the Active Directory CA was signed by an external CA.
    • --win-subtree: DN of the Windows directory subtree containing the users to synchronize. The default value is cn=Users,$SUFFIX.
    • AD_server_name: Fully qualified domain name (FQDN) of the Active Directory domain controller.
  4. When prompted, enter the Directory Manager password.
  5. Optional. Configure Password Synchronization, as in Section 6.6.2, “Setting up Password Synchronization”. Without the Password Synchronization client, user attributes are synchronized between the peer servers, but passwords are not.

    Note

    The Password Synchronization client captures password changes and then synchronizes them between Active Directory and IdM. This means that it synchronizes new passwords or password updates.
    Existing passwords, which are stored in a hashed form in both IdM and Active Directory, cannot be decrypted or synchronized when the Password Synchronization client is installed, so existing passwords are not synchronized. User passwords must be changed to initiate synchronization between the peer servers.

6.5.2. Changing the Behavior for Synchronizing User Account Attributes

When the synchronization agreement is created, it has certain default behaviors defined for how the synchronization process handles the user account attributes during synchronization. The types of behaviors are things like how to handle lockout attributes or how to handle different DN formats. This behavior can be changed by editing the synchronization agreement.
The synchronization agreement exists as a special plug-in entry in the LDAP server and each attribute behavior is set through an LDAP attribute. To change the synchronization behavior, use the ldapmodify command to modify the LDAP server entry directly.
For example, account lockout attributes are synchronized between IdM and Active Directory by default, but this can be disabled by editing the ipaWinSyncAcctDisable attribute. (Changing this means that if an account is disabled in Active Directory, it is still active in IdM and vice versa.) 
[jsmith@ipaserver ~]$ ldapmodify -x -D "cn=directory manager" -w password

dn: cn=ipa-winsync,cn=plugins,cn=config
changetype: modify
replace: ipaWinSyncAcctDisable
ipaWinSyncAcctDisable: none

modifying entry "cn=ipa-winsync,cn=plugins,cn=config"
The following is an overview of synchronization settings attributes:

General User Account Parameters

  • ipaWinSyncNewEntryFilter: Sets the search filter to use to find the entry which contains the list of object classes to add to new user entries.
    Default value: (cn=ipaConfig)
  • ipaWinSyncNewUserOCAttr: Sets the attribute in the configuration entry which actually contains the list of object classes to add to new user entries.
    Default value: ipauserobjectclasses
  • ipaWinSyncHomeDirAttr: Identifies which attribute in the entry contains the default location of the POSIX home directory.
    Default value: ipaHomesRootDir
  • ipaWinSyncUserAttr: Sets an additional attribute with a specific value to add to Active Directory users when they are synchronized over from the Active Directory domain. If the attribute is multi-valued, then it can be set multiple times, and the synchronization process adds all of the values to the entry.
    Example: ipaWinSyncUserAttr: attributeName attributeValue

    Note

    This only sets the attribute value if the entry does not already have that attribute present. If the attribute is present, then the entry's value is used when the Active Directory entry is synchronized over.
  • ipaWinSyncForceSync: Sets whether existing IdM users that match existing AD users should be forced to be synchronized. When set to true, such IdM users are automatically edited so that they are synchronized.
    Possible values: true | false
    If an IdM user account has a uid parameter which is identical to the sAMAccountName in an existing Active Directory user, then that account is not synchronized by default. This attribute tells the synchronization service to add the ntUser and ntUserDomainId to the IdM user entries automatically, which allows them to be synchronized.

User Account Lock Parameters

  • ipaWinSyncAcctDisable: Sets which way to synchronize account lockout attributes. It is possible to control which account lockout settings are in effect. For example, to_ad means that when account lockout attribute is set in IdM, its value is synchronized over to Active Directory and overrides the local Active Directory value. By default, account lockout attributes are synchronized from both domains.
    Possible values: both (default), to_ad, to_ds, none
  • ipaWinSyncInactivatedFilter: Sets the search filter to use to find the DN of the group used to hold inactivated (disabled) users. This does not need to be changed in most deployments.
    Default value: (&(cn=inactivated)(objectclass=groupOfNames))

Group Parameters

  • ipaWinSyncDefaultGroupAttr: Sets the attribute in the new user account to reference to see what the default group for the user is. The group name in the entry is then used to find the gidNumber for the user account.
    Default value: ipaDefaultPrimaryGroup
  • ipaWinSyncDefaultGroupFilter: Sets the attribute in the new user account to reference to see what the default group for the user is. The group name in the entry is then used to find the gidNumber for the user account.
    Default value: ipaDefaultPrimaryGroup

Realm Parameters

  • ipaWinSyncRealmAttr: Sets the attribute which contains the realm name in the realm entry.
    Default value: cn
  • ipaWinSyncRealmFilter: Sets the search filter to use to find the entry which contains the IdM realm name.
    Default value: (objectclass=krbRealmContainer)

6.5.3. Changing the Synchronized Windows Subtree

Creating a synchronization agreement automatically sets the two subtrees to use as the synchronized user database. In IdM, the default is cn=users,cn=accounts,$SUFFIX, and for Active Directory, the default is CN=Users,$SUFFIX.
The value for the Active Directory subtree can be set to a non-default value when the synchronization agreement is created by using the --win-subtree option. After the agreement is created, the Active Directory subtree can be changed by using the ldapmodify command to edit the nsds7WindowsReplicaSubtree value in the synchronization agreement entry.
  1. Get the name of the synchronization agreement, using ldapsearch. This search returns only the values for the dn and nsds7WindowsReplicaSubtree attributes instead of the entire entry. 
    [jsmith@ipaserver ~]$ ldapsearch -xLLL -D "cn=directory manager" -w password -p 389 -h ipaserver.example.com -b cn=config objectclass=nsdswindowsreplicationagreement dn nsds7WindowsReplicaSubtree

dn: cn=meToWindowsBox.example.com,cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config
nsds7WindowsReplicaSubtree: cn=users,dc=example,dc=com

... 8< ...
  2. Modify the synchronization agreement 
    [jsmith@ipaserver ~]$ ldapmodify -x -D "cn=directory manager" -W -p 389 -h ipaserver.example.com <<EOF
 dn: cn=meToWindowsBox.example.com,cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config
 changetype: modify
 replace: nsds7WindowsReplicaSubtree
 nsds7WindowsReplicaSubtree: cn=alternateusers,dc=example,dc=com
 EOF

 modifying entry "cn=meToWindowsBox.example.com,cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config"
The new subtree setting takes effect immediately. If a synchronization operation is currently running, then it takes effect as soon as the current operation completes.

6.5.4. Configuring Uni-directional Synchronization

By default, all modifications and deletions are bidirectional. A change in Active Directory is synchronized over to Identity Management, and a change to an entry in Identity Management is synchronized over to Active Directory. This is essentially an equitable, multi-master relationship, where both Active Directory and Identity Management are equal peers in synchronization and are both data masters.
However, there can be some data structure or IT designs where only one domain should be a data master and the other domain should accept updates. This changes the synchronization relationship from a multi-master relationship (where the peer servers are equal) to a master consumer relationship.
This is done by setting the oneWaySync parameter on the synchronization agreement. The possible values are fromWindows (for Active Directory to Identity Management synchronization) and toWindows (for Identity Management to Active Directory synchronization).
For example, to synchronize changes from Active Directory to Identity Management: 
[jsmith@ipaserver ~]$ ldapmodify -x -D "cn=directory manager" -w password -p 389 -h ipaserver.example.com

dn: cn=meToWindowsBox.example.com,cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config
changetype: modify
add: oneWaySync
oneWaySync: fromWindows

Important

Enabling unidirectional synchronization does not automatically prevent changes on the unsynchronized server, and this can lead to inconsistencies between the synchronization peers between synchronization updates. For example, unidirectional synchronization is configured to go from Active Directory to Identity Management, so Active Directory is (in essence) the data master. If an entry is modified or even deleted on the Identity Management, then the Identity Management information is different then the information and those changes are never carried over to Active Directory. During the next synchronization update, the edits are overwritten on the Directory Server and the deleted entry is re-added.

6.5.5. Deleting Synchronization Agreements

Synchronization can be stopped by deleting the synchronization agreement which disconnects the IdM and Active Directory servers. In the inverse of creating a synchronization agreement, deleting a synchronization agreement uses the ipa-replica-manage disconnect command and then the host name of the Active Directory server.
  1. Delete the synchronization agreement. 
    # ipa-replica-manage disconnect adserver.ad.example.com
  2. List the certificates in the IdM directory certificate database: 
    # certutil -L -d /etc/dirsrv/slapd-IDM-EXAMPLE-COM/
Certificate Nickname                   Trust Attributes
                                       SSL,S/MIME,JAR/XPI

IDM.EXAMPLE.COM IPA CA                 CT,C,C
CN=adserver,DC=ad,DC=example,DC=com    C,,
Server-Cert                            u,u,u
  3. Remove the Active Directory CA certificate from the IdM server database: 
    # certutil -D -d /etc/dirsrv/slapd-IDM-EXAMPLE-COM/ -n "CN=adserver,DC=ad,DC=example,DC=com"

6.5.6. Winsync Agreement Failures

Creating the synchronization agreement fails because it cannot connect to the Active Directory server.

One of the most common synchronization agreement failures is that the IdM server cannot connect to the Active Directory server: 

"Update failed! Status: [81  - LDAP error: Can't contact LDAP server]

This can occur if the wrong Active Directory CA certificate was specified when the agreement was created. This creates duplicate certificates in the IdM LDAP database (in the /etc/dirsrv/slapd-DOMAIN/ directory) with the name Imported CA. This can be checked using certutil: 
$ certutil -L -d /etc/dirsrv/slapd-DOMAIN/

Certificate Nickname                                         Trust Attributes
SSL,S/MIME,JAR/XPI

CA certificate                                               CTu,u,Cu
Imported CA                                                  CT,,C
Server-Cert                                                  u,u,u
Imported CA                                                  CT,,C
To resolve this issue, remove the CA certificate from the certificate database: 
# certutil -d /etc/dirsrv/slapd-DOMAIN-NAME -D -n "Imported CA"
There are errors saying passwords are not being synchronized because it says the entry exists

For some entries in the user database, there may be an informational error message that the password is not being reset because the entry already exists: 

"Windows PassSync entry exists, not resetting password"
This is not an error. This message occurs when an exempt user, the Password Synchronization user, is not being changed. The Password Synchronization user is the operational user which is used by the service to change the passwords in IdM.