Skip to content

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

Open
adityaanikam wants to merge 2 commits into
keycloak:mainfrom
adityaanikam:inclusive-terminology-51435
Open

Use inclusive terminology in docs (blacklist/whitelist -> denylist/allowlist)#51453
adityaanikam wants to merge 2 commits into
keycloak:mainfrom
adityaanikam:inclusive-terminology-51435

Conversation

@adityaanikam

@adityaanikam adityaanikam commented Aug 5, 2026

Copy link
Copy Markdown

Summary

Adopts inclusive terminology (denylist/allowlist) in place of blacklist/whitelist in user facing documentation prose, per

Closes #51435

Files changed

  • docs/documentation/server_admin/topics/authentication/kerberos.adoc
  • docs/documentation/server_admin/topics/authentication/password-policies.adoc
  • docs/guides/securing-apps/client-registration.adoc

Note: password-policies.adoc already used "denylist" in its "Pre computing the Bloom filter" section (the build-password-denylist CLI command). This PR brings the older "Password blacklist" section above it in line with that existing terminology, rather than introducing something new.

Deliberately out of scope

  • Real config identifiers: blacklistsPath, the passwordBlacklist SPI id, the keycloak.password.blacklists.path system property, and all --spi-password-policy--password-blacklist--* CLI flags. Renaming these would be a breaking change for existing deployments and needs its own deprecation path.
  • The default password-blacklists folder path (${kc.home.dir}/data/password-blacklists/), for the same reason.
  • docs/tests.md's --auth-server-whitelist flag - this is a Google Chrome command-line flag name, not Keycloak's own terminology, so changing it would make the doc inaccurate.
  • docs/documentation/release_notes/topics/26_6_0.adoc - a historical release note, left as a record of what shipped at the time.

Fixes #51435

Copilot AI balanced review requested due to automatic review settings August 5, 2026 09:46
@adityaanikam
adityaanikam requested a review from a team as a code owner August 5, 2026 09:46

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates user-facing documentation to use inclusive denylist/allowlist terminology while retaining compatibility-sensitive identifiers.

Changes:

  • Revises password policy terminology.
  • Updates client registration and Kerberos allowlist wording.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File Description
password-policies.adoc Updates password denylist documentation.
client-registration.adoc Replaces whitelist terminology.
kerberos.adoc Uses allowlist terminology for trusted hosts.
Suppressed comments (1)

docs/documentation/server_admin/topics/authentication/password-policies.adoc:142

  • The nested CLI instruction on line 144 still says “blacklist folder.” That phrase is user-facing prose rather than an immutable identifier, so leaving it unchanged makes this terminology update incomplete.
* Denylist files resolve against `+${kc.home.dir}/data/password-blacklists/+` by default. Customize this path using:

Comment on lines +136 to +137
===== Password denylist
Password must not be in a denylist file.

* 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 - Allow to allowlist `Client Scopes`, which can be used with newly registered or updated clients.
Copilot AI review requested due to automatic review settings August 5, 2026 14:48
@adityaanikam
adityaanikam force-pushed the inclusive-terminology-51435 branch from 74abc40 to 1b10e04 Compare August 5, 2026 14:48

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/guides/securing-apps/client-registration.adoc:228

  • This still describes the defaults inaccurately: allow-default-scopes defaults to true and permits both realm default and realm optional client scopes (see ClientScopesClientRegistrationPolicy.java:128-132). Distinguish the empty explicit allowlist from the scopes that are implicitly allowed.
There are no allowlisted scopes by default; only the client scopes, which are defined as `Realm Default Client Scopes` are allowlisted by default.

docs/documentation/server_admin/topics/authentication/password-policies.adoc:144

  • The sample value blacklistsFolder is not a compatibility-sensitive identifier, so it unnecessarily retains the excluded terminology despite this PR's stated documentation update. Rename only this arbitrary path value while preserving the real property and CLI flag names.
** 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+`.

…lowlist)

Fixes keycloak#51435

Signed-off-by: adityaanikam <adityanikam9502@gmail.com>
@adityaanikam
adityaanikam force-pushed the inclusive-terminology-51435 branch from 1b10e04 to 3220b49 Compare August 11, 2026 17:15
Copilot AI review requested due to automatic review settings August 11, 2026 17:15

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

docs/guides/securing-apps/client-registration.adoc:214

  • Line 214 lost the indentation it previously had as a wrapped continuation line. In AsciiDoc lists, wrapped lines are typically indented to remain part of the list item; without indentation, rendering can change (e.g., splitting into a separate paragraph). Restore the prior indentation for this wrapped line to keep list formatting consistent.
* 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 allowlisted host, so anonymous client registration is de-facto disabled.

docs/documentation/server_admin/topics/authentication/password-policies.adoc:151

  • Hyphenate the compound modifier: change 'memory efficient' to 'memory-efficient'.
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.

Comment on lines 19 to +21
[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.
Copilot AI review requested due to automatic review settings August 12, 2026 10:02

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt inclusive terminology: update 'blacklist'/'whitelist' to 'blocklist'/'allowlist'

3 participants