Search
SupportConsoleDevelopersStart a trialContact

15.5. Managing Synchronization Agreements

download PDF

15.5.1. Trusting the Active Directory and IdM CA Certificates

Both Active Directory and Identity Management use certificates for server authentication. For the Active Directory and IdM SSL server certificates to be trusted by each other, both servers need to trust the CA certificate for the CA which issued those certificates. This means that the Active Directory CA certificate needs to be imported into the IdM database, and the IdM CA certificate needs to be imported into the Active Directory database.
  1. On the Active Directory server, download the IdM server's CA certificate from http://ipa.example.com/ipa/config/ca.crt.
  2. Install the IdM CA certificate in the Active Directory certificate database. This can be done using the Microsoft Management Console or the certutil utility. For example: 
    certutil -installcert -v -config "ipaserver.example.com\Example Domain CA" c:\path\to\ca.crt
    For more details, see the Active Directory documentation.
  3. Export the Active Directory CA certificate.
    1. In My Network Places, open the CA distribution point.
    2. Double-click the security certificate file (.crt file) to display the Certificate dialog box.
    3. On the Details tab, click Copy to File to start the Certificate Export Wizard.
    4. Click Next, and then select Base-64 encoded X.509 (.CER).
    5. Specify a suitable directory and file name for the exported file. Click Next to export the certificate, and then click Finish.
  4. Copy the Active Directory certificate over to the IdM server machine.
  5. Download the IdM server's CA certificate from http://ipa.example.com/ipa/config/ca.crt.
  6. Copy both the Active Directory CA certificate and the IdM CA certificate into the /etc/openldap/cacerts/ directory.
  7. Update the hash symlinks for the certificates. 
    cacertdir_rehash /etc/openldap/cacerts/
  8. Edit the /etc/openldap/ldap.conf file, and add the information to point to and use the certificates in the /etc/openldap/cacerts/ directory. 
    TLS_CACERTDIR /etc/openldap/cacerts/
TLS_REQCERT allow

15.5.2. 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. The options to create the synchronization agreement are listed in Table 15.2, “Synchronization Agreement Options”.
  1. Make sure that the Active Directory and IdM servers trust each other's CA certificates, as in Section 15.5.1, “Trusting the Active Directory and IdM CA Certificates”.
  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 Sync.
    The --binddn and--bindpwd options give the username 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
  4. When prompted, enter the Directory Manager password.
  5. Optional. Configure Password Synchronization, as in Section 15.6.2, “Setting up Password Synchronization”.
Table 15.2. Synchronization Agreement Options
Option Description
--winsync Identifies this as a synchronization agreement.
--binddn Gives the full user DN of the synchronization identity. This is the user DN that the IdM LDAP server uses to bind to Active Directory. This user must exist in the Active Directory domain and must have replicator, read, search, and write permissions on the Active Directory subtree.
--bindpw Gives the password for the sync user.
--passsync Gives the password for the Windows user account which is involved in synchronization.
--cacert Gives the full path and file name of the Active Directory CA certificate. This certificate is exported in Section 15.5.1, “Trusting the Active Directory and IdM CA Certificates”.
--win-subtree Gives the DN of the Windows subtree containing the users to synchronize. The default value is cn=Users,$SUFFIX.
AD_server_name Gives the hostname of the Active Directory domain controller.

15.5.3. Changing the Behavior for Syncing User Account Attributes

When the sync 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 list of attribute-related parameters are in Table 15.3, “Synced Attribute Settings”.
The sync 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 sync 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"
Table 15.3. Synced Attribute Settings
Parameter Description Possible Values
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. The default is (cn=ipaConfig).
ipaWinSyncNewUserOCAttr Sets the attribute in the configuration entry which actually contains the list of object classes to add to new user entries. The default is ipauserobjectclasses.
ipaWinSyncHomeDirAttr Identifies which attribute in the entry contains the default location of the POSIX home directory. The default is ipaHomesRootDir.
ipaWinSyncUserAttr Sets an additional attribute with a specific value to add to Active Directory users when they are synced over from the Active Directory domain. If the attribute is multi-valued, then it can be set multiple times, and the sync process adds all of the values to the entry.

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 synced over.
ipaWinSyncUserAttr: attributeName attributeValue
ipaWinSyncForceSync Sets whether to check existing IdM users which match an existing Active Directory user should be automatically edited so they can be synchronized. 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 synced by default. This attribute tells the sync service to add the ntUser and ntUserDomainId to the IdM user entries automatically, which allows them to be synchronized. true | false
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 synced over to Active Directory and overrides the local Active Directory value. By default, account lockout attributes are synced from both domains.
  • 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. The default is (&(cn=inactivated)(objectclass=groupOfNames)).
ipaWinSyncActivatedFilter Sets the search filter to use to find the DN of the group used to hold active users. This does not need to be changed in most deployments. The default is (&(cn=activated)(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. The default is ipaDefaultPrimaryGroup.
ipaWinSyncDefaultGroupFilter Sets the search filter to map the group name to the POSIX gidNumber. The default is (&(gidNumber=*)(objectclass=posixGroup)(cn=groupAttr_value)).
Realm Parameters  
ipaWinSyncRealmAttr Sets the attribute which contains the realm name in the realm entry. The default is cn.
ipaWinSyncRealmFilter Sets the search filter to use to find the entry which contains the IdM realm name. The default is (objectclass=krbRealmContainer).

15.5.4. 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 sync 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 sync agreement entry.
  1. Get the name of the sync 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 sync 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 sync operation is currently running, then it takes effect as soon as the current operation completes.

15.5.5. Configuring Uni-Directional Sync

By default, all modifications and deletions are bi-directional. A change in Active Directory is synced over to Identity Management, and a change to an entry in Identity Management is synced 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 sync 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 sync agreement. The possible values are fromWindows (for Active Directory to Identity Management sync) and toWindows (for Identity Management to Active Directory sync).
For example, to sync 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=windows.example.com,cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config
changetype: modify
add: oneWaySync
oneWaySync: fromWindows

Important

Enabling uni-directional sync does not automatically prevent changes on the un-synchronized server, and this can lead to inconsistencies between the sync peers between sync updates. For example, uni-directional sync 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 sync update, the edits are overwritten on the Directory Server and the deleted entry is re-added.

15.5.6. Deleting Synchronization Agreements

Synchronization can be stopped by deleting the sync agreement which disconnects the IdM and Active Directory servers. In the inverse of creating a sync agreement, deleting a sync agreement uses the ipa-replica-manage disconnect command and then the hostname of the Active Directory server.
  1. Delete the sync agreement. 
    # ipa-replica-manage disconnect adserver.example.com
  2. Remove the Active Directory CA certificate from the IdM server database: 
    # certutil -D -d /etc/dirsrv/slapd-EXAMPLE.COM/ -n "Imported CA"

15.5.7. Winsync Agreement Failures

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

One of the most common sync 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, clear the certificate database: 
# certutil -d /etc/dirsrv/slapd-DOMAIN-NAME -D -n "Imported CA"
This deletes the CA certificate from the LDAP database.
There are errors saying passwords are not being synced 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 Sync user, is not being changed. The Password Sync user is the operational user which is used by the service to change the passwords in IdM.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.