Configure hosted Bitwarden/Vaultwarden for customer

Terms to understand

• Bitwarden is a password manager

• Vaultwarden is an open source implementation of the Bitwarden server. It is completely open and free to use for anyone, including for commercial purposes (i.e. selling it as a service, which we're doing)

• A Vault is where credentials are stored. Each user has an individual Vault that only they can access, and each organization has its own Vault that can be organized and shared with members

• A Folder is what it says on the tin. Folders can be used to organize passwords in a user's vault. Organizations have Collections instead of Folders, but they are functionally identical

• An Organization is a conceptual entity in Vaultwarden which usually represents a company or group of people. Most customers will only need one Organization, usually named the same as their company (such as "University PC Care"). Shared passwords are stored in Collections inside the Organization's Vault and individual access can be granted to specific vaults

• A Collection is an Organization's analogue to a Folder in the individual vault. It's simply a collection of various credentials, usually related. For example, an Organization may have a Collection for Financial logins, a separate one for Purchasing, and as many others as they need

• Users can be invited to be a Member of an Organization. Once the invitation is accepted by the user and approved by an admin, the user will have access to all the Collections that were chosen during the invitation process

Preparation

Choose a name

First, choose an appropriate name for the customer that will be used in two spots:

1. Sending emails to new users, email verification, etc

2. The domain name of the Vaultwarden instance, eg. example.vw.mybiz.care

The chosen name must follow these constraints:

1. All lowercase

2. No spaces, hyphens, dashes, or any other forms of punctuation, except when there is a hyphen as part of the customer's business name

3. Obviously related to this specific customer at a glance. For example, everyone at University PC Care knows "UPCC" is the acronym to use for the company, so it would be an appropriate choice. Some names are short enough and/or easy enough to read on their own that the full name can be used. Other examples:

   1. nceast (NC East Alliance)

   2. bgccp (Boys and Girls Club of the Coastal Plains)

   3. autumnfieldnc (Autumnfield of Belhaven - autumnfieldnc.com is their email domain)

In later steps, you will be using this name as follows:

1. Email: example@vw.mybiz.care

2. Domain: example.vw.mybiz.care

Determine whitelisted email domains allowed to register

With the default configuration presented in this document, you will be configuring a short list of domains that are allowed to register using this customer's Vaultwarden instance. By default, universitypccare.com domains will be allowed. Work with the customer to determine a list of domains to allow for sign-up. If the customer's domain is example.com and example.org, then a list of allowed domains would look like universitypccare.com,example.com,example.org.

Explain to the customer the following:

1. The domains they choose will be allowed to register a new account in their Vaultwarden instance

2. Registering a new account does not give a user access to anything. When the new user logs in for the first time, they will be presented with an empty vault and no ability to view the Organization's passwords.

3. New users will need to be explicitly granted permission to view Collections in the Organization. A Collection is an arbitrary group of passwords, like "Finance" or "Purchasing" or "Mission Critical"

4. Discourage whitelisting non-custom domains such as gmail.com, yahoo.com, etc. If the customer does not have their own domain, this would be a good time to pitch one to them

Create email account for Vaultwarden instance

Vaultwarden will need to occasionally send an email to a user, such as for email verification or new account registration. This account needs to be created using the name you chose above.

1. Login to the mybiz.care cPanel account. Credentials are in Bitwarden "Semi Mission Critical". If you do not have access to this folder it means you shouldn't be doing this

2. Click "Email Accounts"

3. Click "+ Create"

   1. Domain: vw.mybiz.care

   2. Username: the name you chose above. For customer "NC East Alliance", for example, type nceast

   3. Generate a password and save it in "Customer Credentials" in Bitwarden with the following label: "Example Company Vaultwarden Email"

Create Linode

The Vaultwarden instance needs a server on which to run, and we use Linode for this.

1. Login to linode.com

2. Click "Create" then "Linode" at the top, then choose the following options:

   1. Linux Distribution: the default Debian option (Debian 11 at the time of writing)

   2. Region: Atlanta

   3. Plan: Shared CPU, Nanode 1GB

   4. Label: "vaultwarden-companydomain.example" (i.e. "vaultwarden-example.com")

   5. Tag: "Hosted VaultWarden"

   6. Root Password: Generate and store in Customer Credentials in our Bitwarden

   7. Add-ons: Backups $2.00/mo: enable

Create A Record for vw.mybiz.care

You must also point the chosen domain name to the Linode in order for it to be accessible.

1. Login to the mybiz.care cPanel

2. Click "Zone Editor"

3. Click "+ A Record" for mybiz.care

4. Type the domain name example.vw.mybiz.care where example is the name you chose in the beginning (eg., nceast.vw.mybiz.care)

5. Enter the IPv4 address of the new Linode instance in the Address field

6. Click "Add An A Record"

Configure Docker and Caddy

1. SSH into the Linode (use Windows PowerShell, Termius, etc) with username root and the root password you set in step 1.6 above

   1. For example, ssh root@the.linode.server.ip

2. Run the following to update the system and install Docker:

   sudo apt-get update
   sudo apt-get upgrade -y
   sudo apt-get install ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   
   # Add the repository to Apt sources:
   echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
   $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
   sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   sudo apt-get update
   sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

3. Set up the Docker files and configuration:

   1. mkdir /docker; cd /docker; touch compose.yaml; vim compose.yaml

   2. Vim will open (text editor). Press i to begin typing

   3. Type :set paste and hit Enter. You will see your command at the bottom left of the screen. After hitting Enter, the bottom left will say -- INSERT (paste) --

   4. Paste the following snippet

      services:
        vaultwarden:
          image: vaultwarden/server:latest
          container_name: vaultwarden
          restart: always
          environment:
            DOMAIN: "https://vaultwarden.example.com"  # Your domain; vaultwarden needs to know it's https to work properly with attachments
            SIGNUPS_ALLOWED: "true"
            SIGNUPS_DOMAINS_WHITELIST: "universitypccare.com,example.net,example.org"
            ORG_CREATION_USERS: ""
            SMTP_HOST: "server.universitypccare.com"
            SMTP_FROM: "example@vw.mybiz.care"
            SMTP_PORT: "465"
            SMTP_SECURITY: "SSL"
            SMTP_USERNAME: "example@vw.mybiz.care"
            SMTP_PASSWORD: "replaceme"
          volumes:
            - /vw-data:/data
      
        caddy:
          image: caddy:2
          container_name: caddy
          restart: always
          ports:
            - 80:80  # Needed for the ACME HTTP-01 challenge.
            - 443:443
            - 443:443/udp # Needed for HTTP/3.
          volumes:
            - ./Caddyfile:/etc/caddy/Caddyfile:ro
            - ./caddy-config:/config
            - ./caddy-data:/data
          environment:
            DOMAIN: "https://vaultwarden.example.com"  # Your domain.
            EMAIL: "admin@example.com"                 # The email address to use for ACME registration.
            LOG_FILE: "/data/access.log"

   5. Edit the following lines:

      1. DOMAIN: change the domain to the A Record you created above, including the https:// part (eg DOMAIN: "https://example.vw.mybiz.care"). There are two spots to change this field (one near the top and one near the bottom)

      2. EMAIL: Under the Caddy configuration, change this email to help@myweb.care

      3. SIGNUPS_DOMAINS_WHITELIST: Replace with the domains the customer wants to allow in their Organization

      4. SMTP_FROM and SMTP_USERNAME: The email address you chose earlier

      5. SMTP_PASSWORD: The password you generated for the email earlier

   6. Press Esc to exist Insert mode

   7. Type :wq to save and close Vim

4. Back on the terminal, type touch Caddyfile, vim Caddyfile and then:

   1. Type :set paste and hit Enter to enter paste mode again

   2. Paste the following block of code

   {$DOMAIN} {
     log {
       level INFO
       output file {$LOG_FILE} {
         roll_size 10MB
         roll_keep 10
       }
     }
   
     # Use the ACME HTTP-01 challenge to get a cert for the configured domain.
     tls {$EMAIL}
   
     # This setting may have compatibility issues with some browsers
     # (e.g., attachment downloading on Firefox). Try disabling this
     # if you encounter issues.
     encode zstd gzip
   
     # Proxy everything Rocket
     reverse_proxy vaultwarden:80 {
          # Send the true remote IP to Rocket, so that vaultwarden can put this in the
          # log, so that fail2ban can ban the correct IP.
          header_up X-Real-IP {remote_host}
     }
   }

   3. Press Esc to exit Insert Mode

   4. Type :wq to save and close Vim

5. Run docker compose up -d

   1. You'll see Docker start pulling images and creating containers and eventually you will get 3 "Created" stamps when done successfully

6. Access the Vaultwarden instance at the domain you specified

7. Create a new user with an email address that matches the domain whitelist you established earlier. The first user will be the System Administrator.

8. Login

Optionally limit creation of new Organizations

By default, any user can create an Organization. The customer may wish that users not be able to arbitrarily create new Organizations within Vaultwarden so as to reduce confusion or simply to control where passwords can go.

The setting is per user email. If you know who the primary administrator will be ahead of time, you can set this before starting Vaultwarden for the first time. Otherwise, you can set this at any time.

1. SSH into the Linode instance

2. cd /docker

3. vim compose.yaml

4. Press i to enable typing

5. Add email addresses to the ORG_CREATION_USERS: line, separated by commas. A valid list might be ORG_CREATION_USERS: tim@example.com,john@example.com

6. Press Esc then type :wq to exit and save

7. Restart the containers to make the changes take effect: docker compose down and docker compose up -d

When disabled, the option to create a new organization will still be present, but attempting to create one will result in an error message being displayed to the user.