Skip to content

Use inclusive terminology in docs (blacklist/whitelist -> denylist/allowlist) #51453

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adityaanikam wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Use inclusive terminology in docs (blacklist/whitelist -> denylist/allowlist) #51453

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3220b49
Use inclusive terminology in docs (blacklist/whitelist -> denylist/al…
adityaanikam Aug 5, 2026
701a906
Restore closing WARNING block delimiter dropped during rebase conflic…
adityaanikam Aug 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/documentation/server_admin/topics/authentication/kerberos.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ A typical use case for web authentication is the following:

[WARNING]
====
The https://datatracker.ietf.org/doc/html/rfc4559[Negotiate] www-authenticate scheme allows NTLM as a fallback to Kerberos and on some web browsers in Windows NTLM is supported by default. If a www-authenticate challenge comes from a server outside a browsers permitted list, users may encounter an NTLM dialog prompt. A user would need to click the cancel button on the dialog to continue as {project_name} does not support this mechanism. This situation can happen if Intranet web browsers are not strictly configured or if {project_name} serves users in both the Intranet and Internet. A https://github.com/keycloak/keycloak/issues/8989[custom authenticator] can be used to restrict Negotiate challenges to a whitelist of hosts.
The https://datatracker.ietf.org/doc/html/rfc4559[Negotiate] www-authenticate scheme allows NTLM as a fallback to Kerberos and on some web browsers in Windows NTLM is supported by default. If a www-authenticate challenge comes from a server outside a browsers permitted list, users may encounter an NTLM dialog prompt. A user would need to click the cancel button on the dialog to continue as {project_name} does not support this mechanism. This situation can happen if Intranet web browsers are not strictly configured or if {project_name} serves users in both the Intranet and Internet. A https://github.com/keycloak/keycloak/issues/8989[custom authenticator] can be used to restrict Negotiate challenges to an allowlist of hosts.
Comment on lines 19 to +21
====

Perform the following steps to set up Kerberos authentication:
Expand Down
18 changes: 9 additions & 9 deletions docs/documentation/server_admin/topics/authentication/password-policies.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,22 +133,22 @@ Password cannot be already used by the user. {project_name} stores a history of
Password cannot be reused within the configured time period (in days).
If the new password was last set within this period, the user will be forced to provide a different one.

===== Password blacklist
Password must not be in a blacklist file.
===== Password denylist
Password must not be in a denylist file. This option is shown as *Password Blacklist* in the Admin Console's password policy drop-down.

* Blacklist files are UTF-8 plain-text files with Unix line endings. Every line represents a blacklisted password.
* Denylist files are UTF-8 plain-text files with Unix line endings. Every line represents a denylisted password.
* {project_name} compares passwords in a case-insensitive manner.
* The value of the blacklist file must be the name of the blacklist file, for example, `100k_passwords.txt`.
* Blacklist files resolve against `+${kc.home.dir}/data/password-blacklists/+` by default. Customize this path using:
* The value of the denylist file must be the name of the denylist file, for example, `100k_passwords.txt`.
* Denylist files resolve against `+${kc.home.dir}/data/password-blacklists/+` by default. Customize this path using:
** The `keycloak.password.blacklists.path` system property.
** The `blacklistsPath` property of the `passwordBlacklist` policy SPI configuration. To configure the blacklist folder using the CLI, use `+--spi-password-policy--password-blacklist--blacklists-path=/path/to/blacklistsFolder+`.
* Blacklist files are reloaded automatically when modified.
** The `blacklistsPath` property of the `passwordBlacklist` policy SPI configuration. To configure the denylist folder using the CLI, use `+--spi-password-policy--password-blacklist--blacklists-path=/path/to/blacklistsFolder+`.
* Denylist files are reloaded automatically when modified.
** The file is checked for updates during password policy validation but at most once every 60 seconds. Use `+--spi-password-policy--password-blacklist--check-interval-seconds=<seconds>+` to change the default (0 to disable).
** The blacklist file must be updated atomically (write to a temp file, then rename) to avoid reading a partially written file.
** The denylist file must be updated atomically (write to a temp file, then rename) to avoid reading a partially written file.

.A note about False Positives

The current implementation uses a BloomFilter for fast and memory efficient containment checks, such as whether a given password is contained in a blacklist, with the possibility for false positives.
The current implementation uses a BloomFilter for fast and memory efficient containment checks, such as whether a given password is contained in a denylist, with the possibility for false positives.

* By default a false positive probability of `0.01%` is used.
* To change the false positive probability by CLI configuration, use `+--spi-password-policy--password-blacklist--false-positive-probability=0.00001+`.
Expand Down
10 changes: 5 additions & 5 deletions docs/guides/securing-apps/client-registration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ Currently we have these policy implementations:

* Trusted Hosts Policy - You can configure list of trusted hosts and trusted domains. Request to Client Registration Service can be sent just from those hosts or domains.
Request sent from some untrusted IP will be rejected. URLs of newly registered client must also use just those trusted hosts or domains. For example it won't be allowed
to set `Redirect URI` of client pointing to some untrusted host. By default, there is not any whitelisted host, so anonymous client registration is de-facto disabled.
to set `Redirect URI` of client pointing to some untrusted host. By default, there is not any allowlisted host, so anonymous client registration is de-facto disabled.

NOTE: {project_name} normalizes loopback addresses to `localhost` to avoid platform-specific
reverse-DNS differences (for example on Windows a reverse lookup of loopback may return the numeric IP rather than `localhost`). All other trusted domains must be based upon the primary reverse-DNS lookup returned by the platform.
Expand All @@ -220,12 +220,12 @@ reverse-DNS differences (for example on Windows a reverse lookup of loopback may
see consent screen when he needs to approve permissions (client scopes). It means that client won't have access to any personal
info or permission of user unless user approves it.

* Protocol Mappers Policy - Allows to configure list of whitelisted protocol mapper implementations. New client can't be registered
or updated if it contains some non-whitelisted protocol mapper. Note that this policy is used for authenticated requests as well, so
* Protocol Mappers Policy - Allows to configure list of allowlisted protocol mapper implementations. New client can't be registered
or updated if it contains some non-allowlisted protocol mapper. Note that this policy is used for authenticated requests as well, so
even for authenticated request there are some limitations which protocol mappers can be used.

* Client Scope Policy - Allow to whitelist `Client Scopes`, which can be used with newly registered or updated clients.
There are no whitelisted scopes by default; only the client scopes, which are defined as `Realm Default Client Scopes` are whitelisted by default.
* Client Scope Policy - Allowlist `Client Scopes` for use with newly registered or updated clients.
There are no allowlisted scopes by default; only the client scopes, which are defined as `Realm Default Client Scopes` are allowlisted by default.

* Full Scope Policy - Newly registered clients will have `Full Scope Allowed` switch disabled. This means they won't have any scoped
realm roles or client roles of other clients.
Expand Down