Key Connector
If you're new to Key Connector, you should read the Help Center documentation first to understand how it works.
Requirements
- A local development server running in the self-hosted configuration
- An enterprise organization with SSO configured
- Web vault running locally
- .NET Core 5.0 SDK
MacOS
MacOS requires updated SSL libraries, otherwise you will receive the error "No usable version of libssl was found".
- Install Homebrew
- Install the OpenSSL package:
brew install openssl
- Set the required environment variables to point to the OpenSSL libraries:
echo 'DYLD_LIBRARY_PATH="/usr/local/opt/openssl@1.1/lib"' >> ~/.zshrc
- 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
- Clone the repository:
git clone https://github.com/bitwarden/key-connector.git
Configure keys and user secrets
These are recommended development settings and are not suitable for production use. More configuration options are available in the README if required.
Open a terminal and navigate to the
dev
folder inside your local Key Connector repositoryGenerate 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}Create your own copy of the example user secrets:
cp secrets.json.example secrets.json
Edit
secrets.json
and insert the missing information, including the path to your local repository and a password for your database file.(Optional) By default, Key Connector will use the local self-hosted endpoints -
https://localhost:8081
for the web vault andhttp://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"
}Save and apply the user secrets:
pwsh setup_secrets.ps1
If you need help setting user secrets, see the User Secrets Reference.
Configure organization
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
- CLI
Open the solution file (bitwarden-key-connector.sln
) with Visual Studio and click the "Play"
button.
Run the following command from the repository root:
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.