> ## Documentation Index > Fetch the complete documentation index at: https://docs.futurex.com/llms.txt > Use this file to discover all available pages before exploring further. # Configure Bitwarden > Instructions to configure Bitwarden Key Connector to integrate with the HSM. See the Bitwarden [**About Key Connector**](https://bitwarden.com/help/about-key-connector/) and [**Deploy Key Connector**](https://bitwarden.com/help/deploy-key-connector/) instructions and perform the following steps: 1. Set up and deploy Key Connector. 2. Configure Key Connector. 3. Activate Key Connector. ## Before you start To get started using **Key Connector** for customer-managed encryption, please review the following requirements. To use Key Connector, you must have: * An Enterprise organization. * A self-hosted Bitwarden server. * An active SSO implementation. * Activate the single organization and require single sign-on policies. If your organization meets or can meet these requirements, including a team and infrastructure that can support the management of a key server, contact Bitwarden so they can activate Key Connector. ## Set up and deploy Key Connector After you contact Bitwarden about Key Connector, they reach out to kick off a Key Connector discussion. Perform the following tasks to set up and deploy Key Connector: ### Obtain a new license file After Bitwarden enables Key Connector for your organization, complete the following steps to obtain the new license: Open the Bitwarden cloud web app and go to your organization **Billing** > **Subscription** screen in the Admin Console. Scroll down and select **\[ Download License ]**. When prompted, enter the **installation ID** 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 `./bwdata/env/global.override.env`. You won't need your license file immediately, but you must upload it to your self-hosted server later. ### Initialize Key Connector To prepare your Bitwarden server for Key Connector, perform the following steps: Save a backup of `.bwdata/mssql`. After you start using Key Connector, we recommend that you ensure you have access to a pre-Key Connector backup image in case of an issue. If you use an external MSSQL database, back up your database. Update your self-hosted Bitwarden installation to retrieve the latest changes: ```bash expandable lines wrap title="Bash" theme={null} ./bitwarden.sh update ``` Edit the `.bwdata/config.yml` file and enable Key Connector by toggling `enable_key_connector` to `true`. ```bash expandable lines wrap title="Bash" theme={null} nano bwdata/config.yml ``` Rebuild your self-hosted Bitwarden installation: ```bash expandable lines wrap title="Bash" theme={null} ./bitwarden.sh rebuild ``` Update your self-hosted Bitwarden installation again to apply the changes: ```bash expandable lines wrap title="Bash" theme={null} ./bitwarden.sh update ``` ## Configure Key Connector To configure Key Connector, perform the following steps: Download the tarball of the Linux PKCS #11 binaries from the Futurex Portal. Copy the Linux PKCS #11 tar file to your Bitwarden server: Extract the `.tar` file. The extracted content of the `.tar` file is a single `fxpkcs11` directory. This directory contains the following files and directories (only the files and folders relevant to the installation process are included in this list):
File name or directory Description
fxpkcs11.cfg PKCS #11 configuration file to use for HSM Integrations.
x86/ This folder contains the module files for 32-bit architecture.
x64/ This folder contains the module files for 64-bit architecture.
The `x86` and `x64` directories contain multiple directories named for the specific OpenSSL versions. These OpenSSL directories contain the PKCS #11 module files built with the respective OpenSSL versions. You must use the OpenSSL 3.x binaries because that is the version installed in the Bitwarden Key Connector container.
File name Description
configTest Program to test the configuration and connection to the HSM.
libfxpkcs11.so PKCS #11 Library file.
PKCS11Manager Program to test the connection and manage the HSM through the PKCS #11 library.
Convert the PEM certificate created with FXCLI in the previous section to PFX format using OpenSSL: ```bash expandable lines wrap title="Bash" theme={null} openssl pkcs12 -export -nokeys -in Bitwarden-Cert.pem -out Bitwarden-Cert.pfx ``` Specify `Futurex123` as the password for the PFX file. Copy the following files to the `/opt/bitwarden/bwdata/key-connector` directory: As previously noted above, you must use the OpenSSL 3.x binaries because that is the version installed in the Bitwarden Key Connector container. * `Bitwarden.pfx` * `PKI.p12` (the TLS client certificate created for the Futurex PKCS #11 library to mutually authenticate to the Vectera Plus) * `libfxpkcs11.so` * `fxpkcs11.cfg` * `PKCS11Manager` By putting these files in the `/opt/bitwarden/bwdata/key-connector` directory, the system bind-mounts them inside the `bitwarden-key-connector` container at `/etc/bitwarden/key-connector`. Edit the `.bwdata/env/key-connector.override.env` file that came with the `./bitwarden.sh update` you downloaded. Example `key-connector.override.env`: ```none title="Env" expandable lines wrap theme={null} keyConnectorSettings__webVaultUri=https://ec2-34-193-223-21.compute-1.amazonaws.com keyConnectorSettings__identityServerUri=http://identity:5000 keyConnectorSettings__database__provider=json keyConnectorSettings__database__jsonFilePath=/etc/bitwarden/key-connector/data.json keyConnectorSettings__certificate__provider=filesystem keyConnectorSettings__certificate__filesystemPath=/etc/bitwarden/key-connector/Bitwarden.pfx keyConnectorSettings__certificate__filesystemPassword=Futurex123 keyConnectorSettings__rsaKey__provider=pkcs11 keyConnectorSettings__rsaKey__pkcs11LibraryPath=/etc/bitwarden/key-connector/libfxpkcs11.so FXPKCS11_CFG=/etc/bitwarden/key-connector/fxpkcs11.cfg keyConnectorSettings__rsaKey__pkcs11SlotTokenSerialNumber=3174612105 keyConnectorSettings__rsaKey__pkcs11LoginUserType=user keyConnectorSettings__rsaKey__pkcs11LoginPin=EDY0DD29B2T82*fC0&@511h1m4D8 keyConnectorSettings__rsaKey__pkcs11PrivateKeyLabel=Bitwarden ``` The `FXPKCS11_CFG=/etc/bitwarden/key-connector/fxpkcs11.cfg` enables the Futurex PKCS #11 module to find the configuration file at the non-default location (`/etc`). To determine the **keyConnectorSettings\_\_rsaKey\_\_pkcs11SlotTokenSerialNumber** value you must specify, run the **PKCS11Manager** utility against your Vectera Plus and select option 1 (**Print Library/Token Info**). Set **keyConnectorSettings\_\_rsaKey\_\_pkcs11LoginPin** to the password value you configured for the Bitwarden identity. ## What to expect The following sections cover some key concepts you should understand when setting up Bitwarden. ### Endpoints The automated setup populates endpoint values based on your installation configuration. However, we recommend that you confirm the following values in `key-connector.override.env` are accurate for your setup: ```text expandable lines wrap title="Text" theme={null} keyConnectorSettings__webVaultUri=https://your.bitwarden.domain.com keyConnectorSettings__identityServerUri=http://identity:5000 ``` ### Database Key Connector must access a database that stores encrypted user keys for your organization members. Create a secure database to store encrypted user 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 (see [**bitwarden.com/help/deploy-key-connector/#:\~:text=http%3A//identity%3A5000-,Database,-Key%20Connector%20must**](https://bitwarden.com/help/deploy-key-connector/#:~:text=http%3A//identity%3A5000-,Database,-Key%20Connector%20must)). The preceding `key-connector.override.env` instructions define Local JSON, but we do not recommend this option outside testing environments. For production environments, Bitwarden recommends using one of the other supported database options (such as Microsoft SQL Server, PostgreSQL, MySQL/MariaDB, or MongoDB). ### RSA key pair Key Connector uses an RSA key pair to protect user keys at rest. You must replace the default **keyConnectorSettings\_\_rsaKey\_\_** and **keyConnectorSettings\_\_certificate\_\_** values in `key-connector.override.env` with the values required to integrate with the Vectera Plus. The RSA key pair must be at a minimum of 2048 bits in length. Key Connector accesses the HSM-stored private key through the Futurex PKCS #11 module and the X.509 Certificate directly in the file system. ## Activate Key Connector Now that Key Connector is fully configured and you have a Key Connector-enabled license, complete the following steps: Restart your self-hosted Bitwarden installation to apply the configuration changes: ```bash expandable lines wrap title="Bash" theme={null} ./bitwarden.sh restart ``` Log in to your self-hosted Bitwarden as an organization owner and go to the Admin Console **Billing** > **Subscription** screen. Select **\[ Update license ]** and upload the Key Connector-enabled license retrieved in a preceding step. If you haven't already done so, go to the **Settings** > **Policies** screen and enable both the **Single organization** and **Require single sign-on authentication** policies. Both are required to use Key Connector. Go to the **Settings** > **Single sign-on** screen. The next few steps assume that you already have an active login with SSO implementation using SAML 2.0 or OIDC. If you don't, implement and test a login with SSO before proceeding. In the **Member decryption options** section, select **Key Connector**. In the **Key Connector URL** input, enter the IP address Key Connector is running at (by default, `https://your.domain/key-connector`) and select **\[ Test ]** to ensure you can reach Key Connector. Scroll to the bottom of the screen and select **\[ Save ]**.