Skip to main content

Key Connector

info

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

Requirements​

MacOS​

MacOS requires updated SSL libraries, otherwise you will receive the error "No usable version of libssl was found".

  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

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
info

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!

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

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.