Certificate Options

This article defines the certificate options available to self-hosted Bitwarden servers during setup:

In standard Docker deployments, you'll select one of 4 options during setup.
In standard Helm deployments, you'll
In Unified deployments, you'll

Let's Encrypt

Let's Encrypt is a certificate authority (CA) that issues trusted certificates free of charge for any domain. Certificate renewal checks occur each time your Bitwarden server is restarted, so using Let's Encrypt will require you to enter an email address for certificate expiration reminders.

warning

Let's Encrypt is a third-party certificate authority that requires inbound ports 80 and 443 have access from the internet in order to validate your domain and issue a certificate. If you do not have or want to set up inbound internet access, you may use one of the other certificate options in this document.

Generate a certificate

The bitwarden.sh and bitwarden.ps1 installation scripts offer the option to generate a trusted certificate for your domain using Let's Encrypt and Certbot. To do so, reply y to the prompt Do you want to use Let's Encrypt to generate a free SSL certificate? (y/n).

Update a certificate

note

When making changes to your certificate setup, rebuild your config.yml installation assets (for example, using the ./bitwarden.sh rebuild or .\bitwarden.ps1 -rebuild commands) before starting your Bitwarden server.

To manually update a Let's Encrypt certificate, for example if you change the domain name of your Bitwarden server:

Stop your Bitwarden server.

Bash
# Bash
./bitwarden.sh stop

# PowerShell
.\bitwarden.ps1 -stop

Create a backup.

Bash
# Bash
mv ./bwdata/letsencrypt ./bwdata/letsencrypt_backup
mkdir ./bwdata/letsencrypt
chown -R bitwarden:bitwarden ./bwdata/letsencrypt
chmod -R 740 ./bwdata/letsencrypt

# PowerShell
mv .\bwdata\letsencrypt .\bwdata\letsencrypt_backup
mkdir .\bwdata\letsencrypt

Update your certificate.

tip

For PowerShell, you will need to install a build of OpenSSL for Windows.

Bash
# Bash
docker pull certbot/certbot
docker run -i --rm --name certbot -p 443:443 -p 80:80 -v <Full Path from / >/bwdata/letsencrypt:/etc/letsencrypt/ certbot/certbot certonly --email <user@email.com> --logs-dir /etc/letsencrypt/logs
# Select 1, then
openssl dhparam -out ./bwdata/letsencrypt/live/<your.domain.com>/dhparam.pem 2048

# PowerShell
docker pull certbot/certbot
docker run -i --rm --name certbot -p 443:443 -p 80:80 -v <Full Path from \ >\bwdata\letsencrypt\:/etc/letsencrypt/ certbot/certbot certonly --email <user@email.com> --logs-dir /etc/letsencrypt/logs
# Select 1, then
<path/to/openssl.exe> dhparam -out .\bwdata\letsencrypt\live\<your.domain.com>\dhparam.pem 2048

Rebuild your config.yml installation assets.

Bash
# Bash
./bitwarden.sh rebuild

# PowerShell
.\bitwarden.ps1 -rebuild

Restart your Bitwarden server.

Bash
# Bash
./bitwarden.sh start

# PowerShell
.\bitwarden.ps1 -start

This example with walk you through using cert-manager to generate a certificate with Let's Encrypt:

Install cert-manager on the cluster using the following command:

Bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.yaml

Define a certificate issuer. Bitwarden recommends using the Staging configuration in this example until your DNS records have been pointed to your cluster. Be sure to replace the email: placeholder with a valid value:

Bash
cat <<EOF | kubectl apply -n bitwarden -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: me@example.com
    privateKeySecretRef:
      name: tls-secret
    solvers:
      - http01:
          ingress:
            class: nginx #use "azure/application-gateway" for Application Gateway ingress
EOF

Bash
cat <<EOF | kubectl apply -n bitwarden -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-production
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: me@example.com
    privateKeySecretRef:
      name: tls-secret
    solvers:
      - http01:
          ingress:
            class: nginx #use "azure/application-gateway" for Application Gateway ingress
EOF

If you haven't already, be sure to set the general.ingress.cert.tls.name: and general.ingress.cert.tls.clusterIssuer: values in my-values.yaml. In this example, you would set:
- general.ingress.cert.tls.name: tls-secret
- general.ingress.cert.tls.clusterIssuer: letsencrypt-staging or letsencrypt-production

Existing SSL certificate

To use an existing SSL certificate, you will be required to have the following files:

A server certificate (certificate.crt)
A private key (private.key)
A CA certificate (ca.crt)

You may need to bundle your primary certificate with intermediate CA certificates to prevent SSL trust errors. All certificates should be included in the server certificate file when using a CA certificate. The first certificate in the file should be your server certificate, followed by any intermediate CA certificate(s), followed by the root CA.

