Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The vault service, based on Vaultwarden, serves as a secrets storage application for the whole organisation.

Individuals still may use their own password manager, but it is strongly encouraged that all users start using Vaultwarden for the TPO-related secrets storage. TPA still uses pass for now.

Tutorial

Welcome email

Hello,

You're receiving this email because you manage some credentials for Tor.

You need to read these instructions carefully -- there are two important actions detailed here that are required for your Vaultwarden account to work fully.

Getting Started

You'll soon receive an email from Vaultwarden <noreply@torproject.org> with the subject, "Join The Tor Project". Please click the link in the email to create your account.

After deciding on a password, you will be sent a verification code to your email address, please obtain that code and provide it to login for the first time.

Critical Steps (must be completed)

  1. Set up Two-Factor Authentication (2FA) immediately after creating your account. Full functionality will not be available without 2FA. Go to Settings->Security->Two-step login to set this up.

  2. Send me your account’s Fingerprint Phrase in a secure way. You can find this under Settings->My Account, there you will find "Your account's fingerprint phrase". Without this step, your account will remain limited.

Once I have received that fingerprint phrase, I will "confirm" your account. Until I have done that, you will not be able to view or add any passwords. Once confirmed, you'll receive another email titled "Invitation to The Tor Project confirmed."

How to use the vault

Vaultwarden is our self-hosted server version of Bitwarden. You can use any Bitwarden client to interact with the vault. Available clients are here: https://bitwarden.com/download/

You can interact with Vaultwarden using https://vault.torproject.org, but the web interface that you have used to setup your account is not the most useful way to use this tool!

