Migrating to Identity Management on RHEL 8

1. Upgrade the system to the latest RHEL 7 version.
2. Ensure that the domain level for your domain is set to 1. For more information, see Displaying and Raising the Domain Level in the Linux Domain Identity, Authentication, and Policy Guide for RHEL 7.

3. Update the ipa-* packages to their latest version:

   [root@rhel7 ~]# yum update ipa-*

   Warning

   When upgrading multiple Identity Management (IdM) servers, wait at least 10 minutes between each upgrade.

   When two or more servers are upgraded simultaneously or with only short intervals between the upgrades, there is not enough time to replicate the post-upgrade data changes throughout the topology, which can result in conflicting replication events.

1. Install the latest version of Red Hat Enterprise Linux on the system. For more information, see Interactively installing RHEL from installation media.

2. Identify the time server rhel7.example.com is synchronized with:

   [root@rhel7 ~]# ntpstat
   synchronised to NTP server (ntp.example.com) at stratum 3
      time correct to within 42 ms
      polling server every 1024 s

   Important

   In RHEL 8, IdM does not provide its own time server: the installation of IdM on rhel8.example.com does not result in the installation of an NTP server on the host. Therefore, you need to use a separate NTP server, for example ntp.example.com. For more information, see Migrating to chrony and Time service requirements for IdM.

   While rhel7.example.com can be used in an NTP server role, you will decommission the server as part of the migration process. Therefore, rhel8.example.com needs to be synchronized directly with ntp.example.com instead. You can specify this during the client installation process.

3. Enroll the system as an IdM client into the domain for which rhel7.example.com IdM server is authoritative. For more information, see Installing an IdM client. When installing the client, specify the time server from the previous step:

   [root@rhel8]# ipa-client-install --mkhomedir --ntp-server ntp.example.com

   If you are using a pool of NTP servers, use the --ntp-pool option.

   If you do not specify an NTP server manually, it will be automatically set from DNS records. This can lead to rhel8.example.com synchronizing with rhel7.example.com. This will cause issues when the RHEL 7 server is decommissioned.

   If the RHEL8 system is already properly configured as an NTP client, you can use the --no-ntp option when performing the IdM client installation.

   Important

   Do not use single-label domain names, for example .company. Starting with RHEL 8, IDM does not accept single-labeled domain names and the domain name must be composed of one or more subdomains and a top level domain, for example example.com or company.example.com.

   If the existing domain is single-labeled, it is not possible to perform the migration using these instructions. In these cases, use Migrating an LDAP Server to Identity Management.

4. Prepare the system for IdM server installation. See Preparing the system for IdM server installation.
5. Authorize the system for the installation of an IdM replica. See Authorizing the installation of a replica on an IdM client.

6. Update the ipa-* packages to their latest version:

   [root@rhel7 ~]# yum update ipa-*

Verification

1. Verify that the IdM services are running on rhel8.example.com:

   [root@rhel8 ~]# ipactl status
   Directory Service: RUNNING
   [... output truncated ...]
   ipa: INFO: The ipactl command was successful

2. Verify that server roles for rhel8.example.com are the same as for rhel7.example.com except the NTP server role:

   [root@rhel8 ~]$ kinit admin
   [root@rhel8 ~]$ ipa server-role-find --status enabled --server rhel8.example.com
   ----------------------
   2 server roles matched
   ----------------------
     Server name: rhel8.example.com
     Role name: CA server
     Role status: enabled
   
     Server name: rhel8.example.com
     Role name: DNS server
     Role status: enabled

3. Optional: Display details about the replication agreement between rhel7.example.com and rhel8.example.com:

   [root@rhel8 ~]# ipa-csreplica-manage list --verbose rhel8.example.com
   Directory Manager password:
   
   rhel7.example.com
   last init status: None
   last init ended: 1970-01-01 00:00:00+00:00
   last update status: Error (0) Replica acquired successfully: Incremental update succeeded
   last update ended: 2019-02-13 13:55:13+00:00

