Migrating LDAP passwords to FreeIPA Kerberos keys

Migrating LDAP passwords to FreeIPA Kerberos keys without forced resets

Users keep their LDAP passwords when the directory's password hashes can be read and verified, and the first login generates Kerberos keys in FreeIPA. A team that wants no mass password reset should confirm this before any user is moved. The user and group import uses the ipa migrate-ds command, which excludes Kerberos attributes because FreeIPA regenerates them, as the FreeIPA migration how-to explains. During the migration window, password migration mode lets the FreeIPA server accept the old password once. SSSD then keeps the user signed in through the normal Kerberos path, and the server stores new keys from that login. Ask your directory administrators which hash schemes the source server stores, and test a sample of accounts against a copy of the directory before you enable the mode.

Hash availability decides how much work remains. Users with usable hashes need no action beyond logging in, so the effort sits in the test migration, the client configuration and the monitoring of first logins. Users whose hashes cannot be migrated, such as accounts bound to an external authentication source or stored in an irreversible format, need another path. Plan a migration web page where the user proves identity to a system you control and then sets a new password, or a helpdesk procedure for the same result. Also list service accounts, shared accounts and any application that binds to LDAP with a stored password, because these do not behave like interactive users. When you request a quote, ask for these items as separate line items: the hash inventory, the test migration, the web page or helpdesk procedure, and the exception accounts.

What maps cleanly and what does not for LDAP passwords

This table compares what a source LDAP directory holds for passwords, tokens and policy with what FreeIPA can take over during migration. Read each row as a question to answer before cutover: what is copied directly, what FreeIPA regenerates, and what needs a separate workstream.

Capability	Source LDAP directory	FreeIPA after migration
Plain or hashed user passwords	Stored as userPassword values, often salted hashes such as SSHA or crypt	Not copied as usable Kerberos keys by migrate-ds; confirm which hash schemes your source exposes and whether the migration mode can use them
Kerberos attributes	Present only if the source already runs a Kerberos realm tied to the directory	Excluded from ipa migrate-ds because FreeIPA regenerates Kerberos keys and principal data itself
Keys issued at first login	Not applicable	SSSD can trigger key generation when a migrated user logs in with the old password, provided migration mode is enabled
OTP tokens	Usually stored in a separate token store or vendor system, not in the user entry	Not carried by migrate-ds; FreeIPA OTP tokens need a separate import or re-enrollment plan
Password policy and lockout	Often set by overlay modules or application logic outside the directory schema	Recreated as FreeIPA password policies per group; map each rule explicitly rather than assuming it carries over
Users without a usable hash	Accounts bound to external authentication, service accounts or disabled entries	Need a planned reset path, a different login method or a documented exception list before cutover

Which password hashes can migrate and which users need a manual path

Some source directories store password material that FreeIPA can use to build the user's Kerberos keys when the user first authenticates. In password migration mode, the user keeps the existing password, and SSSD on the client helps generate the Kerberos keys at the first successful login, so no forced reset is needed. The schemes that can be verified depend on the FreeIPA version and the source server, so treat the points below as checks to run, not guarantees.

Hash scheme. Identify the scheme stored in userPassword for each account, such as salted SHA variants or crypt-based hashes, and confirm support in the FreeIPA migration how-to for your version.
Reversible storage. Confirm whether any entries hold plaintext or reversibly encrypted passwords, since those need separate handling and their own risk review.
Login path. Confirm that the SSSD and PAM settings on test hosts let the first login trigger key generation, and test with one account before each wave.
Password policy. Check that existing passwords meet the FreeIPA password policy, because a weak legacy password may be accepted during migration but flagged later.
Fallback guidance. Tell users in advance what to do if the first login fails, and name the team that answers those requests.

Before the first wave, count the accounts in each scheme from a copy of the source directory so the administrator knows how many users will sign in without intervention.

