How to Import Legacy Usernames with Non-Allowed Characters

Knowledge Articles
, , , ,
1

Problem statement

Auth0 has a defined list of allowed characters that can be used for a user profile’s ‘username’ value. This can be an issue in custom database migration scenarios, where the legacy custom database and users have usernames that are not compatible with Auth0’s username validation.

Are there any potential options to mitigate this issue so that users from a legacy database can migrate their profiles into Auth0? What are some potential options to mitigate this issue so users from a legacy database can migrate their profiles into Auth0?

Solution

Currently, Auth0 does not have the means to relax username validation on a tenant or connection level to allow for user migration into Auth0. However, the following are some potential workarounds that may be suitable depending on the use case and intended user journey. Note the three options listed are suggestions on how to approach this issue and should be rigorously tested to confirm if any of the options will apply to a given user migration scenario.

Option 1:

Auth0 does not enforce the allowed characters mentioned previously in a custom database with migration turned off. The downside of this option is that the legacy database will still be the source of the truth, and the passwords will still be stored only on the legacy database.

Option 2:

  1. It is possible to fully customize the Classic Universal Login so that a user can input their non-valid username, which would then be sent to the custom database scripts.
  2. The custom database scripts would validate the credentials against the legacy database.
  3. If the credentials are correct, the script returns a username like “newuser” for example. This new identifier would then be appended to a unique random string (e.g., “newuser-RANDOM-STRING”).
  4. Implement an Action to check the username. If the username has “newuser” in it, force a redirect to a page where the user is notified to change their username with the allowed characters.
  5. The user enters their new username, and the application updates the username using the Management API and redirects the user to your login entry point to re-authenticate, as updating the username will invalidate the Auth0 session.

Option 3:

If it Is possible to have the users only log in with their emails, the legacy user names could be stored in the app_metadata of the user profile within the custom database script while they are imported. This can help to insert the user’s legacy user name in a custom claim in the Access or ID Token. With that addition, the username can still be used in downstream apps. The only side-effect is that users cannot log in with their username and must log in solely with their email.