Description
This use case addresses the situation when a user has existing directory server running and would like to use FreeIPA instead. The benefits of using FreeIPA are mainly Kerberos authentication which can be leveraged for Single Sign On and better access control (HBAC) rules. The migration does not modify data on the existing Directory Server in any way.
The existing password is stored in hashed form in the LDAP server, but in order for the Kerberos passwords to be generated, the password migration component must access the password in plaintext. Therefore the users have to either enter the password manually on a special web page (Server Based Migration) or log in to a client machine that is already enrolled to the IPA domain (Client Based Migration). Both ways share a common first step, which is the actual migration of users and groups from the existing LDAP server to FreeIPA.
Setup
- Make sure you have a working FreeIPA server (see QA:Testcase_freeipav2_installation)
- Make sure the CLI works as expected (see QA:Testcase_freeipav2_cli)
- Before the migration, you should collect the following data about your Directory Server:
- The LDAP URI of the existing Directory Server. This would have the form of ldap://directory.example.com
- The DN of the user you will bind as. That user must be able to read the LDAP passwords of the users. The default which works fine for 389-DS/RHDS is Directory Manager
- The container that stores users and groups in your directory. The default is ou=People and ou=Groups respectively. This value is concatenated with the autodetected baseDN of the directory. If your base DN was, for example, dc=example,dc=com, the migration tool would look into ou=People,dc=example,dc=com and ou=Groups,dc=example,dc=com respectively.
- The objectclasses of your users and groups. The defaults that the migration tool uses are person for users and any of groupOfUniqueNames and groupOfNames for groups.
- The schema of your LDAP server. If you are not sure (and you're not migrating from an existing FreeIPA instance), you should most probably use RFC2307.
How to test
Migrating the Directory Server Data
Migration is disabled in FreeIPA by default. Enable it using the config plugin:
# ipa config-mod --enable-migration=TRUE
The first step of the migration process is migrating the users and groups with the migrate-ds tool. Using the information about your directory server setup, run the migrate-ds tool. The following example illustrates migrating POSIX users and groups from an existing RFC2307 server:
# ipa migrate-ds --user-container='cn=users' --group-container='cn=groups' --user-objectclass=posixUser --group-objectclass=posixGroup
--schema=RFC2307 ldap://ds.example.com:389
Another following example illustrates migration from a FreeIPA v1 server:
# ipa migrate-ds --user-container='cn=users,cn=accounts' --group-container='cn=groups,cn=accounts' ldap://ipav1.example.com:389
Refer to the ipa migrate-ds help page for more details about this command (ipa help migration).
The tool will ask you for the bind password and migrate all users and groups. It will skip any users or groups that already exist in the new FreeIPA instance.
A sample output showing migration from another FreeIPA instance looks like this:
# ipa migrate-ds --user-container='cn=users,cn=accounts' --group-container='cn=groups,cn=accounts' ldap://ipa.example.com Password: Enter Password again to verify: ----------- migrate-ds: ----------- Migrated: user: able, baker, sam Failed user: admin: This entry already exists Failed group: admins: This entry already exists editors: This entry already exists ipausers: This entry already exists ---------- Passwords have been migrated in pre-hashed format. IPA is unable to generate Kerberos keys unless provided with clear text passwords. All migrated users need to login at https://your.domain/ipa/migration/ before they can use their Kerberos accounts.
At this point, LDAP pre-hashed passwords have been migrated. In order to generate Kerberos passwords, either Server Based or Client Based Migration must be performed.
WebUI Migration
One option is to migrate the user data using a self-service Web UI. After migrating the users, point your web browser to https://ipa.example.com/ipa/migration/. You will be presented with a form where you should enter your username and password. At this point, IPA will be able to migrate the password to the new Kerberos format. If the password was OK, the UI would redirect you to the FreeIPA WebUI.
Client Based Migration
This kind of migration assumes a host enrolled into the IPA domain with SSSD configured to use IPA as a back end. When a user logs into the machine with SSSD, his credentials will be migrated.
Expected Results
All the test steps should end with the specified results.