Skip to main content

WebAuthn

info

This page contains additional setup instructions if you need to test WebAuthn authentication locally.

The WebAuthn spec requires that a valid domain name is used. Since localhost does not satisfy this requirement, you need to configure your local instance to use a domain name.

There are multiple ways of doing this. However, the simplest method is to modify the operating system's host file with a loopback to 127.0.0.1.

Configuration

Webpack protects against DNS rebind attacks by blocking hostnames by default. However, we can specify specific hostnames to be allowed in the web environment configuration JSON files.

  1. Create a local.json file in the web/config/ folder

  2. Add "bitwarden.test" as an allowedHosts entry:

    {
    "dev": {
    "allowedHosts": ["bitwarden.test"]
    }
    }
note

If you are running the app, you must restart it for the config change to take effect.

Hosts file

note

You will need administrator access to edit this file.

The location of the host file differs slightly between operating systems.

C:\Windows\System32\drivers\etc\hosts

Open the file with the text editor of your choice. And append the following line.

127.0.0.1 bitwarden.test

User Secrets

In addition to modifying the host file, the user secret globalSettings:baseServiceUri:vault for API and Identity projects in the server needs to be created or updated to reflect the domain name. For example:

{
...
"globalSettings":{
"baseServiceUri":{
"vault":"https://bitwarden.test:8080"
}
},
...
}

Testing

You should now be ready to test WebAuthn on your local instance by going to https://bitwarden.test:8080.