To use an existing SSL certificate, place your files in the default location () ./bwdata/ssl/your.domain or () C:\Bitwarden\bwdata\ssl\your_domain.

You may specify a different location for your certificate files by editing the following values in your config.yml file:

Bash
ssl_certificate_path: <path>
ssl_key_path: <path>
ssl_ca_path: <path>

The values defined in config.yml represent locations inside the NGINX container. Directories on the host are mapped to directories within the NGINX container. Under the default configuration, mappings line up as follows:

config.yml Key	config.yml Value	Host File
ssl_certificate_path	/etc/ssl/your.domain/certificate.crt	./bwdata/ssl/your.domain/certificate.crt
ssl_key_path	/etc/ssl/your.domain/private.key	./bwdata/ssl/your.domain/private.key
ssl_ca_path	/etc/ssl/your.domain/ca.crt	./bwdata/ssl/your.domain/ca.crt

You should only ever need to work with files in ./bwdata/ssl/. Working with files directly in the NGINX container is not recommended.

tip

If your server is logging outbound traffic to 1.1.1.1, 1.0.0.1, 9.9.9.9, or 149.112.112.112, your server is making OCSP checks. You can prevent this traffic by configuring an empty value for ssl_ca_path: in your config.yml file. Changing this value, as with changing anything in config.yml, requires a rebuild and restart of your server.

Diffie-Hellman key exchange

If you're using Diffie-Hellman key exchange to generate ephemeral parameters:

Include a dhparam.pem file in the same directory.
Set the ssl_diffie_hellman_path: value in config.yml.

tip

You can create your own dhparam.pem file using OpenSSL with openssl dhparam -out ./dhparam.pem 2048.

Self-signed Certificate

Using a self-signed certificate this is only recommended for testing. Self-signed certificates will not be trusted by Bitwarden client applications by default, so you will be required to manually install this certificate to the trusted store of each device you plan to use Bitwarden with.

Generate a self-signed certificate

Bash
mkdir ./bwdata/ssl/bitwarden.example.com
openssl req -x509 -newkey rsa:4096 -sha256 -nodes -days 365 \
  -keyout ./bwdata/ssl/bitwarden.example.com/private.key \
  -out ./bwdata/ssl/bitwarden.example.com/certificate.crt \
  -reqexts SAN -extensions SAN \
  -config <(cat /usr/lib/ssl/openssl.cnf <(printf '[SAN]\nsubjectAltName=DNS:bitwarden.example.com\nbasicConstraints=CA:true')) \
  -subj "/C=US/ST=New York/L=New York/O=Company Name/OU=Bitwarden/CN=bitwarden.example.com"

Your self-signed certificate (.crt) and private key (private.key) can be placed in the ./bwdata/ssl/self/your.domain directory and configured in the ./bwdata/config.yml:

Bash
 ssl_certificate_path: /etc/ssl/bitwarden.example.com/certificate.crt
 ssl_key_path: /etc/ssl/bitwarden.example.com/private.key

Trust a self-signed certificate

Windows

To trust a self-signed certificate on Windows, run certmgr.msc and import your certificate into the Trusted Root Certification Authorities.

Linux

To trust a self-signed certificate on Linux, add your certificate to the following directories:

Bash
/usr/local/share/ca-certificates/
/usr/share/ca-certificates/

And run the following commands:

Bash
sudo dpkg-reconfigure ca-certificates
sudo update-ca-certificates

For our Linux desktop app, accessing the web vault using Chromium-based browsers, and the Directory Connector desktop app, you also need to complete this Linux cert management procedure.

For the Bitwarden CLI and Directory Connector CLI, your self-signed certificate must be stored in a local file and referenced by a NODE_EXTRA_CA_CERTS= environment variable, for example:

Bash
export NODE_EXTRA_CA_CERTS=~/.config/Bitwarden/certificate.crt

Android

To trust a self-signed certificate on an Android device, refer to Google's Add & remove certificates documentation.

note

If you are not self-hosting and encounter the following certificate error on your android device:

Bash
Exception message: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found.

You will need to upload Bitwarden's certificates to your device. Refer to this community thread for help finding the certificates.

Use no certificate

warning

If you opt to use no certificate, you must front your installation with a proxy that serves Bitwarden over SSL. This is because Bitwarden requires HTTPS; trying to use Bitwarden without the HTTPS protocol will trigger errors.

Suggest changes to this page

How can we improve this page for you?
For technical, billing, and product questions, please contact support



Certificate Options

Let's Encrypt

warning

Generate a certificate

Update a certificate

note

tip

Existing SSL certificate

tip

Diffie-Hellman key exchange

tip

Self-signed Certificate

Generate a self-signed certificate

Trust a self-signed certificate

Windows

Linux

Android

note

Use no certificate

warning

Suggest changes to this page

Cloud Status