Some entries cannot be verified at all. The source may hash passwords with a one-way scheme that FreeIPA does not support, store a value the administrator cannot export, or hold no password at all. These users cannot prove an existing password, so they need a manual path, such as an administrator-set temporary password or a reset through the migration web page, depending on how the deployment is configured.

Unsupported schemes. Accounts using a scheme outside the supported list stay unusable until reset, so list them from a directory export before cutover.
Missing or placeholder values. Accounts with no userPassword value, or with a placeholder, need a reset path and should not be counted as migrated.
Application-bound accounts. Entries used by applications that authenticate with a shared secret may have no human password to verify, so identify their owners.
Lockout and expiry state. Decide whether locked or expired source accounts keep that status in FreeIPA, and make the decision before the migration starts.
User notice. Tell affected users in writing that a reset is required, along with the channel and identity check the help desk will use.

Ask the directory administrator for a list of these accounts with an owner and a reset method for each, and keep them out of the first migration wave until those steps are complete.

Documented tools for moving users and passwords into FreeIPA

FreeIPA documents three routes for bringing accounts in: the migrate-ds command for LDAP sources, the password migration mode that supports it, and ipa-migrate for FreeIPA-to-FreeIPA moves. Each route handles credentials differently, so the choice of tool decides whether users keep their passwords, need a guided transition, or must set a new one.

The ipa migrate-ds command

This is the documented route for copying users and groups from another LDAP server into FreeIPA. It excludes Kerberos attributes because FreeIPA regenerates them, so the command alone does not give users working Kerberos keys. Check which attributes your source directory stores and confirm, on a test copy, which ones the command skips before planning the cutover.

Password migration mode

Password migration mode is the setting that lets FreeIPA accept a user's existing LDAP password once and create Kerberos keys from it. It is the mechanism that keeps users from needing a forced reset. Confirm how your source stores password hashes, since a hash that FreeIPA cannot verify will not produce working keys.

Migration web page

The migration web page lets a user prove their identity with the old password and set a new one in FreeIPA. It fits users whose hashes cannot be migrated or who never log in during the window. Decide who hosts the page, how users reach it, and how the team handles accounts still unmigrated when the window closes.

ipa-migrate for FreeIPA moves

ipa-migrate moves users, groups, certificates, sudo and HBAC rules, hosts, services, DNS, OTP tokens and policies between two FreeIPA deployments over LDAP. It is the route for consolidating or rebuilding a realm rather than importing from an LDAP source. Confirm with the documentation whether credential data and Kerberos keys transfer in your version, and plan for client re-enrollment and password follow-up either way.

Manual rules and policy transfers

Sudo and HBAC rules do not come across with migrate-ds and must be exported as LDIF and recreated by hand. These objects carry access decisions, so a missed rule can lock users out or open a host to the wrong group. Build an inventory of rules per host group and test each one before any user logs in through FreeIPA.

Which paths carry passwords

An LDAP import with migrate-ds needs password migration mode to produce Kerberos keys at first login, while the FreeIPA-to-FreeIPA path is the one to test for credential transfer in your version. Users whose source stores hashes FreeIPA cannot use will need the web page or a reset. Write this matrix down per source system before scheduling any user communication.

Sequence for a pilot, parallel run and cutover of migrated logins

This sequence moves migrated LDAP users to FreeIPA in controlled stages, so each group proves its logins work before the next group is exposed. It ends with a documented cutover and a planned retirement of migration mode.

