Usage of JWKS with JWT (without using OpenID connect)

[Rishav9852Kumar]

Description

This PR implements direct JWKS (JSON Web Key Set) support in the JWT authentication backend by adding a new HTTPJwtKeyByJWKSAuthenticator class. This enables JWT authentication with JWKS endpoints without requiring OIDC infrastructure coupling.

• Category: Enhancement

Why these changes are required?

JWKS support currently exists only through the HTTPJwtKeyByOpenIdConnectAuthenticator which requires OIDC discovery (openid_connect_url). This creates unnecessary coupling between JWT authentication and OIDC infrastructure. This enhancement addresses:

• Decoupling from OIDC: Enables direct JWKS usage without OpenID Connect discovery dependency
• Architectural Separation: Moves JWKS functionality to the JWT backend where it logically belongs
• Simplified Configuration: Eliminates need for openid_connect_url when only JWKS is required
• Use Case Support: Enables scenarios where JWKS endpoints exist without full OIDC infrastructure

What is the old behavior before changes and new behavior after changes?

Old Behavior:

• JWKS only available via jwt-key-by-oidc type (OIDC authenticator)
• Required openid_connect_url for OIDC discovery OR jwks_uri through OIDC backend
• Two-step process: OIDC discovery → JWKS retrieval (even when discovery wasn't needed)
• JWT + JWKS forced coupling with OIDC authentication backend

New Behavior:

• Single-step process: Direct JWKS endpoint access with jwks_uri in jwt_auth_domain config
• New handler for JWT with JWKS does not affect the existing Static JWT handler flow
• Clean separation: JWT authentication independent of OIDC infrastructure
• Backward compatibility: Existing OIDC-based configurations continue working

Issues Resolved

#4974

Implementation Details

• HTTPJwtKeyByJWKSAuthenticator: New authenticator extending AbstractHTTPJwtAuthenticator

• Configuration parameters:

  • jwks_uri: JWKS endpoint URL (required)
  • cache_jwks_endpoint: Enable caching (default: true)
  • jwks_request_timeout_ms: HTTP timeout (default: 5000ms)
  • jwks_queued_thread_timeout_ms: Thread timeout (default: 2500ms)
  • Rate limiting controls for refresh operations

Architecture:

• Leverages existing AbstractHTTPJwtAuthenticator infrastructure
• Reuses KeyProvider interface and SelfRefreshingKeySet for consistency
• Uses same kid-based key selection as OIDC authenticator
• Maintains identical JWT verification flow

Key Features:

• Caching: HTTP-based caching with configurable limits (10 entries, 1MB max)
• Rate Limiting: Prevents excessive refresh attempts (10 attempts per 10-second window)
• Error Handling: Graceful degradation when JWKS endpoint unavailable
• SSL Support: Configurable SSL settings for JWKS endpoints

Testing

Unit Tests added

Added in KeySetRetrieverTest.java

Added in HTTPJwtKeyByJWKSAuthenticatorTest.java

ref : https://github.com/Rishav9852Kumar/sample/blob/main/Steps%20to%20validate%20JWT%20auth%20using%20JWKS%20endpoint.pdf

Check List

• New functionality includes testing
• New functionality has been documented
• New Roles/Permissions have a corresponding security dashboards plugin PR
• API changes companion pull request created
• Commits are signed per the DCO using --signoff

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[codecov]

Codecov Report

❌ Patch coverage is 86.31579% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.99%. Comparing base (e8a82af) to head (9845012).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...urity/auth/http/jwt/keybyoidc/KeySetRetriever.java	83.67%	6 Missing and 2 partials ⚠️
.../security/auth/http/jwt/keybyoidc/JwtVerifier.java	0.00%	4 Missing ⚠️
...p/jwt/keybyjwks/HTTPJwtKeyByJWKSAuthenticator.java	97.56%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5578      +/-   ##
==========================================
+ Coverage   72.85%   72.99%   +0.14%     
==========================================
  Files         413      414       +1     
  Lines       25758    25840      +82     
  Branches     3917     3933      +16     
==========================================
+ Hits        18767    18863      +96     
+ Misses       5073     5063      -10     
+ Partials     1918     1914       -4     

Files with missing lines	Coverage Δ
...arch/security/securityconf/DynamicConfigModel.java	100.00% <100.00%> (ø)
...p/jwt/keybyjwks/HTTPJwtKeyByJWKSAuthenticator.java	97.56% <97.56%> (ø)
.../security/auth/http/jwt/keybyoidc/JwtVerifier.java	77.19% <0.00%> (-2.81%)	⬇️
...urity/auth/http/jwt/keybyoidc/KeySetRetriever.java	85.41% <83.67%> (+6.36%)	⬆️

... and 12 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cwperks]

@Rishav9852Kumar Thank you for this thorough PR with associated documentation on testing. Left a few comments, but mostly looks good and well documented in the code.