Package org.keycloak.policy

Class DenylistPasswordPolicyProviderFactory

java.lang.Object

org.keycloak.policy.DenylistPasswordPolicyProviderFactory

All Implemented Interfaces:

PasswordPolicyProviderFactory, ProviderFactory<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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DenylistPasswordPolicyProviderFactory.FileBasedPasswordDenylist	A DenylistPasswordPolicyProviderFactory.FileBasedPasswordDenylist uses password-denylist files to construct a DenylistPasswordPolicyProviderFactory.PasswordDenylist.
static interface	DenylistPasswordPolicyProviderFactory.PasswordDenylist	A DenylistPasswordPolicyProviderFactory.PasswordDenylist describes a list of too easy to guess or potentially leaked passwords that users should not be able to use.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	BLACKLISTS_FALSE_POSITIVE_PROBABILITY_PROPERTY
static final String	BLACKLISTS_PATH_PROPERTY
static final String	CHECK_INTERVAL_SECONDS_PROPERTY
static final int	DEFAULT_CHECK_INTERVAL_SECONDS
static final double	DEFAULT_FALSE_POSITIVE_PROBABILITY
static final String	ID
static final String	JBOSS_SERVER_DATA_DIR
static final String	PASSWORD_BLACKLISTS_FOLDER
static final String	SYSTEM_PROPERTY

Constructor Summary

Constructors

Constructor	Description
DenylistPasswordPolicyProviderFactory()

Method Summary

Modifier and Type	Method	Description
static void	buildBloomFile(Path inputFile, Path outputFile, double fpp)	Builds a pre-computed Bloom filter (.bloom) file from a plaintext password denylist file.
void	close()	This is called when the server shuts down.
PasswordPolicyProvider	create(KeycloakSession session)
protected int	getCheckIntervalSeconds()
List<ProviderConfigProperty>	getConfigMetadata()	Returns the metadata for each configuration property supported by this factory.
String	getConfigType()
String	getDefaultConfigValue()
String	getDefaultDenylistsBasePath()	Method to obtain the default location for the list folder.
String	getDisplayName()
protected double	getFalsePositiveProbability()
String	getId()
void	init(Config.Scope config)	Only called once when the factory is first created.
boolean	isMultiplSupported()
void	postInit(KeycloakSessionFactory factory)	Called after all provider factories have been initialized
DenylistPasswordPolicyProviderFactory.PasswordDenylist	resolvePasswordDenylist(String denylistName)	Resolves and potentially registers a DenylistPasswordPolicyProviderFactory.PasswordDenylist for the given denylistName.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.keycloak.provider.ProviderFactory

dependsOn, order

Field Details

ID

public static final String ID

See Also:

• Constant Field Values

SYSTEM_PROPERTY

public static final String SYSTEM_PROPERTY

See Also:

• Constant Field Values

BLACKLISTS_PATH_PROPERTY

public static final String BLACKLISTS_PATH_PROPERTY

See Also:

• Constant Field Values

BLACKLISTS_FALSE_POSITIVE_PROBABILITY_PROPERTY

public static final String BLACKLISTS_FALSE_POSITIVE_PROBABILITY_PROPERTY

See Also:

• Constant Field Values

CHECK_INTERVAL_SECONDS_PROPERTY

public static final String CHECK_INTERVAL_SECONDS_PROPERTY

See Also:

• Constant Field Values

DEFAULT_FALSE_POSITIVE_PROBABILITY

public static final double DEFAULT_FALSE_POSITIVE_PROBABILITY

See Also:

• Constant Field Values

DEFAULT_CHECK_INTERVAL_SECONDS

public static final int DEFAULT_CHECK_INTERVAL_SECONDS

See Also:

• Constant Field Values

JBOSS_SERVER_DATA_DIR

public static final String JBOSS_SERVER_DATA_DIR

See Also:

• Constant Field Values

PASSWORD_BLACKLISTS_FOLDER

public static final String PASSWORD_BLACKLISTS_FOLDER

Constructor Details

DenylistPasswordPolicyProviderFactory

public DenylistPasswordPolicyProviderFactory()

Method Details

create

public PasswordPolicyProvider create(KeycloakSession session)

Specified by:

create in interface ProviderFactory<PasswordPolicyProvider>

init

public void init(Config.Scope config)

Description copied from interface: ProviderFactory

Only called once when the factory is first created.

Specified by:

init in interface ProviderFactory<PasswordPolicyProvider>

postInit

public void postInit(KeycloakSessionFactory factory)

Description copied from interface: ProviderFactory

Called after all provider factories have been initialized

Specified by:

postInit in interface ProviderFactory<PasswordPolicyProvider>

close

public void close()

Description copied from interface: ProviderFactory

This is called when the server shuts down.

Specified by:

close in interface ProviderFactory<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 ProviderFactory<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<ProviderConfigProperty> getConfigMetadata()

Description copied from interface: ProviderFactory

Returns the metadata for each configuration property supported by this factory.

Specified by:

getConfigMetadata in interface ProviderFactory<PasswordPolicyProvider>

Returns:

a list with the metadata for each configuration property supported by this factory

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