Inventory password hash types and users
Export a list of every user in the source LDAP directory with the password hash scheme stored for each account, and count users per scheme. Mark accounts with no usable hash, accounts with schemes you do not expect, and accounts that authenticate through other services such as SSH keys or application-specific secrets. Confirm with the directory owner which schemes the migration will read, and record the result as the baseline for every later checkpoint. The step is done when each user has a recorded hash category and an owner has signed off on the list.
Run a test migration on a copy
Load a copy of the source directory into a non-production FreeIPA server, run the user and group migration with migration mode enabled, and attempt logins from a test client enrolled in that environment. Compare results with the inventory from the previous step to confirm which users authenticate with their existing password and which need a reset. Record every failure with its cause, fix the mapping or policy, and repeat until the failures are limited to the categories you have already accepted. The step produces a written test report that the pilot owners review.
Enable migration mode for a pilot group
Choose a small pilot group of users whose work tolerates interruption, and confirm that migration mode is enabled only for the source of those accounts in production. Confirm with the identity team that the migration web page is reachable for pilot users and that help desk staff know the expected messages. Check that the pilot accounts log in on the target clients and that Kerberos keys are generated at first successful login. The checkpoint is a list of pilot logins with outcomes, and no pilot user is locked out without a documented path back.
Enroll clients and run a parallel period
Enroll the Linux clients that the pilot group uses into FreeIPA and keep the legacy LDAP authentication path available for the same users during the overlap. Track which authentication path succeeds for each login, and watch for SSSD errors, Kerberos ticket failures and users whose keys have not yet been generated. Hold the parallel run until pilot users have logged in successfully on each client type they use. The output is a per-client record of enrollment status and login success that supports the go or no-go decision.
Decide whether to proceed
Review the pilot and parallel run results with the application owners, the security team and the help desk before any further population is moved. Proceed only if the failures are understood, no unexpected hash categories appear in production, and the rollback steps have been rehearsed on the copy. Record the decision, the named approver and any conditions. If the checkpoint fails, return to the test migration with the new findings rather than widening the population.
Cut over the remaining population in waves
Move the rest of the users in groups that match the inventory categories, starting with the accounts that have the most standard hashes and leaving users with unusual or missing hashes for last. After each wave, confirm login success, count the users who still need a password reset, and confirm that the migration web page handles their first login. Keep the source directory read-only for the moved accounts so changes are not split across two systems. The step is complete when every planned wave has a recorded login result and a list of accounts still awaiting keys.
Handle users who cannot be migrated
Work through the accounts whose hashes could not be read or converted, and agree with each owner whether the account gets a forced reset, a temporary credential issued through an approved process, or removal. Confirm the identity of each user through a method the organization already accepts before any password is set. Track these accounts in a separate list until each one has a working login or a documented decision. The output is a closed list with an outcome for every account.
Retire migration mode and document the result
Once every planned account has a working login or a documented outcome, disable migration mode and confirm that FreeIPA no longer accepts the legacy password path for migrated accounts. Update the runbook, retire the migration web page where it is no longer needed, and archive the inventory, test report and checkpoint records. Ask your vendor or the FreeIPA documentation to confirm the exact steps for your release before changing production settings. The step is done when the change is recorded, the legacy directory is scheduled for retirement, and an owner is named for ongoing support.

What drives the effort of a password migration

This table lists the factors that change how much work a password migration into FreeIPA takes, the direction each one pushes cost, and the question to put to a partner or your own team before agreeing scope. Read it as a checklist: the rows that push effort up most are the ones to size first, before any quote is requested.

Driver	Why it changes effort	Question to ask in a quote
Hash scheme variety	Each scheme in the LDAP directory needs its own handling. Schemes that cannot be verified or converted leave some users without a migrated password, which adds reset work.	Which password hash schemes exist in our directory, and which users will need a reset because their hashes cannot be migrated?
Number of users and client hosts	More accounts mean more testing samples and more login checks. More client hosts mean more SSSD configuration to confirm before cutover.	How many accounts and enrolled hosts are in scope, and how will login tests be sampled across them?
Dependence on LDAP binds	Applications and SSO gateways that bind directly to LDAP keep working only if they are reconfigured or tested, so each one adds integration work.	Which applications bind to LDAP with user passwords, and which of them must move to Kerberos or another method?
OTP token count	Migrated OTP tokens need to be re-associated and tested with each user. Tokens that cannot be moved add enrollment work for affected users.	How many OTP tokens exist, and what is the plan for re-enrolling tokens that do not carry over?
Password policy alignment	Differences between the old directory policy and FreeIPA password policy (complexity, history, lockout) create exceptions to review and document.	Which password rules do we enforce today, and how will each map to a FreeIPA password policy?
Number of sites with replicas	Each site with its own replica must be checked for consistent Kerberos key generation and for SSSD behavior at first login, which multiplies verification work.	How many sites and replicas will be involved, and how will replication be verified after the migration runs?

