Vaultwarden and Home Assistant: Create Your Self-Hosted Password Manager (Complete Guide)

Password Manager: Definition and Importance for Your Security

We keep hearing that we should use different, long and complex passwords for every online account. But in reality, managing a multitude of different and complex passwords is not really possible. A password manager is designed to solve this problem by storing, generating and organizing your passwords securely. Instead of having to remember each password, you only need to remember a single password. This is what we call the "master password". It grants access to all your other passwords.

The importance of a password manager lies primarily in the enhanced security it provides. By using strong and unique passwords for each account, you significantly reduce the risk of being hacked. On top of that (and that alone is already great!), a password manager makes daily management of your logins easier by automatically filling in your credentials when you sign in, saving you precious time and minimizing input errors.

Why Choose Vaultwarden: Advantages Over Other Password Managers

As you may have guessed, Vaultwarden is what I'm going to introduce today! In reality, Vaultwarden is an open-source derivative of Bitwarden, designed to offer a self-hosted solution. Building on Bitwarden's code, Vaultwarden allows users to fully control their sensitive data without relying on a third-party service.

Among the many password managers available on the market, Vaultwarden stands out with a range of advantages that make it the perfect solution for security-conscious individuals. First of all, Vaultwarden is an open source solution, which means its source code is accessible to everyone. This transparency allows it to be audited by the community, unlike commercial password managers whose source code quality is not always known. This characteristic ensures better reliability and enhanced security, as vulnerabilities can be identified and fixed more quickly.

Another major advantage of Vaultwarden is its ability to be self-hosted. Unlike commercial password managers that store your data on their own servers, Vaultwarden allows you to host your passwords locally or on a server of your choice. This gives you full control over your data, reducing the risk of data breaches by third parties and increasing the confidentiality of your personal and professional information.

Finally, a companion add-on is available for Home Assistant, which allows you to integrate it extremely easily. Thanks to this compatibility, Vaultwarden becomes a natural extension of your home automation system.

In terms of cost, Vaultwarden positions itself as an affordable alternative compared to paid solutions such as LastPass or Dashlane. Indeed, Vaultwarden is free! I know some will think "if it's free, it must be inferior". Well, that's not necessarily true. The best example is LastPass, one of the world's leading password managers. In 2022, it suffered a major breach exposing users' encrypted passwords as well as their unencrypted personal information!

Installing Vaultwarden with Home Assistant

First of all, please note that accessing Home Assistant with a domain name is mandatory to follow this article. I have always shown Cloudflared, so that is what we will use. For those using Nginx Proxy Manager, it will be easily adaptable. In all cases, Cloudflared (or Nginx Proxy Manager) must already be configured!

For this, nothing could be simpler: an add-on is here for that.

Go to Settings > Add-ons > Add-on Store, then in the Home Assistant Community Add-ons section you should find Vaultwarden (Bitwarden). Click on it and hit "Install".

Before launching it, go to its configuration (the Configuration tab). Here we will disable the SSL option, since it will be automatically handled by Cloudflared. Then in the network section, note the port on which you can access the Vaultwarden interface, which will generally be 7277.

Configuring Cloudflared to Access Vaultwarden

To access our password manager, we need to tell Cloudflared to use a new subdomain that will redirect to our port 7277, used by Vaultwarden.

To do this, go to Settings > Add-ons > Cloudflared. Then in the Configuration tab, you will find an Additional Hosts section. Here is an example configuration to enter:

For more details, next to hostname you will enter a new subdomain, which can be anything you like.

Next to service, it will be the hostname of your Home Assistant instance followed by the Vaultwarden port. Most often it is "homeassistant". To find your hostname, go to Settings > System > Network. The first field will correspond to the hostname.

Once done, you can save and restart Cloudflared.

Starting Vaultwarden and Accessing the Administration

Go back to the Vaultwarden add-on, start it, and click on the Log tab at the top. You should see something like this:

As you can see, we have a TEMPORARY token, here "jNhKtXrmFh0A5MVHZFJ0iV8RCRcj8F7m27T9MwTQf02co6sfHL0s9QCrsCvuKNN7". Copy it and go to vaultwarden.YOUR_DOMAIN.com (change it according to what you entered in Cloudflared).

You will be asked for the "admin token". Paste the code you just copied.

As I just told you, the access token is temporary, and you have a message reminding you at the top. In fact, to be secure, you need to generate an encrypted password in Argon2 with specific parameters. For beginners, this can be a bit tricky, so this article is here to simplify the task for you! 🤓