The web extension (which you can find at https://bitwarden.com/download) is recommended as the primary method because it is most extensively audited for security and offers ease of use. Other client tools, including desktop applications, are also available. Choose the client that best suits your needs and workflow.

To use one of these clients, simply configure it to use the self-hosted server, and put https://vault.torproject.org as the location.

Adding Credentials

After confirmation, use the web interface:

  • Navigate to the collection under Collections in the left sidebar.

  • Click “New” (top right) and select "Item" to add credentials. Credentials added here are accessible by everyone who is part of that collection.

What Credentials to Include:

  • Any third-party service credentials intended for shared access.
  • Accounts managed on behalf of The Tor Project.

Do NOT include your OpenPGP private key passphrase.

If unsure, please contact me.

Organizing Credentials

  • Folders are for organizing credentials hierarchically.
  • Collections manage different access levels within or across teams.

Create new Folders or Collections using the "New" button.

Additional Documentation

Sharing a secret with other users

The primary way to share secrets with other users is through the Collections feature. A "Collection" is like a "Folder" in the sense that it organizes items in a nested structure, but contrarily to a Folder, it allows you to grant access for specific sets to specific groups or users.

Say you want to share a password with your team. The first step will be to create a new Collection for your team, if it doesn't already exist. For this, you:

  1. click the New (top right) button and select Collection
  2. pick a correct name for the collection (e.g. "Foo admins" for the admins of the service "Foo" or "Bar team" for everyone in the team "Bar")
  3. nest the collection under the right collection, typically, "Foo admins" would be nested under the "Bar team", for example, this will grant access to everyone under the parent collection!
  4. For more advanced access control, click the Access tab where you can grant users or groups the permission to "View items" by selecting them in the Select groups and members drop down
  5. Click save

The two crucial steps are steps 3 and 4, which determine who will have access to the secret. Typically, passwords should be shared with teams and simply picking the right Collection when creating a password.

It's only if you want to give access to a single user or a new, perhaps ad-hoc, team that you will need to create a new Collection.

How-to

Add a user

Note: this step cannot be done by a Vault "admin" (through the /admin) interface, it needs to be done by an organization owner (currently micah).

  1. sent the above "Welcome email"
  2. invite the user from the main vault interface (not the /admin interface), make them part of "The Tor Project" organization
  3. add the user to the right groups
  4. add a Personal - <username> collection with the user given "Edit items, hidden passwords" access, and the "Manage collection" access should be given to the "Executive Leadership" group

Recover a user

The process for recovering a user may be needed if a user forgets their 'master' password, or has been offboarded from the organization and any access that they have needs to be cleaned up. Turning on the Account recovery administration policy will allow owners and admins to use password reset to reset the master password of enrolled users.

In order to recover a user, the organization policy "Account recovery administration" has been turned on. This policy requires that the "Single organization policy" must be enabled. We have also enabled the "automatic enrollment option" which will automatically enroll all new members, regardless of role, in password reset when their invitation to the organization is accepted and prevent them from withdrawing.

Note: Users already in the organization will not be retroactively enrolled in password reset, and will be required to self-enroll. Most users have not been enrolled in this configuration, but as of November 1st, they have been contacted to self-enroll. Enrollment in recovery can be determined by the key icon under the "Policies" column in the Members section of the Admin Console

Converting passwords from pass

If you want to move passwords from the old "pass" password manager, you can try to use anarcat's pass2rbw script, which requires the rbw command line tool.

We do not currently recommend TPA migrate from pass to Bitwarden, but this might be useful for others.

Pager playbook

Check running version

It's possible to query version of Vaultwarven currently running inside the container using the command podman exec vaultwarden /vaultwarden --version.

Disaster recovery

Reference

Installation

This service is installed using the upstream-provided container which runs under Podman.

To set it up, deploy the profile::vaultwarden Puppet profile. This will:

  • install Podman
  • deploy an unprivileged user/group pair
  • manage this user's home directory under /srv/vault.torproject.org
  • install systemd unit to instantiate and manage the container
  • install the container configuration in /srv/vault.torproject.org/container-env
  • create a directory for the container's persistent storage in /srv/vault.torproject.org/data
  • deploy a cron job to create a database backup

The installation requirements are recorded in the GitLab ticket tpo/tpa/team#41541.

Manual

This procedure documents a manual installation performed in a lab, for testing purposes. It was also done manually because the environment is different than production (Apache vs Nginx, Docker vs Podman).

  1. create system user

    addgroup --system vaultwarden
adduser --system vaultwarden

  2. create a Docker compose file, note how the user is numeric below, it needs to match the UID and GID created above:

version: '3'
services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: always
    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "false"
      ROCKET_ADDRESS: "127.0.0.1"
      ROCKET_PORT: 8086
      IP_HEADER: "X-Forwarded-For"
      SMTP_PORT: 25
      SMTP_HOST: "localhost"
      SMTP_FROM: "vault@example.com"
      HELO_NAME: "vault.example.com"
      SMTP_SECURITY: "off"
    env_file: "admin-token.env"
    volumes:
      - data:/data:Z
    restart: unless-stopped
    network_mode: host
    user: 108:127
volumes:
  data:

  1. create the secrets file:

    # generate a strong secret and store it in your password manager
tr -dc '[:alnum:]' < /dev/urandom | head -c  40
docker run --rm -it  vaultwarden/server /vaultwarden hash

    copy-paste the ADMIN_TOKEN line in the /etc/docker/admin-token.env file.

  2. start the container, which will fail on a permission issue:

    docker-compose up

  3. fix perms:

    chown vaultwarden:vaultwarden /var/lib/docker/volumes/vaultwarden_data/_data

  4. start the container properly

    docker-compose up

  5. setup DNS, webserver and TLS, see their proxy examples

  6. setup backups, upgrades, fail2ban, etc

Assuming you setup the service on the domain vault.example.com, head towards https://vault.example.com/admin to access the admin interface.

Upgrades

Because the cintainer is started with label io.containers.autoupdate=registry and the systemd unit is configured to create new containers on startup (--new switch on the podman generate systemd command) the container will be auto-upgraded daily from the upstream container registry via the podman-auto-update service/timer unit pair (enabled by default on bookworm).

SLA

Design and architecture

Services

The service is set up using a single all-in-one container, pulled from quay.io/vaultwarden/server:latest which listens for HTTP/1.1 connections on port 8080. The container is started/stopped using the container-vaultwarden.service systemd unit.

An nginx instance is installed in front of port 8080 to proxy connections from the standard web ports 80 and 443 and handle HTTPS termination.

Storage

All the Vaultwarden data, including SQlite3 database is stored below /srv/vault.torproject.org/data.

Interfaces

Authentication

Vaultwarden has its own user database.

The instance is administered using a secret ADMIN_TOKEN which allows service admins to login at https://vault.torproject.org/admin

Implementation

Issues

There is no issue tracker specifically for this project, File or search for issues in the team issue tracker with the label ~Foo.

Maintainer

Users

Upstream

The server is setup with vaultwarden, an "Unofficial Bitwarden compatible server written in Rust, formerly known as bitwarden_rs". It's active as of December 2025, with regular commits and releases.

According to the vaultwarden README, "one of the active maintainers for Vaultwarden is employed by Bitwarden and is allowed to contribute to the project on their own time".

Monitoring and metrics

Tests

Logs

The logs for Vaultwarden can be read using journalctl -u container-vaultwarden.service.

Backups

Other documentation

Vaultwarden has its own wiki but essentially links to the official Bitwarden help pages for most features.

Discussion

Overview

Security and risk assessment

Technical debt and next steps

Proposed Solution

Other alternatives