4. Optional: If your IdM deployment is in a trust relationship with AD, verify that it is working:

   1. link: Verify the Kerberos configuration

   2. Attempt to resolve an AD user on rhel8.example.com:

      [root@rhel8 ~]# id aduser@ad.domain

5. Verify that rhel8.example.com is synchronized with the NTP server:

   [root@rhel8 ~]# chronyc tracking
   Reference ID    : CB00710F (ntp.example.com)
   Stratum         : 3
   Ref time (UTC)  : Tue Nov 16 09:49:17 2021
   [... output truncated ...]

1. Configure rhel8.example.com to handle CA subsystem certificate renewal:

   [root@rhel8 ~]# ipa config-mod --ca-renewal-master-server rhel8.example.com
     ...
     IPA masters: rhel7.example.com, rhel8.example.com
     IPA CA servers: rhel7.example.com, rhel8.example.com
     IPA NTP servers: rhel7.example.com, rhel8.example.com
     IPA CA renewal master: rhel8.example.com

   The output confirms that the update was successful.

2. On rhel8.example.com, enable the certificate updater task:

   1. Open the /etc/pki/pki-tomcat/ca/CS.cfg configuration file for editing.
   2. Remove the ca.certStatusUpdateInterval entry, or set it to the desired interval in seconds. The default value is 600.
   3. Save and close the /etc/pki/pki-tomcat/ca/CS.cfg configuration file.

   4. Restart IdM services:

      [user@rhel8 ~]$ ipactl restart

3. On rhel7.example.com, disable the certificate updater task:

   1. Open the /etc/pki/pki-tomcat/ca/CS.cfg configuration file for editing.

   2. Change ca.certStatusUpdateInterval to 0, or add the following entry if it does not exist:

      ca.certStatusUpdateInterval=0

   3. Save and close the /etc/pki/pki-tomcat/ca/CS.cfg configuration file.

   4. Restart IdM services:

      [user@rhel7 ~]$ ipactl restart

Procedure

1. Optional: Check if rhel7.example.com is generating the CRL:

   [root@rhel7 ~]# ipa-crlgen-manage status
   CRL generation: enabled
   Last CRL update: 2019-10-31 12:00:00
   Last CRL Number: 6
   The ipa-crlgen-manage command was successful

2. Stop generating the CRL on the rhel7.example.com server:

   [root@rhel7 ~]# ipa-crlgen-manage disable
   Stopping pki-tomcatd
   Editing /var/lib/pki/pki-tomcat/conf/ca/CS.cfg
   Starting pki-tomcatd
   Editing /etc/httpd/conf.d/ipa-pki-proxy.conf
   Restarting httpd
   CRL generation disabled on the local host. Please make sure to configure CRL generation on another master with ipa-crlgen-manage enable.
   The ipa-crlgen-manage command was successful

Verification

1. Check if the rhel7.example.com server stopped generating the CRL:

   [root@rhel7 ~]# ipa-crlgen-manage status

Procedure

1. To start generating CRL on rhel8.example.com, use the ipa-crlgen-manage enable command:

   [root@rhel8 ~]# ipa-crlgen-manage enable
   Stopping pki-tomcatd
   Editing /var/lib/pki/pki-tomcat/conf/ca/CS.cfg
   Starting pki-tomcatd
   Editing /etc/httpd/conf.d/ipa-pki-proxy.conf
   Restarting httpd
   Forcing CRL update
   CRL generation enabled on the local host. Please make sure to have only a single CRL generation master.
   The ipa-crlgen-manage command was successful

2. To check if CRL generation is enabled, use the ipa-crlgen-manage status command:

   [root@rhel8 ~]# ipa-crlgen-manage status
   CRL generation: enabled
   Last CRL update: 2019-10-31 12:10:00
   Last CRL Number: 7
   The ipa-crlgen-manage command was successful

