Migrate Existing Users to Single Sign-On

This information applies to SwaggerHub On-Premise. For SwaggerHub SaaS, click here.

Note: This information applies to SwaggerHub On-Premise versions prior to 1.20.1. Starting from v. 1.20.1, users are migrated to single sign-on automatically, and the procedure described below is no longer needed.

In SwaggerHub On-Premise versions prior to 1.20.1, after you enable single sign-on (SSO), you need to migrate the existing users so that they can log in via SSO. This is done by running a special maintenance script, as explained below.


The script migrates all users with their existing email addresses unchanged. The users’ email addresses in SwaggerHub must match their email addresses in your SSO provider.

Users with mismatched email addresses will not be able to log in after migration. Such users can be fixed later if you contact SmartBear Support.

Migrate users

  1. Important: Create a full VM snapshot.

  2. Download the user migration script:


  3. In the Admin Center, review the user list on the License page. Make sure the email addresses of the users, including the administrator user (you), are the same as in your SSO provider (ignoring the letter case). If needed, ask the users to update their email addresses in SwaggerHub.

    Admin Center: List of users
  4. Upload the script on the System page, under Maintenance.

    Running the user migration script
  5. Click Apply to run the script.

  6. Wait until the script has finished running. You should see the following output:

    Running maintenance file migrate_all_users_to_sso.js
    Backed up registry database
    Backed up user database
    Migrated users.
    Finished processing maintenance script


If some users cannot log in to SwaggerHub after the migration, please contact SmartBear Support. Most likely, the email addresses of these SwaggerHub users need to be updated to match their email addresses in the SSO provider. Our Support will assist you with this matter.

See Also

Publication date: