FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    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?

    FusionAuth Reactor logo

    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.

    After you activate your license, there will be a delay before the breached password dataset is available and the feature is working. This delay is typically minutes and at most an hour.

    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:

    Turn on breached password detection

    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:

    Error message when an administrative user tries to use a compromised password.

    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:

    Breached password detection 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:

    Table 1. What Is Allowed In Each Match Mode
    Username Password High Medium Low

    richard@piedpiper.com

    This333ABCpassword!

    richard+test@piedpiper.com

    This333ABCpassword!

    jian@piedpiper.com

    This333ABCpassword!

    richard@piedpiper.com

    ADifferent333pass!

    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 is the default HTML template.

    HTML Breached Password Email Template
    
    <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

    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 the overview report, navigate to Reactor:

    Overview password breach report

    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:

    Individual password breach 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:

    The vulnerable password message in the admin interface

    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:

    Acting on a user

    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:

    What a user who is registering with a breached password will see.

    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:

    What a user who is signing in with a breached password will see.

    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:

    Diagram of the breached password detection system.

    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:

    Regenerating the AES key.

    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.

    Related Posts

    • Breached password detection best practices

    • Breached Password Detection: How to Lock User Accounts with a Webhook

    • How to enable breached password detection with FusionAuth

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    Subscribe for developer updates