Skip to content

Vaultwarden guide

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.

Note

TPA still uses pass for now, see the TPA password-manager service and also the service documentation.

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.

When you pick your password, do make sure to pick a strong password. We know you always pick a strong password, but in this case, we really mean it. You can read Reliably generating good passwords from anarcat to find a good password.

Tip

If you are missing a good "diceware" style password generator, know that once you sign up, you can use Vaultwarden itself to generate such a good password.

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 Step: 2FA

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.

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.