Chapter 40. Migrating from an LDAP Directory to IdM

As an administrator, you previously deployed an LDAP server for authentication and identity lookups and now you want to migrate the back end to Identity Management. You want to use the IdM migration tool to transfer user accounts, including passwords, and group, without losing data. Additionally you want to avoid expensive configuration updates on the clients.
The migration process described here, assumes a simple deployment scenario with one name space in LDAP and one in IdM. For more complex environments, such as multiple name spaces or custom schema, contact the Red Hat support services.

40.1. An Overview of an LDAP to IdM Migration

The actual migration part of moving from an LDAP server to Identity Management — the process of moving the data from one server to the other — is fairly straightforward. The process is simple: move data, move passwords, and move clients.
The most expensive part of the migration is deciding how clients are going to be configured to use Identity Management. For each client in the infrastructure, you need to decide what services (such as Kerberos and SSSD) are being used and what services can be used in the final IdM deployment.
A secondary, but significant, consideration is planning how to migrate passwords. Identity Management requires Kerberos hashes for every user account in addition to passwords. Some of the considerations and migration paths for passwords are covered in Section 40.1.2, “Planning Password Migration”.

40.1.1. Planning the Client Configuration

Identity Management can support a number of different client configurations, with varying degrees of functionality, flexibility, and security. Decide which configuration is best for each individual client based on its operating system, functional area (such as development machines, production servers, or user laptops), and your IT maintenance priorities.

Important

The different client configurations are not mutually exclusive. Most environments will have a mix of different ways that clients use to connect to the IdM domain. Administrators must decide which scenario is best for each individual client.

40.1.1.1. Initial Client Configuration (Pre-Migration)

Before deciding where you want to go with the client configuration in Identity Management, first establish where you are before the migration.
The initial state for almost all LDAP deployments that will be migrated is that there is an LDAP service providing identity and authentication services.
Basic LDAP Directory and Client Configuration

Figure 40.1. Basic LDAP Directory and Client Configuration

Linux and Unix clients use PAM_LDAP and NSS_LDAP libraries to connect directly to the LDAP services. These libraries allow clients to retrieve user information from the LDAP directory as if the data were stored in /etc/passwd or /etc/shadow. (In real life, the infrastructure may be more complex if a client uses LDAP for identity lookups and Kerberos for authentication or other configurations.)
There are structural differences between an LDAP directory and an IdM server, particularly in schema support and the structure of the directory tree. (For more background on those differences, see Section 1.1.2, “Contrasting Identity Management with a Standard LDAP Directory”.) While those differences may impact data (especially with the directory tree, which affects entry names), they have little impact on the client configuration, so it really has little impact on migrating clients to Identity Management.

40.1.1.2. Recommended Configuration for Red Hat Enterprise Linux Clients

Red Hat Enterprise Linux has a service called the System Security Services Daemon (SSSD). SSSD uses special PAM and NSS libraries (pam_sss and nss_sss, respectively) which allow SSSD to be integrated very closely with Identity Management and leverage the full authentication and identity features in Identity Management. SSSD has a number of useful features, like caching identity information so that users can log in even if the connection is lost to the central server; these are described in the System-Level Authentication Guide.
Unlike generic LDAP directory services (using pam_ldap and nss_ldap), SSSD establishes relationships between identity and authentication information by defining domains. A domain in SSSD defines four back end functions: authentication, identity lookups, access, and password changes. The SSSD domain is then configured to use a provider to supply the information for any one (or all) of those four functions. An identity provider is always required in the domain configuration. The other three providers are optional; if an authentication, access, or password provider is not defined, then the identity provider is used for that function.
SSSD can use Identity Management for all of its back end functions. This is the ideal configuration because it provides the full range of Identity Management functionality, unlike generic LDAP identity providers or Kerberos authentication. For example, during daily operation, SSSD enforces host-based access control rules and security features in Identity Management.

Note

