Package org.keycloak.policy

Class BlacklistPasswordPolicyProviderFactory

java.lang.Object

org.keycloak.policy.BlacklistPasswordPolicyProviderFactory

All Implemented Interfaces:

PasswordPolicyProviderFactory, ProviderFactory<PasswordPolicyProvider>

public class BlacklistPasswordPolicyProviderFactory
extends Object
implements PasswordPolicyProviderFactory

Creates BlacklistPasswordPolicyProvider instances.

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

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

Blacklist location

Users can provide custom blacklists by adding a blacklist password file to the configured blacklist 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 blacklist folder via CLI use --spi-password-policy-password-blacklist-blacklists-path=/path/to/blacklistsFolder

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

A password blacklist 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 blacklist, 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	BlacklistPasswordPolicyProviderFactory.FileBasedPasswordBlacklist	A BlacklistPasswordPolicyProviderFactory.FileBasedPasswordBlacklist uses password-blacklist files as to construct a BlacklistPasswordPolicyProviderFactory.PasswordBlacklist.
static interface	BlacklistPasswordPolicyProviderFactory.PasswordBlacklist	A BlacklistPasswordPolicyProviderFactory.PasswordBlacklist 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 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
BlacklistPasswordPolicyProviderFactory()

Method Summary

Modifier and Type	Method	Description
void	close()	This is called when the server shuts down.
PasswordPolicyProvider	create(KeycloakSession session)
String	getConfigType()
String	getDefaultBlacklistsBasePath()	Method to obtain the default location for the list folder.
String	getDefaultConfigValue()
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
BlacklistPasswordPolicyProviderFactory.PasswordBlacklist	resolvePasswordBlacklist(String blacklistName)	Resolves and potentially registers a BlacklistPasswordPolicyProviderFactory.PasswordBlacklist for the given blacklistName.

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

getConfigMetadata, 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

DEFAULT_FALSE_POSITIVE_PROBABILITY

public static final double DEFAULT_FALSE_POSITIVE_PROBABILITY

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

BlacklistPasswordPolicyProviderFactory

public BlacklistPasswordPolicyProviderFactory()

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. This config is pulled from keycloak_server.json

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>

getDefaultBlacklistsBasePath

public String getDefaultBlacklistsBasePath()

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.

resolvePasswordBlacklist

public BlacklistPasswordPolicyProviderFactory.PasswordBlacklist resolvePasswordBlacklist(String blacklistName)

Resolves and potentially registers a BlacklistPasswordPolicyProviderFactory.PasswordBlacklist for the given blacklistName.

Parameters:

blacklistName -

Returns:

getFalsePositiveProbability

protected double getFalsePositiveProbability()