SOLR-18233 Strengthen Basic Authentication password policy and harden template users created by bin/solr auth enable by janhoy · Pull Request #4477 · apache/solr

janhoy · 2026-05-29T21:49:11Z

https://issues.apache.org/jira/browse/SOLR-18233

Password policy (affects all Basic Auth installations): Solr's Basic Authentication has had minimal password requirements. While the Admin UI enforced a few rules, it still permitted passwords identical to the username (e.g. admin/admin). This change disallows username/password equality both at login and at account creation, via the API and Admin UI alike. As a side effect, any existing installation retaining the well-known template credentials will have those accounts silently disabled until the passwords are changed.

bin/solr auth enable cleanup: The command previously uploaded a bundled security.json template containing four undocumented accounts with weak default credentials. With this change:

The superadmin template account is removed from the bundled template
The remaining template accounts ship with no password set rather than a default one
The command will prompt the operator to set passwords for any template accounts at enable-time
Documentation for bin/solr auth enable is updated to clearly describe all accounts it creates

These changes collectively strengthen the security posture of both new and existing Solr installations using Basic Authentication.

Clean up bin/solr auth enable template accounts

epugh

Thanks for tackling this hard thing @janhoy!

…er.authenticate() username.equals(password) threw NPE when username was null. The previous code handled null usernames safely via credentials.get(null), so this was a regression introduced by the new equality check.

… and set-user Adds two test methods to TestSha256AuthenticationProvider: - testAuthenticateRejectsUsernameEqualPassword: verifies that authenticate() returns false when username==password even if the hash is stored - testSetUserRejectsUsernameEqualPassword: verifies that the set-user edit command rejects entries where username==password

If an operator runs 'bin/solr auth enable --credentials admin:admin' with --block-unknown (the default), the created account will never authenticate, immediately locking them out. Fail early with a clear error message instead.

…son top level The --block-unknown flag was writing blockUnknown to the top level of security.json, but Solr reads it from security.json.authentication.blockUnknown. This meant the option had no effect and the template's value (false) was always used, a security-relevant bug since operators believed auth was mandatory when it was not.

The bullet describing what 'bin/solr auth enable' does pointed to solr/core/resources/security.json (missing src/). The correct path is solr/core/src/resources/security.json, matching the link added earlier in the same section.

Copilot

Pull request overview

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

janhoy · 2026-06-01T07:43:55Z

@dsmiley @epugh Anyone of you ready to give a thumbs up? I'll backport to 10x, 9x and 9_11

epugh

LGTM! Thank you for tackling this.

epugh

err wait, i see a script test failing...

janhoy · 2026-06-05T00:24:09Z

err wait, i see a script test failing...

Yea, this was a tricky one. But I committed a fix, explained below:

The CI "Run Solr Script Tests" job was failing on test 89 (start solr with ssl and auth) in test_ssl.bats.

Root cause

The earlier commit in this PR correctly fixed AuthTool to place blockUnknown inside the authentication block (instead of erroneously at the top level of security.json). However, the old code also unconditionally set blockUnknown=true (the CLI default), which overrode the template's intentional blockUnknown=false.

On main, this override was harmless because it landed at the wrong JSON level and was ignored by BasicAuthPlugin. But once we fixed the placement, the override started taking effect — blocking unauthenticated requests and changing the 401 error message from "Authentication" (from the authorization layer) to "require authentication" (from BasicAuthPlugin), breaking the test assertion.

Fix

AuthTool no longer overrides blockUnknown unless the user explicitly passes --block-unknown. The template security.json already sets blockUnknown=false, which is the intended default — it allows unauthenticated pass-through for endpoints like health checks and metrics that are authorized via the authorization rules. If a user wants to block all unknown users, they can pass --block-unknown true explicitly.

Risk of newly identified bug

The previously unknown bug of AuthTool setting the wrong blockUnknown param could have been serious, had it not been for the fact that the security.json template that always is used, has a catch-all rule at the end of chain requiring "admin" role. The healthcheck and metric endpoints were open to the world, and if user specified --blockUnknown true they would still be open, as intended by the template.

…r blockUnknown

janhoy · 2026-06-05T08:00:51Z

I found a doc bug regarding default for --block-unknown cli flag which was documented as default true. While code default is true, the auth enable default is false due to the template. Here's what I did to clarify:

basic-authentication-plugin.adoc

Lead with bin/solr auth enable as the recommended way to enable basic auth (cloud mode), with a cross-reference to the control script reference
Manual security.json creation presented as the alternative rather than the only path

solr-control-script-reference.adoc

Added NOTE that bin/solr auth enable requires SolrCloud mode; for user-managed clusters, security.json must be placed on each node manually
Described the security.json as a "best-practice template with roles and permissions" rather than just "base file"
Fixed --block-unknown default from true to false — the BasicAuthPlugin code-default is true, but the installed template explicitly sets it to false because it includes a
RuleBasedAuthorizationPlugin that restricts all operations by role. Only health and metrics-read are open (for load balancers / monitoring). Pass --block-unknown true to lock those down too.

janhoy · 2026-06-05T08:04:54Z

 [%autowidth,frame=none]
 |===
-|Optional |Default: `true`
+|Optional |Default: `false` (via template)


Should the "Default" for this CLI option instead of true or false be something like

"Use value from security.json template (false)"

That would perhaps allow us to simplify the explanation in line 971-972 below?

i like... "via template" isn't obvious.

epugh

Great work!

janhoy added 2 commits May 28, 2026 20:07

SOLR-18268 Strengthen Basic Auth security: disallow username==password

a1d1133

Clean up bin/solr auth enable template accounts

Rename changelog

eb21a88

github-actions Bot added documentation Improvements or additions to documentation admin-ui cat:cli cat:security labels May 29, 2026

janhoy requested a review from Copilot May 29, 2026 21:49

Copilot started reviewing on behalf of janhoy May 29, 2026 21:49 View session

This comment was marked as resolved.

Sign in to view