A password migration is not a database copy. When users move between identity providers, the source often cannot provide a password that the target can reuse. Even when an export contains password hashes, a hash produced for one platform is not automatically valid on another.
Users can sometimes keep their existing password without a forced reset. The safe method depends on what the source can export, whether it can validate passwords online, how long it can remain available and whether the migration can bind each account to a stable source identifier.
This article provides a decision framework for choosing between compatible import, gradual password validation, continued external validation and a controlled password reset. It focuses on the password path; application protocols, claims, multi-factor authentication (MFA) enrolment and the complete cut-over plan must still be handled as connected migration workstreams.
Start with the source, not the preferred user experience
“No password reset” is a desirable outcome, but it is not yet a migration method. Before selecting an approach, establish what the source can actually support:
- Can it export clear-text passwords or a password representation that the target explicitly supports?
- Can it validate a user's current password through a protected validation API?
- Can that API remain available, monitored and supported throughout a gradual migration and rollback window?
- Is there a stable, immutable source user ID that can bind the same account across identifier changes?
- Can password changes and resets remain consistent while two systems are involved?
- Do security policy, contracts and risk assessment allow password material to be imported or retained?
Do not use email address, phone number or username as the only migration key. Those identifiers can change. A mistaken account match is more serious than a reset because it can bind credentials and access to the wrong identity.
Choose one of four password paths
Different user populations may need different paths. For example, active employees may migrate gradually through online validation while dormant external accounts receive a reset when they return.
| Source capability and constraint | Defensible path | Main benefit | Main cost or risk |
|---|---|---|---|
| Passwords or a target-compatible password representation are available and can be handled securely | Controlled batch import | Users can authenticate in the target immediately | Export, transport and processing of password material expand the security boundary |
| The source can validate existing passwords online and remain authoritative during transition | Gradual migration with Directory Connector | Active users move on successful sign-in without a mass reset | The source and connector remain in the production authentication path until cut-over |
| Users are already provisioned in FoxIDs and only password validation, policy checking or change notification remains external | External Password API | Keeps a narrower password-store or policy integration | It does not provide the same user creation and profile synchronisation flow as Directory Connector |
| No secure compatible import or reliable online validation exists | Verified password reset | Establishes a new target credential with a clear trust boundary | User communication, recovery channels and support capacity become critical |
The answer is therefore not always “preserve” or always “reset”. Select the least disruptive path that can still be defended technically and operationally for each population.
Gradual migration with Directory Connector
Directory Connector is the main FoxIDs pattern when an existing directory or custom repository must remain authoritative during transition.
When a user signs in with a password, FoxIDs calls the connector API. After successful validation, FoxIDs creates or updates the internal user from the returned identifiers, properties and claims. The response includes a stable directoryUserId, which binds the FoxIDs user to the source account even if the user's email address, phone number or username later changes.
This creates a practical just-in-time sequence:
- The user signs in to an application through FoxIDs with the existing identifier and password.
- FoxIDs asks the source directory to validate the password.
- The connector returns the stable source ID and approved user data.
- FoxIDs creates or updates the internal user and completes authentication.
- The user can continue with the existing password while that source remains authoritative.
By default, FoxIDs also saves a local password copy after successful connector validation or a connector password lifecycle operation. That copy creates an option for a later planned switch to FoxIDs password validation without resetting every user who has completed the gradual flow.
The boundary matters: while Directory Connector is enabled, the external directory remains authoritative. FoxIDs does not use the saved local hash as an automatic fallback if the connector is unavailable. A connector outage is therefore an authentication-path failure, not an instruction to bypass the source.
The password-policy switch shown below is a third, independent decision. It controls whether FoxIDs checks a proposed password against the FoxIDs environment policy before calling the connector. The external directory still owns the password and can reject it according to its own policy. If both checks are used, align their requirements and user guidance.
Define exit criteria before enabling the connector
A gradual migration needs an end condition. Decide before rollout:
- Which user populations must complete a successful sign-in before cut-over?
- How will inactive or never-returning accounts be handled?
- How long must the source and connector remain available for rollback?
- Which connector latency and failure rates stop or reverse the rollout?
- How will identifier conflicts, missing claims and disabled or deleted source accounts be investigated?
- When can the connector be disabled and FoxIDs become authoritative for passwords?
Saving a local copy is optional. Disable it when policy requires the source to remain the only password store, but recognise that this removes that path to a later no-reset switch.
When External Password API is the narrower fit
FoxIDs can configure an External Password API as a password check for internal users. It can validate a current password, validate a new password against an external policy, notify another system about password changes, or combine these responsibilities.
Use this option when the users already exist in FoxIDs and the remaining requirement is specifically about the password store or password policy. Do not treat it as a substitute for Directory Connector when the migration also needs just-in-time user creation, a stable external directory binding, profile updates or external account lifecycle handling.
This distinction keeps the integration boundary explicit: Directory Connector represents an authoritative external directory; External Password API represents an external password validation, policy or notification dependency for internal users.
When batch import is justified
Batch import can remove the runtime dependency on the source, but only when the input is suitable for the target and can be protected throughout the transfer.
FoxIDs supports uploading internal users with known passwords, with FoxIDs-compatible precomputed password hashes, or without passwords. A hash from an arbitrary source platform cannot simply be labelled as a FoxIDs hash. Confirm the exact algorithm, salt and target format before deciding that an exported hash is reusable.
Treat clear-text password export as a security decision, not a convenience. Limit access, use a controlled transfer path, prevent passwords from entering logs or ordinary project files, verify deletion of temporary material and document who approved the operation. If that handling cannot be justified, choose online validation or reset instead.
When password reset is safer
A reset is not necessarily evidence of a failed migration. It is the honest path when retaining the existing credential would weaken the target or depend on assumptions the team cannot verify.
Prefer a controlled reset when:
- the source cannot export a compatible representation or validate the current password online;
- moving password material would create an unacceptable exposure or contractual problem;
- the source credential is subject to a known or suspected compromise;
- accounts cannot be correlated to stable source identities with sufficient confidence;
- the source cannot remain reliable for the required gradual-migration and rollback period; or
- preserving the old password would require weaker target controls.
FoxIDs users can be uploaded without passwords and asked to set one using a verification code sent by email or SMS. That is only safe when the recovery identifier belongs to the intended user and the delivery channel meets the organisation's risk requirements. Test expired codes, inaccessible inboxes or phone numbers, duplicate identifiers, locked accounts and support escalation before a broad rollout.
Communicate the reason and timing before users encounter the reset. Separate the security decision from the support plan: a sound reset design can still fail operationally if recovery channels are stale or the help desk cannot handle the initial demand.
Require evidence before password cut-over
Test the selected path in a separate FoxIDs environment and move a controlled population first. A successful login is necessary but not sufficient.
| Decision area | Evidence required before wider rollout |
|---|---|
| Identity binding | Stable source IDs, tested identifier changes and defined handling of duplicates or missing users |
| Password behaviour | Successful and rejected passwords, expired-password flow, password change/reset and policy errors |
| Availability | Connector or validation API monitoring, timeouts, failure handling and named operational owner |
| User migration | Pilot results for representative active, inactive, disabled and restricted accounts |
| Security | Approved handling of password material, protected secrets, diagnostic logging without passwords and reviewed data retention |
| Cut-over | Population-specific exit criteria, treatment of users without a saved target credential, rollback trigger and source retirement owner |
Keep the source available until the required population has migrated and the rollback window has closed. Do not disable the connector merely because the pilot succeeded; verify the target password path for the population that must work after cut-over and retain a controlled reset route for the remainder.
How FoxIDs supports the decision
Use the migration documentation to plan applications, users, passwords, cut-over and rollback together. The Directory Connector documentation, External Password API documentation and user upload documentation contain the exact implementation details.
If the source capabilities, user populations or cut-over criteria are not yet clear, FoxIDs Identity Migration describes how the team behind the platform can help design and deliver the migration.
Conclusion
Users can keep an existing password only when the migration preserves a trustworthy validation path or establishes a compatible target credential securely. Directory Connector often provides the least disruptive gradual path, but it also keeps the source in the production authentication flow until a deliberate cut-over.
Choose reset when compatibility, identity binding or secure handling cannot be demonstrated. The right password strategy is the one that makes the source of truth, failure behaviour, user impact and exit criteria explicit before production traffic moves.