From 930e30c51600fc9ec4c68714f3296c62d51d84e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Tue, 28 Apr 2026 10:44:11 +0200 Subject: [PATCH 1/6] Fix JWT Authentication Plugin documentation regarding blockUnknown default value --- .../pages/jwt-authentication-plugin.adoc | 13 +++++++++---- .../pages/major-changes-in-solr-9.adoc | 7 +++++++ 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/jwt-authentication-plugin.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/jwt-authentication-plugin.adoc index 4a5094f6225..311fd2c893f 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/jwt-authentication-plugin.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/jwt-authentication-plugin.adoc @@ -42,9 +42,14 @@ The simplest possible `security.json` for registering the plugin without configu } ---- -The plugin will by default require a valid JWT token for all traffic. +[WARNING] +==== +Earlier versions of this documentation incorrectly stated that `blockUnknown` defaulted to `true`. The actual default is `false`, meaning requests without a JWT token are passed through unauthenticated. If you intend to require authentication for all requests, you must explicitly set `"blockUnknown": true` in your `security.json`. +==== + +By default, `blockUnknown` is `false`, so requests without a JWT token are passed through unauthenticated. -If the `blockUnknown` property is set to `false` as in the above example, it is possible to start configuring the plugin using unauthenticated REST API calls, which is further described in section <>. +With `blockUnknown` set to `false` (the default, as shown above), you can configure the plugin using unauthenticated REST API calls, which is further described in section <>. == Configuration Parameters @@ -52,7 +57,7 @@ If the `blockUnknown` property is set to `false` as in the above example, it is [%header,format=csv,separator=;,cols="25%,50%,25%"] |=== Key ; Description ; Default -blockUnknown ; Set to `false` to if you need to perform configuration through REST API or if you use an Authorization Plugin and only want certain paths protected. By default all requests will require a token ; `true` +blockUnknown ; Set to `true` to require a valid JWT token for all requests. Set to `false` (the default) to allow unauthenticated requests through — useful when configuring via REST API or when an Authorization Plugin handles path-based protection ; `false` realm ; Name of the authentication realm to echo back in HTTP 401 responses. Will also be displayed in Admin UI login page ; 'solr-jwt' scope ; Whitespace separated list of valid scopes. If configured, the JWT access token MUST contain a `scope` claim with at least one of the listed scopes. Example: `solr:read solr:admin` ; requireIss ; Fails requests that lacks an `iss` (issuer) claim ; `true` @@ -167,7 +172,7 @@ Let's look at a more complex configuration, this time with two issuers configure Let's comment on this config: <1> Plugin class -<2> Make sure to block anyone without a valid token (this is also the default) +<2> Explicitly block anyone without a valid token (the default is `false`, so this must be set explicitly to enforce authentication) <3> Fetch the user id from another claim than the default `sub` <4> Require that the `foo` claim is one of "A" or "B" and that the `dept` claim is "IT" <5> Require one of the scopes `solr:read`, `solr:write` or `solr:admin` diff --git a/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc b/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc index 37180f2d30f..9a3470de8ea 100644 --- a/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc +++ b/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc @@ -97,6 +97,13 @@ The project normally doesn't remove functionality in a minor release, but we mad +NOTE: The previous parse-context-based configuration (`parseContext.config`) is no longer supported. Tika parser-specific properties must now be configured directly on the Tika Server itself, rather than through Solr configuration. Please refer to the Tika Server documentation for details on how to set these properties. +=== JWT Authentication Plugin: `blockUnknown` documentation Corrected + +The `blockUnknown` configuration parameter of the xref:deployment-guide:jwt-authentication-plugin.adoc[JWT Authentication Plugin] defaults to `false`, meaning requests without a JWT token are passed through unauthenticated. +Previous versions of the reference guide incorrectly stated the default was `true`. + +* Users who relied on the (incorrectly documented) default of `true` should explicitly add `"blockUnknown": true` to their `authentication` block in `security.json` to preserve the intended behaviour. + == Solr 9.10 === SolrJ From 5170bcaadf9ce418d4d89dcb2a4b899eb20ab4b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Tue, 28 Apr 2026 10:48:14 +0200 Subject: [PATCH 2/6] Changelog entry --- .../SOLR-18216-jwt-blockUnknown-default-docs.yml | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 changelog/unreleased/SOLR-18216-jwt-blockUnknown-default-docs.yml diff --git a/changelog/unreleased/SOLR-18216-jwt-blockUnknown-default-docs.yml b/changelog/unreleased/SOLR-18216-jwt-blockUnknown-default-docs.yml new file mode 100644 index 00000000000..f63bc99b504 --- /dev/null +++ b/changelog/unreleased/SOLR-18216-jwt-blockUnknown-default-docs.yml @@ -0,0 +1,8 @@ +# See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc +title: "JWT Authentication Plugin: correct documentation of `blockUnknown` default value (`false`, not `true`). See upgrade notes in the reference guide for more" +type: fixed # added, changed, fixed, deprecated, removed, dependency_update, security, other +authors: + - name: Jan Høydahl +links: + - name: SOLR-18216 + url: https://issues.apache.org/jira/browse/SOLR-18216 From fdedfffd346d7888588b619c490379823dcbed95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Tue, 28 Apr 2026 10:57:49 +0200 Subject: [PATCH 3/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../modules/upgrade-notes/pages/major-changes-in-solr-9.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc b/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc index 9a3470de8ea..4326834d14b 100644 --- a/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc +++ b/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc @@ -97,7 +97,7 @@ The project normally doesn't remove functionality in a minor release, but we mad +NOTE: The previous parse-context-based configuration (`parseContext.config`) is no longer supported. Tika parser-specific properties must now be configured directly on the Tika Server itself, rather than through Solr configuration. Please refer to the Tika Server documentation for details on how to set these properties. -=== JWT Authentication Plugin: `blockUnknown` documentation Corrected +=== JWT Authentication Plugin: `blockUnknown` documentation corrected The `blockUnknown` configuration parameter of the xref:deployment-guide:jwt-authentication-plugin.adoc[JWT Authentication Plugin] defaults to `false`, meaning requests without a JWT token are passed through unauthenticated. Previous versions of the reference guide incorrectly stated the default was `true`. From f34aa7bb97e4a08000006d91d153a7bfdf41c25d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Tue, 28 Apr 2026 11:03:03 +0200 Subject: [PATCH 4/6] Correct 9.0 major-changes bullet that was incorrect. --- .../modules/upgrade-notes/pages/major-changes-in-solr-9.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc b/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc index 4326834d14b..a854d6012ca 100644 --- a/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc +++ b/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-9.adoc @@ -396,7 +396,7 @@ to switch back if needed. * Upgrade to Zookeeper 3.7, allowing for TLS protected ZK communication. * All request handlers support security permissions. Users may have to adapt their `security.json`. * Ability to disable admin UI through a system property. -* The property `blockUnknown` in the `BasicAuthPlugin` and the `JWTAuthPlugin` now defaults to `true` instead of `false`. This change is backward incompatible. If you need the pre-9.0 default behavior, you need to explicitly set `blockUnknown:false` in `security.json`. +* The property `blockUnknown` in the `BasicAuthPlugin` [.line-through]#and the `JWTAuthPlugin`# now defaults to `true` instead of `false`. This change is backward incompatible. If you need the pre-9.0 default behavior, you need to explicitly set `blockUnknown:false` in `security.json`. * Solr now runs with the Java security manager enabled by default. Hadoop users may need to disable this. * Solr now binds to localhost network interface by default for better out of the box security. Administrators that need Solr exposed more broadly can change the `SOLR_JETTY_HOST` property in their Solr include (`solr.in.sh`/`solr.in.cmd`) file. From 23c796f3b926489a983ef79fb4a607f26485bd40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Tue, 28 Apr 2026 11:04:46 +0200 Subject: [PATCH 5/6] Use boolean instead of string --- .../deployment-guide/pages/jwt-authentication-plugin.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/jwt-authentication-plugin.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/jwt-authentication-plugin.adoc index 311fd2c893f..9166a61a211 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/jwt-authentication-plugin.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/jwt-authentication-plugin.adoc @@ -37,7 +37,7 @@ The simplest possible `security.json` for registering the plugin without configu { "authentication": { "class":"solr.JWTAuthPlugin", - "blockUnknown":"false" + "blockUnknown": false } } ---- From 34bcd2bb4d8580076ef546c8ef4dec546ae63c1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Tue, 28 Apr 2026 11:05:52 +0200 Subject: [PATCH 6/6] Review comment on changelog --- .../unreleased/SOLR-18216-jwt-blockUnknown-default-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog/unreleased/SOLR-18216-jwt-blockUnknown-default-docs.yml b/changelog/unreleased/SOLR-18216-jwt-blockUnknown-default-docs.yml index f63bc99b504..a91ed3ec18b 100644 --- a/changelog/unreleased/SOLR-18216-jwt-blockUnknown-default-docs.yml +++ b/changelog/unreleased/SOLR-18216-jwt-blockUnknown-default-docs.yml @@ -1,5 +1,5 @@ # See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc -title: "JWT Authentication Plugin: correct documentation of `blockUnknown` default value (`false`, not `true`). See upgrade notes in the reference guide for more" +title: "JWT Authentication Plugin: correct documentation of `blockUnknown` default value (`false`, not `true`). See upgrade notes in the reference guide for more details." type: fixed # added, changed, fixed, deprecated, removed, dependency_update, security, other authors: - name: Jan Høydahl