Key Connector

Info

If you’re new to Key Connector, you should read the Help Center documentation first to understand how it works.

Requirements

• Web vault running locally
• .NET Core 5.0 SDK

macOS

macOS requires up to date SSL libraries, otherwise you will receive the error “No usable version of libssl was found”.

Intel

1. Install Homebrew
2. Install the OpenSSL package:

brew install openssl

3. Set the required environment variables to point to the OpenSSL libraries:

echo 'DYLD_LIBRARY_PATH="/usr/local/opt/openssl@1.1/lib"' >> ~/.zshrc

4. If you are running the Key Connector from a terminal, restart your terminal to make sure the updated .zshrc settings are applied

ARM

Given that the Key Connector project is based on NET 5 then we need to use the x86_64 version of OpenSSL, thus installing x86_64 packages using Homebrew (a guide with several approaches can be found here).

1. Install Rosetta

softwareupdate --install-rosetta

2. Set your terminal to Open using Rosetta (create a duplicate of the terminal application -> Go to Get Info -> check Open using Rosetta).
3. Install Homebrew

3.a This should gives us a Homebrew living in /usr/local but if it doesn’t work prepend arch -x86_64 before the Homebrew installation command.

4. Install the OpenSSL package using the x86_64 Homebrew:

arch -x86_64 /usr/local/homebrew/bin/brew install openssl

5. Set the required environment variables to point to the OpenSSL libraries:

echo 'export DYLD_LIBRARY_PATH="/usr/local/opt/openssl@1.1/lib"' >> ~/.zshrc

6. If you are running the Key Connector from a terminal, restart your terminal to make sure the updated .zshrc settings are applied or run

source ~/.zshrc

Setup and configuration

1. Clone the repository:

git clone https://github.com/bitwarden/key-connector.git

Configure keys and user secrets

Caution

These are recommended development settings and are not suitable for production use. More configuration options are available in the README if required.

1. Open a terminal and navigate to the dev folder inside your local Key Connector repository

2. Generate a new RSA keypair (these will be ignored by git provided they are in the dev folder):

openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout bwkc.key -out bwkc.crt -subj "/CN=Bitwarden Key Connector" -days 36500

openssl pkcs12 -export -out ./bwkc.pfx -inkey bwkc.key -in bwkc.crt -passout pass:{Password}

3. Create your own copy of the example user secrets:

cp secrets.json.example secrets.json

4. Edit secrets.json and insert the missing information, including the path to your local repository and a password for your database file.
5. (Optional) By default, Key Connector will use the local self-hosted endpoints - https://localhost:8081 for the web vault and http://localhost:33657 for Identity. No changes are required if you’re following this documentation. However, if you need different endpoints for your setup, you can set them in your user secrets as follows:

"keyConnectorSettings": {
  "webVaultUri": "https://localhost:8081",
  "identityServerUri": "http://localhost:33657"
}

6. Save and apply the user secrets:

pwsh setup_secrets.ps1

If you need help setting user secrets, see the User Secrets Reference.

Configure organization

1. Open your local web vault and configure your enterprise organization to use the following settings:

• Policies: Single Organization and Single Sign-On Authentication

• Single Sign-On:

• Member Decryption Option: Key Connector

• Key Connector URL: http://localhost:5000

Running and Debugging

You’re now ready to start using Key Connector in your dev environment!

Visual Studio

Open the solution file (bitwarden-key-connector.sln) with Visual Studio and click the “Play” button.

CLI

Run the following command from the repository root:

dotnet run --project src/KeyConnector --configuration Development

Note

If running on ARM based Mac you may need to use /usr/local/share/dotnet/x64/dotnet

/usr/local/share/dotnet/x64/dotnet run --project src/KeyConnector --configuration Development

The --configuration flag is required for macOS to use the right SSL libraries.

After starting Key Connector, log in with SSO using an account that is not an Admin or an Owner. New users will be onboarded to Key Connector automatically, and existing users will be prompted to remove their Master Password.