During the migration process from an LDAP directory to Identity Management, SSSD can seamlessly migrate user passwords without additional user interaction.
Clients and SSSD with an IdM Back End

Figure 40.2. Clients and SSSD with an IdM Back End

The ipa-client-install script automatically configured SSSD to use IdM for all four of its back end services, so Red Hat Enterprise Linux clients are set up with the recommended configuration by default.

Note

This client configuration is only supported for Red Hat Enterprise Linux 6.1 and later and Red Hat Enterprise Linux 5.7 later, which support the latest versions of SSSD and ipa-client. Older versions of Red Hat Enterprise Linux can be configured as described in Section 40.1.1.3, “Alternative Supported Configuration”.

40.1.1.3. Alternative Supported Configuration

Unix and Linux systems such as Mac, Solaris, HP-UX, AIX, and Scientific Linux support all of the services that IdM manages but do not use SSSD. Likewise, older Red Hat Enterprise Linux versions (6.1 and 5.6) support SSSD but have an older version, which does not support IdM as an identity provider.
When it is not possible to use a modern version of SSSD on a system, then clients can be configured to connect to the IdM server as if it were an LDAP directory service for identity lookups (using nss_ldap) and to IdM as if it were a regular Kerberos KDC (using pam_krb5).
Clients and IdM with LDAP and Kerberos

Figure 40.3. Clients and IdM with LDAP and Kerberos

If a Red Hat Enterprise Linux client is using an older version of SSSD, SSSD can still be configured to use the IdM server as its identity provider and its Kerberos authentication domain; this is described in the SSSD configuration section of the System-Level Authentication Guide.
Any IdM domain client can be configured to use nss_ldap and pam_krb5 to connect to the IdM server. For some maintenance situations and IT structures, a scenario that fits the lowest common denominator may be required, using LDAP for both identity and authentication (nss_ldap and pam_ldap). However, it is generally best practice to use the most secure configuration possible for a client. This means SSSD or LDAP for identities and Kerberos for authentication.

40.1.2. Planning Password Migration

Probably the most visible issue that can impact LDAP-to-Identity Management migration is migrating user passwords.
Identity Management (by default) uses Kerberos for authentication and requires that each user has Kerberos hashes stored in the Identity Management Directory Server in addition to the standard user passwords. To generate these hashes, the user password needs to be available to the IdM server in clear text. When you create a user, the password is available in clear text before it is hashed and stored in Identity Management. However, when the user is migrated from an LDAP directory, the associated user password is already hashed, so the corresponding Kerberos key cannot be generated.

Important

Users cannot authenticate to the IdM domain or access IdM resources until they have Kerberos hashes.
If a user does not have a Kerberos hash[6], that user cannot log into the IdM domain even if he has a user account. There are three options for migrating passwords: forcing a password change, using a web page, and using SSSD.
Migrating users from an existing system provides a smoother transition but also requires parallel management of LDAP directory and IdM during the migration and transition process. If you do not preserve passwords, the migration can be performed more quickly but it requires more manual work by administrators and users.

40.1.2.1. Method 1: Using Temporary Passwords and Requiring a Change

When passwords are changed in Identity Management, they will be created with the appropriate Kerberos hashes. So one alternative for administrators is to force users to change their passwords by resetting all user passwords when user accounts are migrated. The new users are assigned a temporary password which they change at the first login. No passwords are migrated.
For details, see Section 22.1.1, “Changing and Resetting User Passwords”.

40.1.2.2. Method 2: Using the Migration Web Page

When it is running in migration mode, Identity Management has a special web page in its web UI that will capture a cleartext password and create the appropriate Kerberos hash. 
https://ipaserver.example.com/ipa/migration
Administrators could tell users to authenticate once to this web page, which would properly update their user accounts with their password and corresponding Kerberos hash, without requiring password changes.

40.1.2.3. Method 3: Using SSSD (Recommended)

