> ## 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 for configuring Bitwarden components including Key Connector and database setup.

Refer to this section and the Bitwarden

[**About Key Connector**](https://bitwarden.com/help/about-key-connector/) and

[**Deploy Key Connector**](https://bitwarden.com/help/deploy-key-connector/) instructions for installation and configuration guidance.

Perform the following tasks to Configure Bitwarden:

1. Set up and Deploy Key Connector.
2. Confirm endpoint values.
3. Create a database.
4. Create an RSA key pair.
5. Activate Key Connector.

## Before you start

To get started using **Key Connector** for customer-managed encryption, review the following requirements.

To use Key Connector, you must have the following components:

* An Enterprise organization
* A self-hosted Bitwarden server
* An active SSO implementation
* Enabled **Single organization** and **Require single sign-on authentication** policies

If your organization meets these requirements, including a team and infrastructure that supports key server management, contact Bitwarden so they can activate Key Connector.

## Set up and deploy Key Connector

After you contact Bitwarden regarding Key Connector, they schedule a Key Connector discussion.

Perform the following tasks to set up and deploy Key Connector:

1. Obtain a new license file.
2. Initialize Key Connector
3. Configure Key Connector.

### Obtain a license file

After Bitwarden enables Key Connector for your organization, complete the following steps to obtain the new license:

<Steps>
  <Step>
    Open the Bitwarden cloud web app and go to your organization **Billing** > **Subscription** screen in the Admin Console.
  </Step>

  <Step>
    Scroll down and select **\[ Download License ]**.
  </Step>

  <Step>
    When prompted, enter the **installation ID** used to install your self-hosted server and select **\[ Submit ]**. If you don't know your installation ID, retrieve it from `./bwdata/env/global.override.env`.
  </Step>
</Steps>

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 to initialize Key Connector:

<Steps>
  <Step>
    Save a backup of `.bwdata/mssql`. After you start using Key Connector, we recommend that you have access to a pre-Key Connector backup image in case you need it.

    <Note>
      If you use an external MSSQL database, back up your database by following your usual procedure.
    </Note>
  </Step>

  <Step>
    Update your self-hosted Bitwarden installation to retrieve the latest changes:

    ```text expandable lines wrap title="Text" theme={null}
    ./bitwarden.sh update
    ```
  </Step>

  <Step>
    Edit the `.bwdata/config.yml` file and enable Key Connector by setting **enable\_key\_connector** to **true**.

    ```text expandable lines wrap title="Text" theme={null}
    nano bwdata/config.yml
    ```
  </Step>

  <Step>
    Rebuild your self-hosted Bitwarden installation:

    ```text expandable lines wrap title="Text" theme={null}
    ./bitwarden.sh rebuild
    ```
  </Step>

  <Step>
    Update your self-hosted Bitwarden installation again to apply the changes:

    ```text expandable lines wrap title="Text" theme={null}
    ./bitwarden.sh update
    ```
  </Step>
</Steps>

### Configure Key Connector

To configure Key Connector, perform the following steps:

<Steps>
  <Step>
    Copy the following files to your Bitwarden server:

    * The Endpoint zip file that CryptoHub generated for the Bitwarden service
    * The PEM Certificate exported from **PKI Management** > **Certificate Management**
  </Step>

  <Step>
    Extract the contents of the Endpoint zip file containing the following files:

    * `PKCS11Manager`: Program to test the connection to the CryptoHub and perform basic functions through the **FXPKCS11** module, such as logging in and generating random data.
    * `ca-chain.pem`: CA certificate bundle.
    * `client-cert.pem`: Client TLS certificate.
    * `client.p12`: Full Client PKI in encrypted PKCS #12 format (contains the CA chain, client certificate, and client private key).
    * `configTest`: Program to test configuration and connection to the CryptoHub.
    * `fxpkcs11.cfg`: Configuration file for the **FXPKCS11** module, enabling you to customize settings and specify connection details to the CryptoHub.
    * `libfxpkcs11.so`: **FXPKCS11** module.
  </Step>

  <Step>
    Convert the PEM certificate to `PFX` format by using OpenSSL:

    ```text expandable lines wrap title="Text" theme={null}
    openssl pkcs12 -export -nokeys -in Bitwarden-Cert.pem -out Bitwarden-Cert.pfx
    ```

    Specify `Futurex123` as the password for the `PFX` file.
  </Step>

  <Step>
    Copy the following files to the `/opt/bitwarden/bwdata/key-connector` directory:

    * `Bitwarden.pfx`
    * `client.p12`
    * `libfxpkcs11.so`
    * `fxpkcs11.cfg`
    * `PKCS11Manager`

    Putting these files in the `/opt/bitwarden/bwdata/key-connector` directory bind-mounts them inside the `bitwarden-key-connector` container at `/etc/bitwarden/key-connector`.
  </Step>

  <Step>
    Edit the `.bwdata/env/key-connector.override.env` file that you downloaded with the `./bitwarden.sh update`. See the following **Additional explanation** section for guidance.
  </Step>
</Steps>

#### Additional explanation

This section provides additional explanation for editing `.bwdata/env/key-connector.override.env`.

Example `key-connector.override.env` file:

```text expandable lines wrap title="Text" 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`). **Ensure the TLS files referenced in the config (`client.p12`, `.cer` files) are also in the same directory as the config file.**

To determine the `keyConnectorSettings__rsaKey__pkcs11SlotTokenSerialNumber` value, you must perform the following steps:

1. Run the `PKCS11Manager` utility against your CryptoHub.
2. Select option 1 (**Print Library/Token Info**).
3. Set `keyConnectorSettings__rsaKey__pkcs11LoginPin` to the value contained within the `<CRYPTO-OPR-PASS>` tags in the Futurex PKCS #11 configuration file (`fxpkcs11.cfg`).

The value you set in the `keyConnectorSettings__rsaKey__pkcs11PrivateKeyLabel` definition must match the name assigned to the Bitwarden key in CryptoHub.

The `PKCS11Manager` and `fxpkcs11.cfg` files are included in the Endpoint zip generated for the Bitwarden service in CryptoHub.

## Confirm endpoint values

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
```

## Create 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**](https://bitwarden.com/help/deploy-key-connector/#:~:text=http%3A//identity%3A5000-,Database,-Key%20Connector%20must) column for the chosen database.

<Note>
  The preceding example `key-connector.override.env` defines Local JSON, but we do not recommend this option except for testing. For production environments, Bitwarden recommends using one of the other supported database options (such as Microsoft SQL Server, PostgreSQL, MySQL/MariaDB, or MongoDB).
</Note>

## Create an 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 CryptoHub.

<Note>
  The RSA key pair must be at a minimum 2048 bits in length.
</Note>

Key Connector directly accesses the CryptoHub-stored private key through the Futurex PKCS #11 module and the X.509 Certificate in the file system.

## Activate Key Connector

Now that you configured Key Connector and have a Key Connector-enabled license complete the following steps:

<Steps>
  <Step>
    Restart your self-hosted Bitwarden installation to apply the configuration changes:

    ```text expandable lines wrap title="Text" theme={null}
    ./bitwarden.sh restart
    ```
  </Step>

  <Step>
    Log in to your self-hosted Bitwarden as an organization owner and go to the Admin Console**Billing** > **Subscription** screen.
  </Step>

  <Step>
    Select **\[ Update license ]** and upload the Key Connector-enabled license retrieved in an earlier step.
  </Step>

  <Step>
    If you haven't already, go to the **Settings** > **Policies** screen and enable the **Single organization** and **Require single sign-on authentication** policies, which are required to use Key Connector.
  </Step>

  <Step>
    Go to the **Settings** > **Single sign-on** screen.

    <Note>
      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 the login with SSO before proceeding.
    </Note>
  </Step>

  <Step>
    In the **Member decryption options** section, select **Key Connector**.
  </Step>

  <Step>
    In the **Key Connector URL** input, enter the address where you are running Key Connector (by default, `https://your.domain/key-connector`) and select **\[ Test ]** to ensure you can reach Key Connector.
  </Step>

  <Step>
    Scroll to the bottom of the screen and select **\[ Save ]**.
  </Step>
</Steps>