From 3220b4968bc47176068d51c2a3e95313c88b2e8d Mon Sep 17 00:00:00 2001 From: adityaanikam Date: Wed, 5 Aug 2026 15:10:48 +0530 Subject: [PATCH 1/2] Use inclusive terminology in docs (blacklist/whitelist -> denylist/allowlist) Fixes #51435 Signed-off-by: adityaanikam --- .../topics/authentication/kerberos.adoc | 3 +-- .../authentication/password-policies.adoc | 18 +++++++++--------- .../securing-apps/client-registration.adoc | 10 +++++----- 3 files changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/documentation/server_admin/topics/authentication/kerberos.adoc b/docs/documentation/server_admin/topics/authentication/kerberos.adoc index 13bffa10ad13..ca702c17e785 100644 --- a/docs/documentation/server_admin/topics/authentication/kerberos.adoc +++ b/docs/documentation/server_admin/topics/authentication/kerberos.adoc @@ -18,8 +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. Perform the following steps to set up Kerberos authentication: diff --git a/docs/documentation/server_admin/topics/authentication/password-policies.adoc b/docs/documentation/server_admin/topics/authentication/password-policies.adoc index e7cc968e7364..7398a33e2a1b 100644 --- a/docs/documentation/server_admin/topics/authentication/password-policies.adoc +++ b/docs/documentation/server_admin/topics/authentication/password-policies.adoc @@ -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=+` 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+`. diff --git a/docs/guides/securing-apps/client-registration.adoc b/docs/guides/securing-apps/client-registration.adoc index 3a143594b572..cf49e6aef01a 100644 --- a/docs/guides/securing-apps/client-registration.adoc +++ b/docs/guides/securing-apps/client-registration.adoc @@ -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. @@ -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. From 701a906a5e0bf2aeb31fde48e85649880136ebcc Mon Sep 17 00:00:00 2001 From: adityaanikam Date: Wed, 12 Aug 2026 15:31:57 +0530 Subject: [PATCH 2/2] Restore closing WARNING block delimiter dropped during rebase conflict resolution --- .../server_admin/topics/authentication/kerberos.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/documentation/server_admin/topics/authentication/kerberos.adoc b/docs/documentation/server_admin/topics/authentication/kerberos.adoc index ca702c17e785..9038ecb3e2ae 100644 --- a/docs/documentation/server_admin/topics/authentication/kerberos.adoc +++ b/docs/documentation/server_admin/topics/authentication/kerberos.adoc @@ -19,6 +19,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 an allowlist of hosts. +==== Perform the following steps to set up Kerberos authentication: