SOLR-18216 Fix documentation bug for jwt-auth blockUnkonwn

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

solr/solr-ref-guide/modules/deployment-guide/pages/jwt-authentication-plugin.adoc

@@ -37,22 +37,27 @@ 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
 
 //*TODO*: standard is not to put parameters in tables but use labeled lists instead
 [%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`

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.