Passthrough migration

This guide describes the passthrough strategy for migrating password-based login from your existing system to Userfront.

Using this approach, you get a standard set of client-side interactions for all new and existing users while you migrate your login to a new system.

Userfront does not store user passwords in a recoverable format (it stores a hash), and this guide assumes that your system also does not store passwords in a recoverable format.

#How the passthrough works

The first time an existing user attempts to log into your application with Userfront, we forward their request to your old login system using whatever format your old system uses.

Based on the response from your old system, Userfront either logs the user in and stores their password hash for future use, or rejects the login along with a message based on your old system's response.

Passthrough diagram

#Passthrough steps

To perform a successful password migration:

  1. Import your existing user data into Userfront, excluding passwords. You can use CSV upload for smaller data sets, or for larger data sets.

  2. Set up a passthrough route. Userfront passes user login requests through to your old system and observes the responses in order to automatically generate a database of password hashes.

  3. Choose your password transfer window. Run the passthrough for as long as desired: typically 1-6 months, or until 90-100% of active users have transferred. As each user's password is verified, Userfront stores their password hash and can handle their subsequent logins directly. Userfront also gives you regular statistics about the transfer process.

  4. Once you are finished transferring, disconnect the passthrough. Users who did not log in during the password transfer window are prompted to reset their password upon their next login.

#Example of a successful login

In this example, we show an existing user's login request during the password transfer window.

First, the user submits their information to Userfront based on the standard Log in with password endpoint.

This can be done with the toolkit login form, the Core JS login() method, or by sending to the API endpoint directly.

Userfront forwards this information to your old login system based on your desired format, and optionally adds a passthroughCode.

Your old login system responds as it normally would, with an optional passbackCode.

Typically, your old system would respond with either a 200 response for success or a 4XX response for failure.

In this example, your old system responds with 200 for success.

From this point forward, Userfront stores a hash of the user's password and can handle future login requests without the passthrough.

#Response to the client

For all successful login requests (passthrough or not), Userfront generates a standard response based on the Log in with password endpoint and sends this response to the client.

If you are using the toolkit login form or Core JS login() method on the client, this response is handled automatically and the user is logged in.

Using this approach, you get a standard set of client-side interactions for all new and existing users while you migrate your login to a new system.

#Set up a passthrough

Please if you are interested in setting up a passthrough route.

We can work with you to map the passthrough requests and responses to your existing system, as well as assist with any other transition topics or questions you may have.