Breached Password Detection

Match Mode

When FusionAuth is checking for compromised credentials, there are a number of ways to attempt to match them. Assume you have a user with the username richard@piedpiper.com and they are trying to sign up with the password This333ABCpassword!.

The system could match on the password string (This333ABCpassword!) only. If the password was in the dataset and any other user had ever used it, FusionAuth would consider this a match and not allow this password.

Another way of matching would be to see if there are any sub-email accounts associated with that password. These are also called aliases by some email providers such as gmail. For instance, richard+test@piedpiper.com is an alias of richard@piedpiper.com. The system could check multiple addresses, such as richard+test@piedpiper.com and richard+foo@piedpiper.com. All of these addresses would be paired with the provided password and checked against the datasets.

If you match on sub-email accounts, if the pair of richard+test@piedpiper.com and This333ABCpassword! was found in the corpus, FusionAuth would consider this a match and not allow this password. On the other hand, if jared@piedpiper.com and This333ABCpassword! were in the dataset, richard@piedpiper.com would still be allowed to use this password.

You could also narrow your scope further and match on only the username/password pair. If richard@piedpiper.com and password! appeared together in the password list, then FusionAuth would not allow this password. If richard+test@piedpiper.com and This333ABCpassword! or jared@piedpiper.com and This333ABCpassword! were, the password would be allowed.

You can control which level of matching will disallow use of a password. This is called the Match mode configuration setting and can be one of the following values:

• High means that should any of the above situations hold, the check fails. This is the strictest option.

• Medium means that an exact username and password match, a commonly compromised password is found, or a sub-email address match disqualifies the password.

• Low means that an exact username and password match or a commonly compromised password results in a failed check.

Assume the dataset contains richard@piedpiper.com with a password of This333ABCpassword!.com` with the same password. If the following users tried to register, the results for a given mode would be:

The stricter the match mode, the more likely your users will be forced to choose a different password because the one they choose is not secure.

On Login

The matching and prohibition of compromised passwords takes place whenever the user is creating or changing a password, as mentioned above. However, there is one other time when a breached password check might make sense: at login.

Consider this scenario: a user signs up on example.com with a password. They come to your site and sign up with the same password. They continue to use your application for months, but forget about their example.com account.

Then, example.com has a data breach. They may send out a notice, but your user may ignore it or may forget to change their password on every system where they used it.

If you only check for compromise when the password is created at registration or when modified, accounts will have credentials that have been compromised by breaches external to your system. The example.com breach negatively affects your application through the vector of the reused password.

For this reason, it’s a good idea to detect breached passwords whenever a user logs in.

However, this raises another issue. What do you do when you detect a breached password at login? At the other times FusionAuth is checking, the password is being modified, so it is easy to prohibit the compromised value; just notify the user that the password is not allowed.

However, at sign in, the user isn’t expecting to change their password. So what is the appropriate action? The answer is that it depends. FusionAuth allows you flexibility to meet your requirements. In order of increasing impact on the user, the options are:

• Record the breach in metrics

• Send the user an email

• Require the user to change their password

With any of these choices, you can configure a webhook to publish the password breach event.

<p>This password was found in the list of vulnerable passwords, and is no longer secure.</p>

<p>In order to secure your account, it is recommended to change your password at your earliest convenience.</p>

<p>Follow this link to change your password.</p>

<a href="https://local.fusionauth.io/password/forgot?email=${user.email}&tenantId=${user.tenantId}">
  https://local.fusionauth.io/password/forgot?email=${user.email}&tenantId=${user.tenantId}
</a>

- FusionAuth Admin

Recommended Settings

The recommended options for maximum protection from compromised passwords:

• Set the Match mode to High.

• Configure the On login option to require a password change. Alternatively, set this value to record the result and configure a webhook to process password breach events.

Of course, choose options that work for you and your system. This is why FusionAuth provides all the configuration flexibility outlined above.

Overview Report

To view the the overview report, navigate to Reactor:

This report displays the total number of checked passwords, detected breaches and accounts with action required. These numbers are displayed for the entire FusionAuth instance as well as on a per tenant basis, should you be using multi-tenant functionality.

User Report

You can also view a list of all users with breached passwords. To do so, click on the Breached users search button on the Reactor page. You’ll see this report:

This is a paginated list of users with compromised credentials. You can then manage the user or lock their account. If you navigate to the user’s details page, there is a warning about their vulnerable password:

An administrator is also able to modify the user account. Options include locking their account, forcing a password change or resetting their password and sending them an email:

Custom Reporting

If you have custom reporting needs, such as knowing the number of breached accounts over time, or finding how many users have had multiple password breaches, the best option is to ingest the data into your own analytics system.

You can do so by setting up a webhook to listen for the user.password.breach event. You can read more about setting up webhooks here.

FusionAuth Provided Templates

If you use the FusionAuth templates, users who are registering will see this message, if they pick a compromised password:

They will not be able to successfully complete a registration without choosing a more secure password.

If you enable breach detection on login, but do not require a password change, the end user will see no difference whether signing in with a secure or compromised password. If you configure FusionAuth to send an email, the user will receive that notice, of course.

If you, on the other hand, require a password change, when a user signs in with a breached password, they’ll see this screen:

These pages can be customized and localized, both in the messages displayed to the end user and in the look and feel. Please visit the themes documentation for more information.

API Responses

When you create a user with the User APIs and breached password detection is enabled, you’ll receive an error if the password is compromised. The HTTP status code will be 400 and you’ll receive a response containing an error object.

{
  "fieldErrors": {
    "user.password": [
      {
        "code": "[breachedCommonPassword]user.password",
        "message": "The [user.password] property value has been breached and may not be used, please select a different password."
      }
    ]
  }
}

If you enable breach detection on login and don’t require a password change, you’ll receive a 200 HTTP status code on successful login and the normal JSON response. Please see the Login API documentation for more information.

Alternatively, if you require a password change, you’ll receive a 203 HTTP status code. You’ll also receive JSON explaining why the password change is required:

{
  "changePasswordId": "yo0FiR_y7Rrtrk2vKe_F93PQ-nWljfGGWexgNSbHfXQ",
  "changePasswordReason": "Breached"
}

You can then use the Change a User’s Password API to, well, change the user’s password.