Skip to main content

Host your own breached password detection API

Ory Kratos uses the Have I Been Pwned (HiBP) API, with the k-anonymity flag, to check if the password the user registers with has been a part of one of the breaches documented by the HiBP project.

In some environments, due to various CISO policies, it might be difficult to establish egress connectivity to non-approved hosts. If it happens that your Kratos operates in such an environment and it can't communicate with the HiBP API at haveibeenpwned.com, but there is the requirement to check if passwords have been leaked, you can host the HiBP API yourself and configure Kratos to use your own instance.

To do so, configure Kratos to use your API:

"path/to/kratos/config.yml
selfservice:
  methods:
    password:
      config:
        haveibeenpwned_host: api.private.host

An example of a minimal self-hosted, k-anonymity enabled HiBP API can be found in this repository.

Alternatively, this feature can be disabled altogether. Note however that by doing so you will significantly decrease the security of the service and not follow NIST guidelines:

When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised. For example, the list MAY include, but isn't limited to:

  1. Passwords obtained from previous breach corpuses.
  2. Dictionary words.
  3. Repetitive or sequential characters (for example ‘aaaaaa’, ‘1234abcd’).
  4. Context-specific words, such as the name of the service, the username, and derivatives thereof.

If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.

Disabling the feature will effectively remove checks for the points 1.-3. The feature can be disabled by setting the following configuration values:

"path/to/kratos/config.yml
selfservice:
  methods:
    password:
      config:
        haveibeenpwned_enabled: false
note

Ory Kratos haveibeenpwned_host setting doesn't allow configuring the respective CA chain at the moment but it does require a TLS connection. Therefore your private HiBP API must use one of the trusted CAs of the underlying operating system.

A solution might be to host the HiBP API using a certificate issued by Let's Encrypt certificate or install the private CA certificate in the trusted CA certificates of the system on which Kratos is running.