SSSD can work with IdM to mitigate the user impact on migrating by generating the required user keys. For deployments with a lot of users or where users should not be burdened with password changes, this is the best scenario.
  1. A user tries to log into a machine with SSSD.
  2. SSSD attempts to perform Kerberos authentication against the IdM server.
  3. Even though the user exists in the system, the authentication will fail with the error key type is not supported because the Kerberos hashes do not yet exist.
  4. SSSD then performs a plain text LDAP bind over a secure connection.
  5. IdM intercepts this bind request. If the user has a Kerberos principal but no Kerberos hashes, then the IdM identity provider generates the hashes and stores them in the user entry.
  6. If authentication is successful, SSSD disconnects from IdM and tries Kerberos authentication again. This time, the request succeeds because the hash exists in the entry.
That entire process is entirely transparent to the user; as far as users know, they simply log into a client service and it works as normal.

40.1.2.4. Migrating Cleartext LDAP Passwords

Although in most deployments LDAP passwords are stored encrypted, there may be some users or some environments that use cleartext passwords for user entries.
When users are migrated from the LDAP server to the IdM server, their cleartext passwords are not migrated over. Identity Management does not allow cleartext passwords. Instead, a Kerberos principal is created for the user, the keytab is set to true, and the password is set as expired. This means that Identity Management requires the user to reset the password at the next login.

Note

If passwords are hashed, the password is successfully migrated through SSSD and the migration web page, as in Section 40.1.2.2, “Method 2: Using the Migration Web Page” and Section 40.1.2.3, “Method 3: Using SSSD (Recommended)”.

40.1.2.5. Automatically Resetting Passwords That Do Not Meet Requirements

If user passwords in the original directory do not meet the password policies defined in Identity Management, then the passwords must be reset after migration.
Password resets are done automatically the first time the users attempts to kinit into the IdM domain. 
[jsmith@server ~]$ kinit 
Password for jsmith@EXAMPLE.COM: 
Password expired.  You must change it now.
Enter new password: 
Enter it again:

40.1.3. Migration Considerations and Requirements

As you are planning a migration from an LDAP server to Identity Management, make sure that your LDAP environment is able to work with the Identity Management migration script.

40.1.3.1. LDAP Servers Supported for Migration

The migration process from an LDAP server to Identity Management uses a special script, ipa migrate-ds, to perform the migration. This script has certain expectations about the structure of the LDAP directory and LDAP entries in order to work. Migration is supported only for LDAPv3-compliant directory services, which include several common directories:
  • Sun ONE Directory Server
  • Apache Directory Server
  • OpenLDAP
Migration from an LDAP server to Identity Management has been tested with Red Hat Directory Server and OpenLDAP.

Note

Migration using the migration script is not supported for Microsoft Active Directory because it is not an LDAPv3-compliant directory. For assistance with migrating from Active Directory, contact Red Hat Professional Services.

40.1.3.2. Migration Environment Requirements

There are many different possible configuration scenarios for both Red Hat Directory Server and Identity Management, and any of those scenarios may affect the migration process. For the example migration procedures in this chapter, these are the assumptions about the environment:
  • A single LDAP directory domain is being migrated to one IdM realm. No consolidation is involved.
  • User passwords are stored as a hash in the LDAP directory. For a list of supported hashes, see the passwordStorageScheme attribute in the Password Policy Attributes table in the Red Hat Directory Server 10 Administration Guide.
  • The LDAP directory instance is both the identity store and the authentication method. Client machines are configured to use pam_ldap or nss_ldap to connect to the LDAP server.
  • Entries use only the standard LDAP schema. Entries that contain custom object classes or attributes are not migrated to Identity Management.

40.1.3.3. Migration — IdM System Requirements

