Migration Script

The Bitwarden public API allows administrators to automate administrative tasks using scripts. The script documented in this article is written to help Bitwarden customers migrate their existing setup from a previous Bitwarden Password Manager environment into a new organization, providing a way to migrate organization vault data, groups, and associated groups' and members' permissions to a new installation.

The script is written in Python and can be run on any operating system with Python v3 installed. Download the script and an example configuration file here.

Other than the default libraries shipped with most Python distributions included by default on Linux and macOS, and available for Windows), this script requires an additional module called requests be installed before the script can run successfully.

A common tool to install Python modules is called pip. To install the module using pip:

BashCopy
pip3 install requests

The above download contains two files:

• bwAdminTools.py: This is the script you will need to execute migration. It requires a fully-configured configuration file.

• config-example.cfg: This is the configuration file required for migration, which you will need to create and setup before running the script.

Unpack the .zip and save these files to the same directory. Once you do, add the following files to the same directory:

• Bitwarden Password Manager CLI native executable.

Before you can continue, you must create the destination organization that you'll be migrating to. Learn how to create an organization.

If your organization license originated from the US cloud server, and self-hosted instance was enabled using US cloud credentials, the follow steps will be required in order to migrate the self hosted instance and organization credentials to the EU:

1. Instruct all organization members to export their individual vaults.
   

   tip

   Individually download any file attachments for vault items and note which items they belong to.

2. Request a new installation Id and Key. Be sure to set the Data Region to the destination you wish to migrate the Bitwarden instance to.

3. Access the ./bwdata/env/global.override.env file on your self hosted instance. Update the environment variables following the example here.

4. Login and access the cloud organization and download a new subscription license file using the new EU or US Installation Id.

5. Create a new organization on the self-hosted instance. Manually apply the new subscription license file to the newly created organization. The subscription license can not be applied an existing organization on the self-hosted instance.

6. Set up your new organization, configuring things like enterprise policies, login with SSO, constructing group-collection relationships, and inviting users with Directory Connector or SCIM. For help, refer to the Proof-of-Concept Checklist.

7. Instruct organization members to import their individual vaults.
   

Before running any bwAdminTools.py script functions, you will need to create a configuration file. Copy the contents of config-example.cfg into a new config.cfg file in the same directory, and fill in the following variables. Note that, as this is a migration script, variables are broken into Source and Destination groupings in this documentation:

Once you've setup these variables, you're ready to start migration using the bwAdminTools.py script functions.

From the directory where you've stored your bwAdminTools.py file, config.cfg file, and Password Manager CLI executable, you can run the following commands:

• To print script helper text:

  BashCopy
  python3 bwAdminTools.py -h

• To compare source and destination organizations:

  BashCopy
  python3 bwAdminTools.py -c diffbw

• To migrate organization vault data, groups, and groups' permissions from a source organization to a destination organization:

  BashCopy
  python3 bwAdminTools.py -c migratebw

  Users must be in at least an invited state in the destination organization for migratebw to be successful.

• To migrate members' permissions (outside of groups) from a source organization to a destination organization:

  BashCopy
  python3 bwAdminTools.py -c migratebwusers

  Users must be in at least an invited state in the destination organization for migratebwusers to be successful.

• To delete all collections from the source organization:

  BashCopy
  python3 bwAdminTools.py -c purgecol

• To delete all collections from the destination organization:

  BashCopy
  python3 bwAdminTools.py -c purgecoldest

• To delete all groups from the source organization:

  BashCopy
  python3 bwAdminTools.py -c purgegroup

• To delete all groups from the destination organization:

  BashCopy
  python3 bwAdminTools.py -c purgegroupdest