Deploy Key Connector
This article will walk you through the procedure for enabling and configuring Key Connector in an existing self-hosted environment. Before proceeding, please thoroughly review the About Key Connector article to ensure a full understanding of what Key Connector is, how it works, and the impacts of implementation.
Management of cryptographic keys is incredibly sensitive and is only recommended for enterprises with a team and infrastructure that can securely support deploying and managing a key server.
In order to use Key Connector you must:
If your Organization meets or can meet these requirements, including a team and infrastructure that can support management of a key server, contact us and we'll activate Key Connector.
Setup & Deploy Key Connector
Once you've contacted us regarding Key Connector, we'll reach out to kick off a Key Connector discussion. The steps that follow in this article must be completed in collaboration with Bitwarden Customer Success & Implementation specialists.
Obtain New License File
Once you've contacted us regarding Key Connector, a member of the Customer Success & Implementation team will generate a Key Connector-enabled license file for your Organization. When your Bitwarden collaborator instructs you it is ready, complete the following steps to obtain the new license:
Open your Bitwarden Cloud Web Vault and navigate to your Organization's Settings → Subscription screen.
Select the Download License button.
When prompted, enter the Installation ID that was used to install your self-hosted server and select Submit. If you don't know your Installation ID off-hand, you can retrieve it from
You won't need your license file immediately, but you will be required to upload it to your self-hosted server in a later step.
Initialize Key Connector
To prepare your Bitwarden server for Key Connector:
Save a backup of, at a minimum,
.bwdata/mssql. Once Key Connector is in use, it's recommended that you have access to a pre-Key Connector backup image in case of an issue.
If you're using an external MSSQL database, take a backup of your database in whatever way fits your implementation.
Update your self-hosted Bitwarden installation in order to retrieve the latest changes:
.bwdata/config.ymlfile and enable Key Connector by toggling
Rebuild your self-hosted Bitwarden installation:
Update your self-hosted Bitwarden installation again in order to apply the changes:
Configure Key Connector
To configure Key Connector:
.bwdata/env/key-connector.override.envfile that will have been downloaded with the
This file will be pre-populated with default values that will spin up a functional local Key Connector setup, however the default values are not recommended for production environments.
key-connector.override.env, you will need to specify values for the following:
Automated setup will populate endpoint values based on your installation configuration, however it's recommended that you confirm the following values in
key-connector.override.env are accurate for your setup:
Key Connector must access a database which stores encrypted user keys keys for your Organization members. Create a secure database to store encrypted users keys and replace the default
keyConnectorSettings__database__ values in
key-connector.override.env with the values designated in the Required Values column for the chosen database:
Migration from one database to another is not supported at this time. Regardless of which provider you choose, implement a frequent automated backup schedule for the database.
|Local JSON (default)||Not recommended outside of testing.
|Microsoft SQL Server||
Learn how to format MSSQL Connection Strings
Learn how to format PostgreSQL Connection Strings
Learn how to format MySQL Connection Strings
Learn how to format MongoDB Connection Strings
RSA Key Pair
Key Connector uses an RSA key pair to protect user keys at rest. Create a key pair and replace the default
keyConnectorSettings__certificate__ values in
key-connector.override.env with the values required for your chosen implementation.
The RSA key pair must be at a minimum 2048 bits in length.
Generally, your options include granting Key Connector access to an X509 Certificate that contains the key pair or granting Key Connector access directly to the Key Pair:
Activate Key Connector
Restart your self-hosted Bitwarden installation in order to apply the configuration changes:
Log in to your self-hosted Bitwarden as an Organization Owner and navigate to the Organization Settings → Subscription screen.
Select the Update License button and upload the Key Connector-enabled license retrieved in an earlier step:
Navigate to the Organization Manage screen.
Navigate to the Single Sign-On screen:
In the Member Decryption Options section, select Key Connector.
In the Key Connector URL input, enter the address Key Connector is running at (by default,
https://your.domain/key-connector) and select the Test button to ensure you can reach Key Connector.
Scroll to the bottom of the screen and select Save.