See the Bitwarden About Key Connector and Deploy Key Connector instructions and perform the following steps: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.
- Set up and deploy Key Connector.
- Configure Key Connector.
- 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.
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.
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.Edit the
.bwdata/config.yml file and enable Key Connector by toggling enable_key_connector to true.Bash
Configure Key Connector
To configure Key Connector, perform the following steps:The extracted content of the
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. |
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.| 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:Specify
Bash
Futurex123 as the password for the PFX file.Copy the following files to the
/opt/bitwarden/bwdata/key-connector directory:Bitwarden.pfxPKI.p12(the TLS client certificate created for the Futurex PKCS #11 library to mutually authenticate to the Vectera Plus)libfxpkcs11.sofxpkcs11.cfgPKCS11Manager
/opt/bitwarden/bwdata/key-connector directory, the system bind-mounts them inside the bitwarden-key-connector container at /etc/bitwarden/key-connector.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 inkey-connector.override.env are accurate for your setup:
Text
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 inkey-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).
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 inkey-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.
Activate Key Connector
Now that Key Connector is fully configured and you have a Key Connector-enabled license, complete the following steps: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 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.