Migrate User Keys

Key Connector provides a utility for migration from one database to another, or from one RSA key pair configuration to another. Before executing this migration, it is highly recommended that you take a backup of the database being used by Key Connector to store encrypted user keys.

Key Connector must access a database which stored encrypted user keys for your organization members. Create a new secure database and complete the following steps to migrate user keys to it:

1. Stop the Key Connector container.

2. In your .bwdata/env/key-connector.override.env file, replace the existing keyConnectorSettings__database__ values with the required values for your new database (learn more).

   tip

   Copy the old values to somewhere where you can easily access them, as you'll need them in a future step.

3. Start the Key Connector container to initialize the database. Once it's initialize, stop the Key Connector container again.

4. In key-connector.override.env, add the old keyConnectorSettings__database__ values back in and insert transferTo__ into each of the new values that you added in Step 2.
   
   For example, at this stage a configuration migrating from a local JSON file to using a Microsoft SQL Server would include the following values:

   BashCopy
   keyConnectorSettings__database__provider=json
   keyConnectorSettings__database__jsonFilePath=/etc/bitwarden/database.json
   
   keyConnectorSettings__transferTo__database__provider=sqlserver
   keyConnectorSettings__transferTo__database__sqlServerConnectionString={Connection_String}

5. Restart your self-hosted Bitwarden installation in order to apply the configuration changes:

   BashCopy
   ./bitwarden.sh restart

6. Now that your user keys are migrated, clean up your key-connector.override.env file. Stop the Key Connector container, remove the old values, and remove transferTo__ from each of the new values added in Step 2.

Key Connector uses an RSA key pair to protect user keys at rest. To migrate from your existing RSA key pair configuration:

1. Stop the Key Connector container.

2. In your .bwdata/env/key-connector.override.env file, add the required values for a new RSA configuration (see here) with transferTo__ inserted in each value immediately following keyConnectorSettings__.
   
   For example, the key-connector.override.env for a configuration migrating from a certificate stored on the filesystem to using AWS Key Management Service (KMS) would include the following values:

   BashCopy
   keyConnectorSettings__rsaKey__provider=certificate
   keyConnectorSettings__certificate__provider=filesystem
   keyConnectorSettings__certificate__filesystemPath=/etc/bitwarden/bw-kc.pfx
   keyConnectorSettings__certificate__filesystemPassword=********
   
   keyConnectorSettings__transferTo__rsaKey__provider=awskms
   keyConnectorSettings__transferTo__rsaKey__awsAccessKeyId={AccessKey_Id}
   keyConnectorSettings__transferTo__rsaKey__awsAccessKeySecret={AccessKey_Secret}
   keyConnectorSettings__transferTo__rsaKey__awsRegion={Region_Name}
   keyConnectorSettings__transferTo__rsaKey__awsKeyId={Key_Id}

3. Restart your self-hosted Bitwarden installation in order to apply the configuration changes:

   BashCopy
   ./bitwarden.sh restart