With a moderately-sized directory (around 10,000 users and 10 groups), it is necessary to have a powerful enough target system (the IdM system) to allow the migration to proceed. The minimum requirements for a migration are:
  • 4 cores
  • 4GB of RAM
  • 30GB of disk space
  • A SASL buffer size of 2MB (default for an IdM server)
    In case of migration errors, increase the buffer size: 
    [root@ipaserver ~]# ldapmodify -x -D 'cn=directory manager' -w password -h ipaserver.example.com -p 389

dn: cn=config
changetype: modify
replace: nsslapd-sasl-max-buffer-size
nsslapd-sasl-max-buffer-size: 4194304

modifying entry "cn=config"
    Set the nsslapd-sasl-max-buffer-size value in bytes.

40.1.3.4. Migration Tools

Identity Management uses a specific command, ipa migrate-ds, to drive the migration process so that LDAP directory data are properly formatted and imported cleanly into the IdM server. When using ipa migrate-ds, the remote system user, specified by the --bind-dn option, needs to have read access to the userPassword attribute, otherwise passwords will not be migrated.
The Identity Management server must be configured to run in migration mode, and then the migration script can be used. For details, see Section 40.3, “Migrating an LDAP Server to Identity Management”.

40.1.3.5. Improving Migration Performance

An LDAP migration is essentially a specialized import operation for the 389 Directory Server instance within the IdM server. Tuning the 389 Directory Server instance for better import operation performance can help improve the overall migration performance.
There are two parameters that directly affect import performance:
  • The nsslapd-cachememsize attribute, which defines the size allowed for the entry cache. This is a buffer, that is automatically set to 80% of the total cache memory size. For large import operations, this parameter (and possibly the memory cache itself) can be increased to more efficiently handle a large number of entries or entries with larger attributes.
    For details how to modify the attribute using the ldapmodify, see corresponding section in the Red Hat Directory Server Performance Tuning Guide.
  • The system ulimit configuration option sets the maximum number of allowed processes for a system user. Processing a large database can exceed the limit. If this happens, increase the value: 
    [root@server ~]# ulimit -u 4096
For further information, see Red Hat Directory Server Performance Tuning Guide at https://access.redhat.com/documentation/en-US/Red_Hat_Directory_Server/10/html-single/Performance_Tuning_Guide/index.html.

40.1.3.6. Migration Sequence

There are four major steps when migrating to Identity Management, but the order varies slightly depending on whether you want to migrate the server first or the clients first.
With a client-based migration, SSSD is used to change the client configuration while an IdM server is configured:
  1. Deploy SSSD.
  2. Reconfigure clients to connect to the current LDAP server and then fail over to IdM.
  3. Install the IdM server.
  4. Migrate the user data using the IdM ipa migrate-ds script. This exports the data from the LDAP directory, formats for the IdM schema, and then imports it into IdM.
  5. Take the LDAP server offline and allow clients to fail over to Identity Management transparently.
With a server migration, the LDAP to Identity Management migration comes first:
  1. Install the IdM server.
  2. Migrate the user data using the IdM ipa migrate-ds script. This exports the data from the LDAP directory, formats it for the IdM schema, and then imports it into IdM.
  3. Optional. Deploy SSSD.
  4. Reconfigure clients to connect to IdM. It is not possible to simply replace the LDAP server. The IdM directory tree — and therefore user entry DNs — is different than the previous directory tree.
    While it is required that clients be reconfigured, clients do not need to be reconfigured immediately. Updated clients can point to the IdM server while other clients point to the old LDAP directory, allowing a reasonable testing and transition phase after the data are migrated.

    Note

    Do not run both an LDAP directory service and the IdM server for very long in parallel. This introduces the risk of user data being inconsistent between the two services.
Both processes provide a general migration procedure, but it may not work in every environment. Set up a test LDAP environment and test the migration process before attempting to migrate the real LDAP environment.

[6] It is possible to use LDAP authentication in Identity Management instead of Kerberos authentication, which means that Kerberos hashes are not required for users. However, this limits the capabilities of Identity Management and is not recommended.