Migrating Existing Users

Workbench

It is possible to migrate existing users who were provisioned locally or through sssd/Active Directory (AD) to Workbench user provisioning.

Caution

If you are upgrading from version 2023.06 or earlier and are turning on Workbench user provisioning for the first time, it is recommended to back up your database before proceeding with local user migration. See the User migration when coming from 2023.06 or earlier section below for more information.

When a user is provisioned to Workbench through a supported Identity Provider (IdP), the IdP first queries Workbench to check for an existing user via username. Workbench will match the username provided by the IdP to the user_name field in the database.

If a user_name in the database matches the username provided by the IdP, the IdP sends an update request to Workbench. Workbench receives the request and updates the user in the database, attempting to backfill information not provided by the IdP, such as homedir.

Note

Depending on the security features of the IdP, the update request may not contain the password for the user. In this case, administrators may be required to manually sync the passwords down from the IdP.

If no user_name in the database matches the username provided by the IdP, the IdP sends a creation request to Workbench. Workbench receives the request and derives the POSIX username from the username provided by the IdP. By default, the derived POSIX username is the same as the username provided by the IdP with any domain suffix removed. See the Provisioning section for more information.

If the derived POSIX username matches an existing POSIX username on the system, then Workbench automatically recognizes this as a migration scenario and updates the user’s information in the database with the information provided by the IdP.

Depending on the settings in the IdP, local user passwords may also be modified.

Migrating local users

If you have users who were provisioned locally, you can migrate them to Workbench user provisioning.

To migrate local users to Workbench user provisioning:

  1. Ensure that Workbench user provisioning is enabled. See the User Provisioning - Configuration section for more information.
  2. Configure a supported IdP to provision users to the Workbench application. See the Supported IdPs section for more information.
  3. Provision the user to the Workbench application in the IdP, ensuring that either:
    • The username provided by the IdP results in the same POSIX username as the local user.
    • The username provided by the IdP matches the user_name of the user in the database.
  4. Confirm migration was successful.
  5. Optionally, remove the local user from the system.

Migrating sssd/AD users

If you have users who were provisioned through sssd/AD, you can migrate them to Workbench user provisioning.

To migrate sssd/AD users to Workbench user provisioning:

  1. Ensure that Workbench user provisioning is enabled. See the User Provisioning - Configuration section for more information.
  2. Configure a supported IdP to provision users to the Workbench application. See the Supported IdPs section for more information.
  3. Provision the user to the Workbench application in the IdP, ensuring that either:
    • The username provided by the IdP results in the same POSIX username as the user.
    • The username provided by the IdP matches the user_name of the user in the database.
  4. Confirm migration was successful.
  5. Disable integration with sssd/AD.

Example migration scenarios

Migrating an existing user when the username provided by the IdP matches the user_name in the database

  1. An existing user with the POSIX account name jdoe exists in the Workbench database:

    terminal
    > SELECT * FROM licensed_users;
id | user_id | user_name | posix_name | email | homedir    | ...
---+---------+-----------+------------+-------+------------+----
1  | 1000    | jdoe      | jdoe       |       |            | ...

  2. The user is provisioned to the Workbench application in the IdP with the username jdoe. The IdP sends a request to Workbench to check for an existing user with that username.

  3. Workbench recieves the request and attempts to match the username to the user_name field in the database. A match is found.

  4. The IdP sends a request to Workbench to update the user with username jdoe.

  5. Workbench receives the request and updates the user’s information in the database with the information provided by the IdP, attempting to backfill information if it is empty:

    terminal
    > SELECT * FROM licensed_users;
id | user_id | user_name        | posix_name | email            | homedir    | ...
---+---------+------------------+------------+------------------+------------+----
1  | 1000    | jdoe             | jdoe       | jdoe@example.com | /home/jdoe | ...

Migrating an existing user when the username provided by the IdP does not match the user_name in the database

  1. An existing user with the POSIX account name jdoe exists in the Workbench database:

    terminal
    > SELECT * FROM licensed_users;
id | user_id | user_name | posix_name | email | homedir    | ...
---+---------+-----------+------------+-------+------------+----
1  | 1000    | jdoe      | jdoe       |       |            | ...

  2. The user is provisioned to the Workbench application in the IdP with the username jdoe@example.com. The IdP sends a request to Workbench to check for an existing user with that username.

  3. Workbench recieves the request and attempts to match the username to the user_name field in the database. No match is found.

  4. The IdP sends a request to Workbench to create the user with username jdoe@example.com.

  5. Workbench recieves the request and derives the POSIX username jdoe from the username jdoe@example.com provided by the IdP, and recognizes this is an existing user.

  6. Workbench updates the user’s information in the database with the information provided by the IdP:

    terminal
    > SELECT * FROM licensed_users;
id | user_id | user_name        | posix_name | email            | homedir    | ...
---+---------+------------------+------------+------------------+------------+----
1  | 1000    | jdoe@example.com | jdoe       | jdoe@example.com | /home/jdoe | ...

User migration when coming from 2023.06 or earlier

When a user is migrated to Workbench user provisioning, the user’s user_name in the database is updated to the username provided by the IdP. The username provided by the IdP may be a non-POSIX-compliant name, such as an email.

Because versions 2023.06 and earlier use user_name as the POSIX username for the user, it is recommended to back up your database before proceeding with local user migration. This ensures that you have a backup of the user_name field. In the event that a rollback to version 2023.06 or earlier is necessary, you can restore the user_name field from the backup for any existing local users who were migrated to Workbench user provisioning.

Note

Backing up the database is not necessary when coming from 2023.09 or later, as user_name is no longer used as the POSIX username in these versions.

See the Data Dictionary section of this guide for more information on the user_name field.

Back to top