This is an automated email from the ASF dual-hosted git repository.
janhoy pushed a commit to branch branch_9x
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/branch_9x by this push:
new 85b85683353 SOLR-18216 Fix documentation bug for jwt-auth blockUnkonwn
(#4374)
85b85683353 is described below
commit 85b856833530c23316a482b2502a212719c3ca78
Author: Jan Høydahl <[email protected]>
AuthorDate: Wed Apr 29 09:38:26 2026 +0200
SOLR-18216 Fix documentation bug for jwt-auth blockUnkonwn (#4374)
Document the fact that the default for blockUnknown is 'false'.
---
.../SOLR-18216-jwt-blockUnknown-default-docs.yml | 8 ++++++++
.../deployment-guide/pages/jwt-authentication-plugin.adoc | 15 ++++++++++-----
.../upgrade-notes/pages/major-changes-in-solr-9.adoc | 9 ++++++++-
3 files changed, 26 insertions(+), 6 deletions(-)
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..a91ed3ec18b
--- /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 details."
+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
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..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,14 +37,19 @@ The simplest possible `security.json` for registering the
plugin without configu
{
"authentication": {
"class":"solr.JWTAuthPlugin",
- "blockUnknown":"false"
+ "blockUnknown": false
}
}
----
-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 <<Editing JWT Authentication
Plugin Configuration>>.
+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 <<Editing JWT Authentication Plugin Configuration>>.
== 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..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
@@ -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
@@ -389,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.
