Breached Password Detection

What Is Breached Password Detection?

Breached password detection consists of the following tasks:

1. Finding breached and compromised passwords.
2. Building a system to download, process and store these datasets.
3. Checking passwords to see if they’ve been compromised.
4. Taking action when a compromised credential is found.

FusionAuth has taken care of steps 1, 2 and 3. All you need to do is to configure the desired action.

The end goal of detecting breached passwords is to have a more secure auth system and to avoid unauthorized access due to compromised user credentials.

How Do I Use Breached Password Detection?

This feature is only available in paid plans. Please visit our pricing page to learn more.

Here’s a video showing setup and usage of the breached password detection feature.

Conceptually, FusionAuth uses a pull model rather than a push model. Passwords are checked in real time when users provide them: at registration, password change, or, optionally, during login.

Setting Up

The first step to enabling breached password detection is to have a valid license key. Please visit our pricing page to buy a license.

The next step is to activate the license. You’ll need to ensure that your FusionAuth instance has outbound network access. To activate, simply follow the steps outlined in the Reactor documentation.

Then, navigate to Tenants and edit the tenant for which you wish to enable the feature. Go to the Password tab and the Breached password detection settings section. Click the checkbox to enable breached password detection. This will enable additional configuration options, as seen below:

The default settings prevent use of compromised credentials in a number of contexts. Simply by enabling breached password detection, all users within this tenant will, from that moment forward, no longer be able to use any password that has been found to be breached by the FusionAuth team.

Passwords will be checked any time they are created or changed, such as when:

• A user is created
• A password change is initiated by an end user
• A administrator modifies a user’s password

Below, you can see an administrative user has received an error message because they attempted to update a password to a compromised value:

If an administrative user changes any other user attribute without modifying the password, it won’t be checked.

Any password creation or change, whether through user interaction with themed pages or an API call, will check the provided text against the latest corpus of compromised passwords. If there is a match, an error will be returned.

Configuration Options

While the default settings are secure, you may want to configure this feature further. The Breached password detection settings section contains additional configuration options:

Each of these configuration options can be updated using either the administrative interface or by calling the Tenant API.

Let’s examine each of these in turn.

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:

What Is Allowed In Each Match Mode

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.

Recording the Breach

Recording the breach and optionally firing a webhook is a good fit for two scenarios. If you’re exploring breached password detection and are unsure how it will affect your end users, use this to gauge the number of compromised passwords.

Another reason to use this option is if you want to rely solely on webhooks to take the appropriate action. You may handle a breached password in custom code, rather than using any of the default FusionAuth options. You could:

• Automatically run a security audit on systems to which the user with the compromised credentials has access
• Lock the account and send an SMS notification
• Force a password change and also flip a flag on their account to more closely monitor it for suspicious activity in the future

All of these require custom code on your end, of course.

Sending an Email

Sending the user an email lets the user know that their account could be compromised, but doesn’t require any action.

This email is an email template which can be customized and localized like other email templates. You’ll typically include a link to reset their password, but you may want to include other information as well. Below are the default templates.

HTML

[#setting url_escaping_charset="UTF-8"]
<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="http://localhost:9011/password/forgot?client_id=${(application.oauthConfiguration.clientId)!''}&email=${user.email?url}&tenantId=${user.tenantId}">
  http://localhost:9011/password/forgot?client_id=${(application.oauthConfiguration.clientId)!''}&email=${user.email?url}&tenantId=${user.tenantId}
</a>

- FusionAuth Admin

Text

[#setting url_escaping_charset="UTF-8"]
This password was found in the list of vulnerable passwords, and is no longer secure.

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

Follow this link to change your password.

http://localhost:9011/password/forgot?client_id=${(application.oauthConfiguration.clientId)!''}&email=${user.email?url}&tenantId=${user.tenantId}

- FusionAuth Admin

Please see the email template documentation for more information, including available variables.

Requiring a Password Change

Another option for handling breached passwords at login is to require a password change. Once a password has been found to be breached, the account is marked as requiring a password change. The user is forced to change it whenever they attempt to login. Changing the ‘On login’ setting to a different option will have no effect on accounts already marked as needing a password change.

If you are using the FusionAuth themed login pages, after the user logs in with a compromised password they will see a page generated by the “OAuth Change password form” template. As with any other template, you can customize it. Please check out the themes documentation for more information.

If you are instead using the login API, the API call will respond with a 203 HTTP status code. Please review the API documentation for more information.

You can also read the End User Experience section for more on what the end user will see.

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.

Breached Password Detection Reporting

Reporting is a key part of breached password detection. Aggregate information across all your users informs actions to take on detection, both within FusionAuth and in external systems.

Reports let you know which users have breached account credentials. This allows you to contact the user or take other actions on the compromised account.

Overview Report

To view 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.

End User Experience

What does the end user see when a breached password is detected? It depends on whether they are registering or logging in when the breach is detected.

It also is different if you are using the FusionAuth provided templates or have built your own integration using APIs.

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.

JSON Response When A User Registers With A Breached Password

{
  "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:

JSON Response When A User Logs In With A Breached Password

{
  "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.

How It Works

Here’s a high level diagram of the FusionAuth breached password detection service:

New breached passwords are ingested and processed by FusionAuth on an ongoing basis. An additional encryption key is used to securely communicate with the FusionAuth Reactor service using a strong AES cipher.

You can modify this key by navigating to Reactor and clicking the Regenerate Key button. When you do so, you’ll be prompted to confirm this decision:

Do this if you there was any chance the key was compromised, if directed to do so by FusionAuth support, or if you are troubleshooting your Reactor service connection.

Limitations

Breached password detection in FusionAuth has a few limitations of which you should be aware.

As you might expect, it can’t check passwords controlled by other systems, such as when you use an external identity provider.

All other password rules, as defined in the tenant configuration, also apply when passwords are changed. If you set a minimum length requirement of 25 characters, both conditions must be satisfied for a password to be accepted. Therefore, the user will have to select a password at least 25 characters long and not known to have been compromised.

Breached password detection is configured at the tenant level and applies to all applications within that tenant. For example, if you enable detection for the Default tenant, which contains the FusionAuth application, administrative users with access to that application will have their passwords checked.

The breached password detection webhook event, user.password.breach, is only fired when login breach detection is enabled. It is not fired at registration or password modification because in these cases the compromised password has never entered the FusionAuth system.