What usually goes wrong with password migration and how to prevent it

Password migration fails in predictable ways, and most of them are visible before cutover if someone checks for them. The cards below cover the failures that lock users out, break service accounts, or leave a topology in a state nobody intended. Each one has a check you can run before the migration window opens.

Users whose hashes cannot migrate

Some source directories store passwords as one-way hashes that the migration path cannot convert into Kerberos keys, so those accounts have no usable key after import. Users with these hashes are locked out at their first login unless you plan for it. Before cutover, export a count of accounts by password scheme from the source directory and decide, for each group, whether they will set a new password through the migration web page or through an administrator-led reset. Confirm the exact hash schemes your directory uses against the migration documentation.

Applications binding with the old password

Applications, scripts and service accounts that bind to LDAP with a user's password keep working only if the password they hold still validates after migration. Once a user changes their password in FreeIPA, those binds fail silently in many tools. Inventory every application that performs LDAP simple binds or stores credentials, and move each one to a dedicated service account or Kerberos keytab before the first user changes a password. Test each one against a copy of the environment.

Clients not enrolled before cutover

Linux hosts that are not enrolled as IPA clients cannot use Kerberos keys generated for their users, and SSSD on those hosts still points at the old directory. Users then see logins fail on machines that were never moved, which looks like a password problem but is not. Build an inventory of hosts, confirm each one has SSSD configured for the new realm, and enroll the rest before the migration window. Test a login from a representative host in each host group.

Restoring an outdated backup into the topology

If a backup taken before migration is restored into a replica topology that is already running, the restored server can carry stale data that conflicts with the replicas. FreeIPA's backup guidance warns that this can break replication. Make a fresh backup immediately before the migration starts, record which server holds the backup, and never restore a server into a live topology without first confirming that its data is newer than the replicas it will join. Use a test environment to rehearse the restore path.

Migration mode left switched on

Password migration mode lets FreeIPA accept a user's old password once and generate Kerberos keys from it. If the setting is left on after the migration period ends, accounts remain open to password checks that should have stopped, and the policy you documented does not match the running system. Write the enable and disable steps into the cutover runbook with named owners, and add a check to your post-migration review that confirms the setting is off. Record the date the setting was changed so auditors can trace it.

Questions buyers ask about FreeIPA password migration

Do migrated users have to reset their passwords?

Not necessarily. Whether a user must reset depends on whether their existing password can be carried into FreeIPA's Kerberos keys, and on how the migration is run. Accounts whose stored credentials can be used for that purpose can keep their password, while accounts whose credentials cannot be migrated will need a new password before they can authenticate. Confirm this per directory before cutover: export a sample of accounts from your existing LDAP server, identify which credential formats are stored, and check them against the migration documentation. The FreeIPA migration how-to explains what the migration tooling carries across and what it does not, including Kerberos attributes that FreeIPA regenerates on its own.

What drives the cost of a FreeIPA password migration?

Cost follows the amount of analysis, build and testing the migration needs, not the number of passwords alone. The main drivers are:

The number of source directories, realms and credential formats in use
How many user, group and host objects must be reconciled before cutover
Whether a staging copy is built and tested before production
How many SSSD clients need enrollment checks and how many host groups are phased
The help desk and communication work needed for users who must set a new password

Most of this is one-time effort: scoping, building the procedure, testing and cutover support. Recurring costs appear only if you keep a support or upgrade retainer afterward. Ask for a quote that itemizes these items separately, and confirm whether the work is fixed-scope with deliverables agreed in writing before work starts.

