Use inclusive terminology in docs (blacklist/whitelist -> denylist/allowlist) - #51453
Use inclusive terminology in docs (blacklist/whitelist -> denylist/allowlist)#51453adityaanikam wants to merge 2 commits into
Conversation
There was a problem hiding this comment.
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:
| ===== 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. |
74abc40 to
1b10e04
Compare
There was a problem hiding this comment.
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-scopesdefaults to true and permits both realm default and realm optional client scopes (seeClientScopesClientRegistrationPolicy.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
blacklistsFolderis 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>
1b10e04 to
3220b49
Compare
There was a problem hiding this comment.
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.
| [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. |
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.adocdocs/documentation/server_admin/topics/authentication/password-policies.adocdocs/guides/securing-apps/client-registration.adocNote:
password-policies.adocalready used "denylist" in its "Pre computing the Bloom filter" section (thebuild-password-denylistCLI 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
blacklistsPath, thepasswordBlacklistSPI id, thekeycloak.password.blacklists.pathsystem 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.password-blacklistsfolder path (${kc.home.dir}/data/password-blacklists/), for the same reason.docs/tests.md's--auth-server-whitelistflag - 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