You can use the generator just below to enter a password that will be converted to Argon2. WARNING! This password must be particularly strong and you will need to remember it. It grants access to your Vaultwarden administration. Enter your password and copy the generated hash.

Good. Now in the Vaultwarden administration, click on "General settings" and you will find at the bottom "Admin token/Argon2 PHC", that's where you need to paste the obtained hash. Once your hash is pasted, you can click on "Save" at the bottom. You can log out and log back in (using the password entered in the generator above) to verify that everything works properly.

Checking Vaultwarden Diagnostics

Before going further, go to the Diagnostics tab in the administration. You should see several green indicators, but probably also some red ones, particularly on Domain Configuration. This is normal: Vaultwarden thinks you are on localhost when in reality you are using your personal domain name.

To fix this, go to Settings > General Settings and enter your full domain name in the designated field (for example https://vaultwarden.YOUR_DOMAIN.com). Click "Save" then go back to Diagnostics: everything should now be green.

If you are not using Cloudflared and the IP header indicator remains red, go to Settings > Advanced Settings and replace the value of the Client IP Header field with CF-Connecting-IP (without a leading space). This allows Cloudflare to correctly transmit the real IP address of visitors. Click "Save" and verify again that everything is green.

Configuring Email Sending (SMTP via Gmail)

Sending emails is an important step, especially for account recovery in case of password loss or to enable email-based two-factor authentication. For this, Vaultwarden needs an SMTP server.

The good news is that you can use Gmail for free for this purpose. However, I recommend creating a dedicated Google account rather than using your personal account, as using the same account for sending and receiving sometimes causes issues.

Here is what to do:

1. Enable two-step verification on the Google account

Go to your Google account's security settings and enable two-step verification. This is an absolutely necessary prerequisite for the next steps.

2. Create an app password

Once two-step verification is enabled, access the app passwords page. To access it directly, replace the end of the URL in Sign-in options with AppPasswords. Give your application a name (for example "Vaultwarden") and click "Create". A password will be generated: copy it immediately.

3. Configure SMTP in Vaultwarden

Go back to the Vaultwarden administration, section Settings > SMTP Email Settings, and fill in the fields as follows:

Click "Save" at the bottom of the page. You can then test the sending by entering an email address in the test field and clicking "Send test e-mail". If you receive the email, everything is correctly configured!

Enabling Email Two-Factor Authentication

Now that email sending works, you can enable email 2FA for your users. Go to Settings > Email 2FA Settings and enable the option. By default, a 6-character code will be sent by email with an expiration of 600 seconds and a maximum of 3 attempts. These values are suitable in most cases, just click "Save".

Configuring YubiKey Keys

If you don't know about YubiKey keys, I really recommend looking into them. Basically, it's a physical key that you plug into your computer and press to validate a connection. Even if someone knows your password, without this key in their possession, they won't be able to access your account. You can therefore understand the enormous benefit with a password manager: if someone gets hold of your master password but doesn't have this key, they won't be able to access your vault.

To configure YubiKey keys in Vaultwarden, you first need to obtain an API Key from the Yubico website. Go to the dedicated page (link in the video description), enter your email address, accept the terms and conditions, then insert your key into the computer and press it. You will receive a Client ID and a Secret Key.

In the Vaultwarden administration, go to Settings > YubiKey Settings and enter the Client ID and Secret Key you obtained. Leave the server at its default value. Click "Save".

Recovering the Administration After Disabling It

If you have disabled the administration by removing the admin token and wish to reactivate it (for example to add a new user when registrations are closed), here is the procedure. It requires command line access via the Home Assistant SSH terminal.

1. Install the SSH terminal

If not already done, install the Advanced SSH & Web Terminal add-on from the add-on store. In the Info tab, disable protected mode (an alert will warn you that this is a sensitive operation), then restart the add-on.

2. Access the Vaultwarden Docker container

Open the terminal and list the Docker containers:

Find the container whose name contains "bitwarden" (Vaultwarden being a derivative of Bitwarden). Copy its name, then enter the container:

3. Edit the configuration file

Navigate to the data directory and install the Nano text editor:

Then open the configuration file:

Scroll all the way down and add, before the last closing brace, the following line:

Don't forget the comma at the end of the previous line. Save with CTRL+X, then Y, then Enter.

4. Restart and verify

Go back to Home Assistant and restart the Vaultwarden add-on. Access vaultwarden.YOUR_DOMAIN.com/admin again: you should be able to log in with the password corresponding to your Argon2 hash.

Important: once the operation is complete, remember to re-enable protected mode on the Advanced SSH & Web Terminal add-on and restart it.

Creating a User Account

Now that Vaultwarden is fully configured, it's time to create your first user account. First verify that registrations are allowed in Settings > General Settings (the "Allow new signups" option must be checked).

Access your Vaultwarden URL (without the /admin) and click "Create Account". Enter your email address, your name, and most importantly your master password. This password is crucial: it protects access to your entire vault. Choose it long, complex and unique.

If other members of your family wish to use Vaultwarden, now is the time to create their accounts as well.

Disabling Registrations and Securing the Installation

Once all accounts have been created, I strongly recommend that you:

1. Disable new registrations: in the administration, General Settings, uncheck "Allow new signups". Without this, anyone finding your URL could create an account and use your service.

2. Disable the administration: still in General Settings, completely delete the content of the Admin token field and click "Save". No one will be able to access the administration area anymore (except via the recovery procedure seen earlier).

Restart Vaultwarden for the changes to take effect. If you try to access /admin, you will see a message indicating that the administration is disabled. And if someone tries to create an account, they will receive an error indicating that registrations are disabled.

Logging In and Verifying Your Email

Now log in to Vaultwarden with your freshly created account. A message will ask you to verify your email address. Click "Send verification email", open the received email and click the verification button. Log in again and you will finally access your vault.

If you were already using another password manager, you can import your data directly from the Vaultwarden web interface by following the proposed import procedure.

Installing and Configuring the Browser Extension

To fully enjoy Vaultwarden on a daily basis, install the Bitwarden extension available on Chrome, Firefox, Edge and other browsers. Once installed, pin it to your toolbar for easy access.

When first launching the extension, instead of "Logging in on bitwarden.com", click and choose "Self-hosted". In the Server URL field, enter the URL of your Vaultwarden service (for example https://vaultwarden.YOUR_DOMAIN.com) and save.

Then log in with your email address and master password. If you have configured a YubiKey, you will be asked to touch it to validate the connection.

If you are the only user of your session, you can go to Settings > Account Security in the extension and change the vault timeout to avoid having to log in again every time the browser closes.

Mobile applications for Bitwarden are also available on Android and iPhone. They work exactly the same way as the browser extension, allowing you to have your passwords on absolutely all your devices.

Enabling Two-Factor Authentication on Your Account

Before you start using your vault on a daily basis, take the time to secure your account. Go to Settings > Security > Two-step login.

Enable YubiKey: click "Manage" next to the YubiKey OTP Security Key option, enter your master password, then click in an empty field, insert your key and press it. You can register up to 5 YubiKeys per account. I recommend having at least 2, in case you lose the first one.

Enable email verification: you can also enable email-based two-factor authentication. Enter your master password, confirm the code sending by email, then enter the received code. You will then have at least two types of two-factor authentication enabled on your account.

Daily Use of Vaultwarden

In practice, Vaultwarden works really well on a daily basis. Here are the main features you will use:

Automatic password saving

When you log in to a website, Vaultwarden will automatically offer to save the password. Simply click "Save" and the site will be added to your vault.

Auto-fill

The next time you visit the same site, Vaultwarden will offer to automatically fill in the login fields. One click and you're logged in.

Password generator

When registering on a new site, use the extension's built-in generator. Remember to check special characters and choose a sufficient length. Copy and paste the generated password and Vaultwarden will offer to save it automatically.

Two-factor authentication management (TOTP)

Vaultwarden is also capable of managing app-based two-factor authentication (TOTP). When a site offers to enable 2FA, retrieve the code (often by clicking "I can't scan the QR code") and enter it in your Vaultwarden entry, in the "Authenticator Key (TOTP)" field. A verification code will then be generated automatically.

The advantage is that when you use auto-fill to log in to a site, Vaultwarden automatically copies the TOTP code to your clipboard. You just need to paste it when the site asks for it.

Editing login information

Sometimes Vaultwarden saves the username instead of the email as the login identifier, or vice versa. Don't worry: click on the entry in question, then on "Edit" to correct the username.

Payment cards

In addition to your passwords, you can save your payment cards in Vaultwarden to avoid retyping them with every online purchase.

Identities (forms)

Identities allow you to store your personal information (name, first name, address, etc.) to automatically fill in registration or delivery forms. To use them, right-click on the page, then Bitwarden > Auto-fill identity and select the configured identity.

Storing Backup Codes

When you enable two-factor authentication on a site, it generally provides you with backup codes. These codes allow you to recover access to your account in case you lose your 2FA method. Remember to store them in Vaultwarden, either in the notes of the corresponding entry, or in custom hidden fields for added security.