How long does a FreeIPA password migration take?

The duration depends on the drivers of the work, and no fixed figure applies to every directory. The biggest factors are the size and condition of the source directory, the number of credential formats that need separate handling, how many clients and host groups must be phased, and how long testing on a copy takes before any production change. Organizations with clean directories and a small number of clients typically finish sooner than those with mixed sources or many systems that depend on existing passwords. Ask for the timeline in writing as part of the scope, with the testing and cutover phases listed separately so you can see where schedule risk sits.

What must our team provide before the migration starts?

Your team provides access and decisions. Expect to supply:

Read access to the source LDAP directory, plus a copy for testing that is separate from production
A working FreeIPA deployment with its replicas and the current server layout
An inventory of Linux hosts, SSSD clients and the services that authenticate against them
Your password policy decisions, including whether users may keep existing passwords
Approved change windows, help desk contacts and a user notice plan
A current backup taken with the FreeIPA backup tooling

The backup step matters. FreeIPA's backup documentation warns that restoring an outdated backup into an active replica topology can break replication, so take a fresh backup immediately before cutover and record which server holds certificate renewal duties.

Can an internal team run a FreeIPA password migration alone?

Yes, if the team already has working knowledge of 389 Directory Server, MIT Kerberos and SSSD, and enough time to test on a copy before touching production. The main risks are untested credential handling, incomplete client coverage and cutover mistakes that lock users out. Before deciding, ask three questions: has anyone on the team migrated a directory into FreeIPA before, is there a staging environment that mirrors production, and who owns the rollback if a host group fails. DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, so a partner can cover the gaps, handle the build and hand over the runbook, or stay on a retainer after cutover.

Which users cannot have their passwords migrated?

Accounts fall into this group when their stored credentials cannot produce Kerberos keys in FreeIPA, when no password is stored at all, or when authentication happens through another system. Common examples include accounts that rely only on external single sign-on, service accounts that never used an interactive password, and accounts whose hash format is not supported by the migration path you choose. Treat these as a separate list during planning. Each group needs its own route, such as a password set through the migration web page at first sign-in or an administrator-driven reset. Confirm the supported credential formats against the FreeIPA documentation for your release before you classify any account.

How does SSSD create Kerberos keys at first login?

In general terms, a migrated user who signs in for the first time proves knowledge of the password, and the client-side and server-side components then generate the Kerberos keys that FreeIPA needs for later authentication. After that, the user logs in normally. Confirm the exact sequence for your FreeIPA and SSSD versions before relying on it. Check that each client runs an SSSD release that supports the flow, that it can reach the KDC and the IdM servers over the expected names, and that time synchronization is correct, since Kerberos fails when clocks drift. Test with one pilot host group first, and record the login results from each client type you run.

How DeployOpen works on this

DeployOpen plans, implements, tests, documents and supports FreeIPA inside your own infrastructure, so the password migration runs on servers you control. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

Inventory which LDAP password hash schemes exist and which users fall outside migration.
Define which user populations enter password migration mode and which stay on existing logins.
Agree in writing which clients, SSSD versions and login paths the migration must cover.

How we build

Configure password migration mode and the migration web page on a staging copy of the realm first.
Test first login on representative Linux clients to confirm SSSD generates Kerberos keys correctly.
Document the reset path for accounts whose hashes cannot be migrated, and test it before cutover.

How we hand over

Deliver the written configuration, test results and the list of accounts needing manual reset.
Provide a cutover runbook with checkpoints, rollback steps and the order of client changes.
Train your administrators on monitoring login counts so you can confirm migration progress.

How we support

Offer ongoing support and upgrades as a retainer after handover, scoped separately in writing.
Review migration progress and remaining unmigrated accounts with your team at agreed points.
Confirm the migration mode is switched off and documented once your user population is complete.

Migrating LDAP passwords to FreeIPA Kerberos keys