Procedure

1. If IdM is not yet installed: install the IdM server, including any custom LDAP directory schema, on a different machine from the one on which the existing LDAP directory is installed. For details, see Installing Identity Management.

   Note

   Custom user or group schemas have limited support in IdM. They can cause problems during the migration because of incompatible object definitions.

2. For performance reasons, disable the compat plug-in:

   # ipa-compat-manage disable

   For more information about the schema compat feature and the benefits of disabling it for the migration, see The schema to use when migrating from LDAP to IdM and the schema compat feature.

3. Restart the IdM Directory Server instance:

   # systemctl restart dirsrv.target

4. Configure the IdM server to allow migration:

   # ipa config-mod --enable-migration=TRUE

   By setting --enable-migration to TRUE, you do the following:

   • Allow pre-hashed passwords during an LDAP add operation.
   • Configure SSSD to try the password migration sequence if the initial Kerberos authentication fails. For more information, see the Workflow section in Using SSSD when migrating passwords from LDAP to IdM.

5. Run the IdM migration script, ipa migrate-ds, with the options that are relevant for your use case. For more information, see Customizing the migration from LDAP to IdM.

   # ipa migrate-ds --your-options ldap://ldap.example.com:389

   Note

   If you did not disable the compat plug-in in one of the previous steps, add the --with-compat option to ipa migrate-ds:

   # ipa migrate-ds --your-options --with-compat ldap://ldap.example.com:389

6. Re-enable the compat plug-in:

   # ipa-compat-manage enable

7. Restart the IdM Directory Server:

   # systemctl restart dirsrv.target

8. When all users have had their passwords migrated, disable the migration mode:

   # ipa config-mod --enable-migration=FALSE

9. Optional: When all of the users have been migrated, reconfigure non-SSSD clients to use Kerberos authentication, that is pam_krb5, instead of LDAP authentication, that is pam_ldap. For more information, see Configuring a Kerberos Client in the RHEL 7 System-level Authentication Guide.

10. Have users generate their hashed Kerberos passwords. Choose one of the methods described in Planning password migration when migrating from LDAP to IdM.

    • If you decide on the SSSD method:

      • Move clients that have SSSD installed from the LDAP directory to the IdM directory, and enroll them as clients with IdM. This downloads the required keys and certificates.

        On Red Hat Enterprise Linux clients, this can be done using the ipa-client-install command. For example:

        # ipa-client-install --enable-dns-update

    • If you decide on the IdM migration web page method:

      • Instruct users to log into IdM using the migration web page:

        https://ipaserver.example.com/ipa/migration

11. To monitor the user migration process, query the existing LDAP directory to see which user accounts have a password but do not yet have a Kerberos principal key.

    $ ldapsearch -LL -x -D 'cn=Directory Manager' -w secret -b 'cn=users,cn=accounts,dc=example,dc=com' '(&(!(krbprincipalkey=))(userpassword=))' uid

    Note

    Include the single quotes around the filter so that it is not interpreted by the shell.

12. When the migration of all clients and users is complete, decommission the LDAP directory.

Verification

1. Create a test user in IdM by using the ipa user-add command. Compare the output of migrated users to that of the test user. Ensure that the migrated users contain the minimal set of attributes and object classes present on the test user. For example:

   $ ipa user-show --all testing_user
   dn: uid=testing_user,cn=users,cn=accounts,dc=idm,dc=example,dc=com
   User login: testing_user
   First name: testing
   Last name: user
   Full name: testing user
   Display name: testing user
   Initials: tu
   Home directory: /home/testing_user
   GECOS: testing user
   Login shell: /bin/sh
   Principal name: testing_user@IDM.EXAMPLE.COM
   Principal alias: testing_user@IDM.EXAMPLE.COM
   Email address: testing_user@idm.example.com
   UID: 1689700012
   GID: 1689700012
   Account disabled: False
   Preserved user: False
   Password: False
   Member of groups: ipausers
   Kerberos keys available: False
   ipauniqueid: 843b1ac8-6e38-11ec-8dfe-5254005aad3e
   mepmanagedentry: cn=testing_user,cn=groups,cn=accounts,dc=idm,dc=example,dc=com
   objectclass: top, person, organizationalperson, inetorgperson, inetuser, posixaccount, krbprincipalaux, krbticketpolicyaux, ipaobject,
                ipasshuser, ipaSshGroupOfPubKeys, mepOriginEntry

