How to Convert Usernames

Customer Managed Applies to customer-managed instances of Alation


This instruction does not work for V R7 (5.12.x), 2020.3, and 2020.4 (a known issue). If you need to update usernames in these releases, please create a ticket for Alation Support.

From version 2021.1, the script works as expected.

Sometimes there is a need to update usernames of particular users after you switch from built-in authentication to LDAP or SAML. This article explains how to do this using a script.


Create a CSV file with two columns having no headers. List old usernames in the first column and new ones in the second one.

Converting usernames

To convert usernames,

  1. Sign into the Alation shell as the administrator.

    sudo service alation shell
  2. Change the user to alation.

    sudo su alation
  3. Change to the /opt/alation/bin/ directory.

  4. Run the following script:

    alation_convert_local_account --file=PATH_TO_CSV_FILE

Successful Completion

The script will print updated usernames and errors if any occurred. Admin user can review all the usernames by logging into the Alation instance and navigating to the Users section of Admin Settings.

New usernames should not exist in the system. If a username needs to be updated to an already existing one, do this using a temporary username that does not exist in the system. If, for example, there is a need to rename to and the latter already exists, add the following two lines to the CSV file:

Admin user can suspend after the script has been run.