Skip to main content

Bitwarden - Password Manager

Bitwarden is a password manager application. It has a public instance that can be used for free with limited features or with all features for a fee. I choose to self-host an instance with all the features for free.

Access

The Bitwarden instance is reverse-proxied by the Secure Web Application Gateway. It is published on bw.kasad.com.

Since Bitwarden provides its own secure login and two-factor authentication, it is not protected behind Cloudflare Access policies. However, the admin dashboard endpoint (/admin) is protected by an Access policy which is restricted to the Administrator user group.

Deployment

We are actually not running the official Bitwarden server. Instead, we run a fork called Vaultwarden because it is much lighter.

Vaultwarden runs as a single Docker container using the vaultwarden/server:alpine image. We deploy it in a Docker Compose stack for ease of configuration:

version: '3'

services:
  vaultwarden:
    image: vaultwarden/server:alpine
    container_name: bitwarden
    restart: always
    environment:
      WEBSOCKET_ENABLED: "true"  # Enable WebSocket notifications
      TZ: America/Los_Angeles
      DOMAIN: https://bw.kasad.com
      ADMIN_TOKEN: [redacted]
    volumes:
      - /srv/bitwarden/data:/data
    networks:
      - default
      - swag

networks:
  swag:
    external: true
    name: swag_default

SWAG network

Since our Bitwarden instance is reverse-proxied behind the Secure Web Application Gateway, the SWAG container needs network access to the Bitwarden container. This has been done in the Compose stack above. See this explanation for details.

Persistent data storage

Bitwarden needs to store data, as that's the entire purpose of the application. To ensure that all data persists between service restarts, we add a storage volume to the container mounted at /data inside the container:

    volumes:
      - /srv/bitwarden/data:/data

This is actually not necessary, as the vaultwarden/server image will mount a volume on /data automatically. We specify it, though, to avoid transparency and to keep our data in the /srv directory on the host.

Configuration

Most of Bitwarden's configuration is done using its built-in admin dashboard. This is published on /admin. There are still a few settings that must be configured for the container before the initial startup.

Environment variable settings

The three settings that need to be configured using environment variables are (1) enabling WebSockets, (2) setting the base domain, and (3) setting the initial admin dashboard password.

Enabling WebSockets

To provide notifications to users, BitWarden requires usage of WebSockets. Simply set the relevant environment variable in the Compose file:

      WEBSOCKET_ENABLED: true

Base domain

We must set the base domain in order for Bitwarden to properly generate URLs:

      DOMAIN: https://bw.kasad.com

Initial admin password

The admin dashboard on /admin requires a password to access. To set the initial password, specify it in an environment variable:

      ADMIN_TOKEN: [redacted]

Once logged in to the admin dashboard, the password can be changed. This only sets the initial password.

Dashboard settings

Many of the settings within the admin dashboard need to be configured. Significant settings for each section in the dashboard are listed below.

Hover over the name of a property in the admin dashboard to see a more detailed description.

General settings

Allow new signups: false
We don't to allow new users to sign up since our Bitwarden instance is publicly accessible.

Require email verification on signups: true
We want to ensure that all users set a valid email address which they have access to.

Allow invitations: true
This will allow administrators to create new users in the Bitwarden instance. Since self-registration is disabled, this is the only way to add new users without manually editing the database.

Invitation organization name: Kasad Family Bitwarden
Sets the name of the Bitwarden instance in invitations.

Advanced settings

Client IP header: X-Real-IP
This tells Bitwarden which HTTP header contains the client's IP address. Since we have the SWAG reverse proxy in front of Bitwarden, this will be the X-Real-IP header.

Icon blacklist non-global IPs: true
Disables fetching icons from internal/private IP addresses. This prevents malicious users from sending requests to internal IPs.

Bypass admin page security: false I have this set to false just in case, but as long as the admin dashboard is protected by proper Cloudflare Access policies, it should be safe to enable this.

Yubikey settings

Enabled: true
Enable support for two-factor authentication using Yubikeys.

Note: you can still use Yubikeys for 2FA if this is disabled, but you must use it as a WebAuthn device in that case. This option simply provides support for the Yubikey verification API.

Client ID and Secret Key
These two properties deal with your API key for the Yubikey API. For the default verification service run by Yubico, go to upgrade.yubico.com/getapikey to get an API key. If using an internal verification server, use the proper API key for it.

Server: https://api.yubico.com/wsapi/2.0/verify
The API endpoint for the verification server. The value provided here is for the default verification service run by Yubico.

Global Duo settings

Enabled: false
I do not use Duo, so I have no use for this to be enabled.

SMTP email settings

In order for Bitwarden to send email invitations, verification emails, password reset emails, and 2FA emails, a valid SMTP configuration is required. We use the kasad.com email server for sending mail. See Sending Emails from Web Apps for a detailed explanation.

Host: mail.kasad.com
Specify the SMTP server to use.

Port: 465
Secure SMTP: force_tls
Use SMTP with implicit TLS on port 465. An alternative is using SMTP with STARTTLS on by setting the Secure SMTP setting to starttls and the Port to 587. Implicit TLS is better though, so we use that.

From Address: no-reply@bw.kasad.com
From Name: Bitwarden
Set the From address that Bitwarden will use when sending emails. See Sending Emails from Web Apps for details on configuring this.

Username: vaultwarden
Password: [redacted]
Specify the username and password to use to log in to the SMTP server. This user must have a mail-enabled account on the kasad.com mail server.

Accept Invalid Certs: false
Accept Invalid Hostnames: false
When both of these are false, Bitwarden will verify the validity of the mail server's TLS certificates.

Email 2FA settings

Enabled: true
I sometimes need two-factor authentication via email, so I enable this option.

Adding users

To add a new user the Bitwarden instance, go to the Users tab and use the form at the bottom of the page to invite them by email. The address you enter will recieve an email with link to the Bitwarden instannce where they can finish setting up their account.

Backing up

Bitwarden provides an easy way to back up its critical data. Just go to the admin dashboard and use the Backup Database option at the bottom of the page to export the SQLite3 database containing Bitwarden's data.