Self Hosted Password Manager: vaultwarden

Updated May 1st, 2020

You familiar with Bitwarden? It’s another one of those password manager services that comes as a browser extension or standalone program, and allows for things like storing TOTP keys, generating new, secure passwords, and all that fun stuff. Except unlike others that I’ve seen, it has one difference: You can self-host an instance. Though, their self-hosted options look a little lacking unless you want to give them money. Well as it happens with an open sourced project, someone decided to create a Bitwarden API compatible server, thus creating vaultwarden. And this is why it’s cool.

A note on the name 'vaultwarden'

This project used to be named “bitwarden_rs,” but has since changed names to “vaultwarden” to, as the GitHub states, “separate itself from the official Bitwarden server in the hopes of avoiding confusion and trademark/branding issues.” The associated discussion mentions “user confusion,” which I can totally see, but a part of me also wonders if using the name “bitwarden” brought someone’s legal team snooping around.

Also, I noticed this change on complete accident yesterday as it happened. And yes, as long as we’re talking about the name, all the documentation refers to “vaultwarden” in all lowercase, violating the usual English capitalization rules for proper nouns, but since that’s how the docs do it, that’s how I’ll do it.

As a quick reminder, this is not an official project, and is not affiliated with Bitwarden itself in any way, shape, or form. Anyways, that out of the way, unlike all the pricing options offered by the official Bitwarden server, vaultwarden just has everything, no payments. And it’s distribution couldn’t be simpler (in theory): Just a docker image. Just run vaultwarden/server with container port 80 mapped, and you’re up and running, though you might want to do a few other things:

  • Bind /data to a volume or a folder on the host, for persistence
  • Set the LOG_FILE environment variable to a file in /data/ so you can easily read the log
  • Set SIGNUPS_ALLOWED to true to… allow signups if you wish
  • Set ADMIN_TOKEN to some (secure) string to allow access to the admin page

All you need after that is an email and master password for your account. Bitwarden is pretty cool about how it handles your data — only the client device, meaning the browser extension or Bitwarden client program, has access to your decrypted data. All data on the server is encrypted using an encryption key generated from that master password.1 Besides storing your logins and passwords (and TOTP keys!), you can also store, for some reason, “identities” (name, address, contact info…) and cards (actual credit / debit card data for payments) for easier form filling. Additionally, a fourth data type called “secure notes” is just an arbitrary text field to store whatever you like.

If you feel like being extra secure, you can require a TOTP or hardware 2FA key in addition to your master password. By default, this is only required for new clients. If you’ve already signed in with one before, you just need that password. Otherwise, if it’s never been seen before, you need the key.2 Also, most clients, as long as they’re running, don’t properly sign you out after inactivity, they just “lock” which requires the master password to unlock. And, yes, you can change that master password but it will require re-encrypting all your data with the new derived key.

Personally, I’m not too much of a fan of the only official vaultwarden “installation” method being Docker, I prefer to have actual executables if possible, especially since my current infrastructure setup means I’m running Docker in an LXC container with the nesting feature flag. It’s not perfect, and there’s likely a small performance penalty, but… I just don’t like it, I’d rather have some distributable package that’s easy enough to install and drop in a systemd unit for. But that’s probably just me being me. (though, just cloning the Git repository and building it from source is always a valid option for having an actual executable, if that’s what someone really wants.)

So in the end if you like the idea of a password manager, yet want one that’s open sourced and gives you full control of your data, check out the vaultwarden server implementation, just remember to enable the TLS options (explained by their docs) or put it behind a reverse proxy, many browsers will keep the APIs that it wants to use from being used over a plain HTTP connection, you need HTTPS for that.

Two other neat features

I just didn’t think they’re big enough to warrant calling out in the main article, since this isn’t meant to be a comprehensive review.

The first is WebSocket support for the desktop and web browser clients, meaning that, when set up correctly, you can have either of those clients update live as you change your vault. This doesn’t work for mobile clients since they use standard push notifications, which is different depending on if you’re on iOS or Android, and in either case, that is not supported in vaultwarden just yet.

The second is sends. This is a feature wherein you can upload some file (or some text) to the server, potentially protect it with a password, and set an expiry time and a maximum view count. This will generate a link to the data that can then get decrypted client-side, with a password if you entered one, and this link can be shared to anyone (assuming the domain name you assigned to the vaultwarden server can actually be reached from where ‘someone else’ is.) Once the time expires, or it’s been viewed the specified number of times, it expires itself, meaning it can’t be looked at anymore.

  1. The default is 100,000 rounds of PBKDF2, SHA-256. You can change this for your account as you wish. ↩︎

  2. Maybe it’s just my Hackintosh, but every time Bitwarden updates, and, by extension (hah!) updates the Safari extension, that’s a “new client” that I need to re-authenticate to. THough as of recently, it’s not adding the extension to Safari at all, a known bug because… Apple. ↩︎