Package org.keycloak.policy

Class DenylistPasswordPolicyProviderFactory

java.lang.Object
org.keycloak.policy.DenylistPasswordPolicyProviderFactory
All Implemented Interfaces:
PasswordPolicyProviderFactory, org.keycloak.provider.ProviderFactory<org.keycloak.policy.PasswordPolicyProvider>
public class DenylistPasswordPolicyProviderFactory extends Object implements PasswordPolicyProviderFactory
Creates DenylistPasswordPolicyProvider instances.

Password denylists are simple text files where every line is a denylisted password delimited by a newline character \n.

Denylists can be configured via the Authentication: Password Policy section in the admin-console. A denylist-file is referred to by its name in the policy configuration.

Denylist location

Users can provide custom denylists by adding a denylist password file to the configured denylist folder.

The location of the password-blacklists folder is derived as follows

  1. the value of the System property keycloak.password.blacklists.path if configured - fails if folder is missing
  2. the value of the SPI config property: blacklistsPath when explicitly configured - fails if folder is missing
  3. otherwise $KC_HOME/data/password-blacklists/ if nothing else is configured
To configure the denylist folder via CLI use --spi-password-policy-password-blacklist-blacklists-path=/path/to/denylistsFolder

Note that the preferred way for configuration is to copy the password file to the $KC_HOME/data/password-blacklists/ folder

A password denylist with the filename 10_million_passwords.txt that is located beneath $KC_HOME/data/keycloak/blacklists/ can be referred to as 10_million_passwords.txt in the Authentication: Password Policy configuration.

False positives

The current implementation uses a probabilistic data-structure called BloomFilter which allows for fast and memory efficient containment checks, e.g. whether a given password is contained in a denylist, with the possibility for false positives. By default a false positive probability DEFAULT_FALSE_POSITIVE_PROBABILITY is used. To change the false positive probability via CLI configuration use --spi-password-policy-password-blacklist-false-positive-probability=0.00001

Author:
Thomas Darimont

  • Field Details

  • Constructor Details

    • DenylistPasswordPolicyProviderFactory

      public DenylistPasswordPolicyProviderFactory()

  • Method Details

    • create

      public org.keycloak.policy.PasswordPolicyProvider create(org.keycloak.models.KeycloakSession session)
      Specified by:
      create in interface org.keycloak.provider.ProviderFactory<org.keycloak.policy.PasswordPolicyProvider>

    • init

      public void init(org.keycloak.Config.Scope config)
      Specified by:
      init in interface org.keycloak.provider.ProviderFactory<org.keycloak.policy.PasswordPolicyProvider>

    • postInit

      public void postInit(org.keycloak.models.KeycloakSessionFactory factory)
      Specified by:
      postInit in interface org.keycloak.provider.ProviderFactory<org.keycloak.policy.PasswordPolicyProvider>

    • close

      public void close()
      Specified by:
      close in interface org.keycloak.provider.ProviderFactory<org.keycloak.policy.PasswordPolicyProvider>

    • getDisplayName

      public String getDisplayName()
      Specified by:
      getDisplayName in interface PasswordPolicyProviderFactory

    • getConfigType

      public String getConfigType()
      Specified by:
      getConfigType in interface PasswordPolicyProviderFactory

    • getDefaultConfigValue

      public String getDefaultConfigValue()
      Specified by:
      getDefaultConfigValue in interface PasswordPolicyProviderFactory

    • isMultiplSupported

      public boolean isMultiplSupported()
      Specified by:
      isMultiplSupported in interface PasswordPolicyProviderFactory

    • getId

      public String getId()
      Specified by:
      getId in interface org.keycloak.provider.ProviderFactory<org.keycloak.policy.PasswordPolicyProvider>

    • getDefaultDenylistsBasePath

      public String getDefaultDenylistsBasePath()
      Method to obtain the default location for the list folder. The method will return the data directory of the Keycloak instance concatenated with /password-blacklists/.
      Returns:
      The default path used by the provider to lookup the lists when no other configuration is in place.

    • resolvePasswordDenylist

      public DenylistPasswordPolicyProviderFactory.PasswordDenylist resolvePasswordDenylist(String denylistName)
      Resolves and potentially registers a DenylistPasswordPolicyProviderFactory.PasswordDenylist for the given denylistName.
      Parameters:
      denylistName -
      Returns:

    • getFalsePositiveProbability

      protected double getFalsePositiveProbability()

    • getCheckIntervalSeconds

      protected int getCheckIntervalSeconds()

    • getConfigMetadata

      public List<org.keycloak.provider.ProviderConfigProperty> getConfigMetadata()
      Specified by:
      getConfigMetadata in interface org.keycloak.provider.ProviderFactory<org.keycloak.policy.PasswordPolicyProvider>

    • buildBloomFile

      public static void buildBloomFile(Path inputFile, Path outputFile, double fpp) throws IOException
      Builds a pre-computed Bloom filter (.bloom) file from a plaintext password denylist file. Each line is treated as one password (lowercased before insertion).
      Parameters:
      inputFile - path to the plaintext password list (one password per line, UTF-8)
      outputFile - path for the generated .bloom file
      fpp - desired false-positive probability (e.g. 0.0001)
      Throws:
      IOException - if the input file cannot be read or the output file cannot be written