2. Compare the output of migrated users, as seen on IdM, to the source users, as seen on the original LDAP server. Ensure that imported attributes are not copied twice and that they have the correct values.

Procedure

1. Store the certificate of the CA that issued the remote LDAP server certificate in a file on the future IdM server. For example: /tmp/remote.crt.

2. Follow the steps described in Migrating an LDAP server to IdM. However, for an encrypted LDAP connection during the migration, use the ldaps protocol in the URL and pass the --ca-cert-file option to the ipa migrate-ds command. For example:

   # ipa migrate-ds --ca-cert-file=/tmp/remote.crt --your-other-options ldaps://ldap.example.com:636

Verification

1. Create a test user in IdM by using the ipa user-add command. Compare the output of migrated users to that of the test user. Ensure that the migrated users contain the minimal set of attributes and object classes present on the test user. For example:

   $ ipa user-show --all testing_user
   dn: uid=testing_user,cn=users,cn=accounts,dc=idm,dc=example,dc=com
   User login: testing_user
   First name: testing
   Last name: user
   Full name: testing user
   Display name: testing user
   Initials: tu
   Home directory: /home/testing_user
   GECOS: testing user
   Login shell: /bin/sh
   Principal name: testing_user@IDM.EXAMPLE.COM
   Principal alias: testing_user@IDM.EXAMPLE.COM
   Email address: testing_user@idm.example.com
   UID: 1689700012
   GID: 1689700012
   Account disabled: False
   Preserved user: False
   Password: False
   Member of groups: ipausers
   Kerberos keys available: False
   ipauniqueid: 843b1ac8-6e38-11ec-8dfe-5254005aad3e
   mepmanagedentry: cn=testing_user,cn=groups,cn=accounts,dc=idm,dc=example,dc=com
   objectclass: top, person, organizationalperson, inetorgperson, inetuser, posixaccount, krbprincipalaux, krbticketpolicyaux, ipaobject,
                ipasshuser, ipaSshGroupOfPubKeys, mepOriginEntry

2. Compare the output of migrated users, as seen on IdM, to the source users, as seen on the original LDAP server. Ensure that imported attributes are not copied twice and that they have the correct values.

Procedure

1. Back up your IdM setup using the ipa-backup utility. See Backing up and restoring IdM.

   NOTE

   The migration affects a significant part of the IdM configuration and many user accounts. Creating a backup enables you to restore your original setup if necessary.

2. Create a trust with the synchronized domain. See For details, see Installing trust between IdM and AD.

3. Run ipa-winsync-migrate and specify the AD realm and the host name of the AD domain controller:

   # ipa-winsync-migrate --realm example.com --server ad.example.com

   If a conflict occurs in the overrides created by ipa-winsync-migrate, information about the conflict is displayed, but the migration continues.

4. Uninstall the Password Sync service from the AD server. This removes the synchronization agreement from the AD domain controllers.

Procedure

1. Create a backup of the original synchronized user and group entries.
2. Create a trust with the synchronized domain. See For details, see Installing trust between IdM and AD.

3. For every synchronized user or group, preserve the UID and GIDs generated by IdM by doing one of the following:

   • Individually create an ID view applied to the specific host and add user ID overrides to the view.
   • Create user ID overrides in the Default Trust View.
   Note

   Only IdM users can manage ID views. AD users cannot.

4. Delete the original synchronized user or group entries.