Update documentation about support of direct JWKS with JWT

Author: Rishav Kumar

_security/authentication-backends/jwt.md

@@ -227,25 +227,108 @@ Validating the signature of the signed JWT is the last step in granting user acc
 
 Rather than store the cryptographic key used for validation in the local `config.yml` file's `authc` section, you can specify a JSON Web Key Set (JWKS) endpoint to retrieve the key from its location on the issuer's server. This method of validating the JWT can help streamline management of public keys and certificates.
 
-In OpenSearch, this method of validation makes use of the [OpenID Connect authentication domain configuration]({{site.url}}{{site.baseurl}}/security/authentication-backends/openid-connect/#configure-openid-connect-integration). To specify the JWKS endpoint, replace the `openid_connect_url` setting in the configuration with the `jwks_uri` setting and add the URL to the setting as its value. This is shown in the following example:
+Starting with OpenSearch 3.3, JWT authentication now supports JWKS endpoints directly.
+
+### Direct JWKS support with JWT authentication
+
+You can now configure JWKS endpoints directly in the JWT authentication domain. This approach provides enhanced security through automated key rotation and dynamic key management.
 
 ```yml
-openid_auth_domain:
+jwt_auth_domain:
+  description: "Authenticate via JSON Web Token"
   http_enabled: true
   transport_enabled: true
   order: 0
   http_authenticator:
-    type: openid # use the OpenID Connect domain, since JWT is part of this authentication.
+    type: jwt
     challenge: false
     config:
-      subject_key: preferred_username
-      roles_key: roles
-      jwks_uri: https://keycloak.example.com:8080/auth/realms/master/.well-known/jwks-keys.json
+      jwks_uri: "https://example.com/.well-known/jwks.json"
+      signing_key: null  # Not used when jwks_uri is specified
+      jwt_header: "Authorization"
+      jwt_url_parameter: null
+      jwt_clock_skew_tolerance_seconds: 30
+      roles_key: "roles"
+      subject_key: "sub"
   authentication_backend:
     type: noop
 ```
 
-The endpoint should be documented by the JWT issuer. You can use it to retrieve the keys needed to validate the signed JWT. For more information about the content and format of JSON Web Keys, see [JSON Web Key (JWK) format](https://datatracker.ietf.org/doc/html/rfc7517#section-4).
+### JWKS configuration parameters
+
+The following table describes the JWKS-specific configuration parameters:
+
+Name | Description | Default
+:--- | :--- | :---
+`jwks_uri` | The JWKS endpoint URL. When specified, `signing_key` is ignored and keys are retrieved from this endpoint. | `null`
+
+### (Advanced) Security protection
+
+To help protect against denial-of-service (DoS) attacks and ensure secure JWKS operations, the Security plugin provides several protective measures including request limits, timeouts, and response size restrictions.
+
+Name | Description | Default
+:--- | :--- | :---
+`max_jwks_keys` | Maximum number of keys to process from the JWKS response. Set to `-1` for no limits. | `-1`
+`jwks_request_timeout_ms` | Maximum time in milliseconds allowed for a single HTTP request to the JWKS endpoint. | `5000`
+`jwks_queued_thread_timeout_ms` | Maximum time in milliseconds a request can wait in the queue before processing. | `2500`
+`max_jwks_response_size_bytes` | Maximum size in bytes for JWKS endpoint responses. | `1048576` (1MB)
+`refresh_rate_limit_count` | Maximum number of JWKS refresh requests allowed within the time window. | `10`
+`refresh_rate_limit_time_window_ms` | Time window in milliseconds for rate limiting JWKS refresh requests. | `10000` (10 seconds)
+
+### JWT header with Key ID
+
+When using JWKS, your JWT header must include a Key ID (`kid`) that identifies which specific key to use for verification:
+
+```json
+{
+  "alg": "RS256",
+  "typ": "JWT",
+  "kid": "V-diposfUJIk5jDBFi_QRouiVinG5PowskcSWy5EuCo"
+}
+```
+
+The `kid` parameter is required when using JWKS endpoints and must match a key identifier in the JWKS response.
+
+### Sample JWKS response
+
+The JWKS endpoint should return a JSON object containing an array of public keys. Each key must include metadata such as the key type (`kty`), usage (`use`), key ID (`kid`), and algorithm (`alg`):
+
+```json
+{
+  "keys": [
+    {
+      "kty": "RSA",
+      "use": "sig",
+      "kid": "V-diposfUJIk5jDBFi_QRouiVinG5PowskcSWy5EuCo",
+      "alg": "RS256",
+      "n": "nCJ9ve8zRv_4pdSja5i_8GgozoVZrUocD6UnMyQmh6fRBZWspoIRSGdTjcKktevnKWXlg7mqe7FIx6CdVqR5rVfM0o61_7cgxJqdNdnCXsFR8_S_98qMIJ-gxmlwE2a1X1VrCSmYh60APUGoGypm0sAsjvYTzU04LTN7K0Gip3H5qpkFD-Mxlev75WeC8WrvsfUFl6XN1h55HZW2wlYJGmbFVQx5839d8o6BxDVvQrGdN8MzLRFTMG8wiPhVDQL5NHt3vKgDnD6zT0c_S5Kz42i4bcktRRoAbR3LjDn5YbAatmfKzwOuL0XsbEnn-kgnt2aJ5GCaggukY3mMc-Bhew",
+      "e": "AQAB"
+    }
+  ]
+}
+```
+
+### Caching and performance
+
+JWKS responses are cached to optimize performance:
+
+- **Initial cache**: When JWKS is enabled, the system caches the JWKS endpoint response
+- **Cache refresh triggers**: 
+  - When a JWT contains a `kid` not found in the cache
+  - When cache entries expire based on HTTP cache headers
+  - During background refresh cycles
+- **Rate limiting**: Prevents excessive requests to the JWKS endpoint (10 requests per 10-second window by default)
+
+### Backward compatibility
+
+The JWKS feature maintains full backward compatibility:
+
+- When `jwks_uri` is not specified or set to `null`, the system uses the existing static `signing_key` mechanism
+- Existing JWT configurations continue to work without modification
+- You can switch between static keys and JWKS by updating the configuration
+- When both `jwks_uri` and `signing_key` are configured, `jwks_uri` takes precedence and `signing_key` is ignored
+
+For more information about the content and format of JSON Web Keys, see [JSON Web Key (JWK) format](https://datatracker.ietf.org/doc/html/rfc7517#section-4).
 
 
 ## Troubleshooting common issues