Skip to content

KNOX-3423: Switch to JSON error messages in Knox token validation paths - #1354

Merged
hanicz merged 2 commits into
apache:masterfrom
hanicz:KNOX-3423
Aug 31, 2026
Merged

KNOX-3423: Switch to JSON error messages in Knox token validation paths#1354
hanicz merged 2 commits into
apache:masterfrom
hanicz:KNOX-3423

Conversation

@hanicz

@hanicz hanicz commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

KNOX-3423 - Switch to JSON error messages in Knox token validation paths

What changes were proposed in this pull request?

RFC 8693 §2.2.2 / RFC 6749 §5.2 require OAuth token-exchange errors to be a JSON
body ({"error", "error_description"}) with Content-Type: application/json.
JWTFederationFilter previously emitted plain-text/HTML (sendError) for every
path, breaking standards-compliant clients.

  • Errors raised while handling a token-exchange request now return the RFC JSON
    body with Cache-Control: no-store / Pragma: no-cache. HTTP status codes are
    unchanged (400 for param/nbf/audience, 401 for signature/expiry/parse).
  • Scope is the whole exchange path, keyed off the existing
    TOKEN_EXCHANGE_REQUEST_ATTR: both the direct param/parse errors in
    TokenExchangeHandler and the shared JWT-validation errors emitted by
    AbstractJWTFilter (expired / bad-signature / wrong-audience / …). The latter is
    the gap a handler-only fix would miss.
  • The normal bearer auth path and the SSO-cookie path are untouched — still
    plain text.

How was this patch tested?

Unit tests, local tests

curl -skiv -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  'https://localhost:8443/gateway/knoxidf/knoxidf/api/v1/token'

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8
{"error":"invalid_request","error_description":"the subject_token parameter is required"}

curl -skiv -H 'Authorization: Bearer not-a-real-jwt' \
  'https://localhost:8443/gateway/tokenconsumer/auth/api/v1/pre'

Content-Type: text/html;charset=iso-8859-1
<body><h2>HTTP ERROR 401 Bad request: missing token passcode.</h2>

curl -skiv -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token=abc&subject_token_type=urn:ietf:params:oauth:token-type:saml2' \
  'https://localhost:8443/gateway/tokenconsumer/auth/api/v1/pre'

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8
{"error":"unsupported_token_type","error_description":"unsupported subject_token_type urn:ietf:params:oauth:token-type:saml2"}

Integration Tests

N/A

UI changes

N/A

@github-actions

github-actions Bot commented Aug 21, 2026 •
edited
Loading

Copy link
Copy Markdown

Test Results

 4 files   4 suites   10s ⏱️
69 tests 69 ✅ 0 💤 0 ❌
80 runs  80 ✅ 0 💤 0 ❌

Results for commit dc91bf3.

♻️ This comment has been updated with latest results.

hsheinblatt
hsheinblatt approved these changes Aug 25, 2026
View reviewed changes

@hsheinblatt hsheinblatt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Tamás. LGTM. I think a couple of the error types might be incorrect, and there may be a missing test -- see comments -- but looks to make it spec compliant.

Comment thread ...st/java/org/apache/knox/gateway/provider/federation/jwt/filter/TokenExchangeHandlerTest.java Outdated
Comment thread ...c/main/java/org/apache/knox/gateway/provider/federation/jwt/filter/TokenExchangeHandler.java Outdated
Comment thread ...st/java/org/apache/knox/gateway/provider/federation/jwt/filter/TokenExchangeHandlerTest.java Outdated
Comment thread ...st/java/org/apache/knox/gateway/provider/federation/jwt/filter/TokenExchangeHandlerTest.java
Comment thread ...t/java/org/apache/knox/gateway/provider/federation/JWTFederationFilterTokenExchangeTest.java
Comment thread ...t/java/org/apache/knox/gateway/provider/federation/JWTFederationFilterTokenExchangeTest.java
@hsheinblatt hsheinblatt mentioned this pull request Aug 25, 2026
Merged
@hanicz

hanicz commented Aug 26, 2026

Copy link
Copy Markdown
Contributor Author

Thanks Tamás. LGTM. I think a couple of the error types might be incorrect, and there may be a missing test -- see comments -- but looks to make it spec compliant.

I made some changes to address your comments.

TokenExchangeHandler: I switched unsupported_token_type to invalid_request. Catch block emits invalid_request as well now.
TokenExchangeHandlerTest: Added the missing test for the catch block.

As per RFC 8693 §2.2.2: If the request itself is not valid or if either the subject_token or actor_token are invalid for any reason, or are unacceptable based on policy, the authorization server MUST construct an error response, as specified in Section 5.2 of [RFC6749]. The value of the error parameter MUST be the invalid_request error code.

Due to the above JWTFederationFilter will send invalid_request for nbf/audience expiry/signature/parse. invalid_grant remains in KnoxIDF authorization/refresh_token grant paths

@hanicz hanicz changed the title KNOX-3424: Switch to JSON error messages in Knox token validation paths KNOX-3423: Switch to JSON error messages in Knox token validation paths Aug 28, 2026
@hanicz
hanicz merged commit 1832299 into apache:master Aug 31, 2026
3 checks passed
@smolnar82 smolnar82 mentioned this pull request Sep 2, 2026
Merged
smolnar82 added a commit to smolnar82/knox that referenced this pull request Sep 3, 2026
@smolnar82 @claude
KNOX-3424: JSON-escape the caller-supplied resource value in the toke…
7cd3b66 
…n error body

The token-issuance error for a rejected resource/audience echoed the
caller-supplied resource value back inside a hand-concatenated JSON body,
so a value containing a double quote (or other JSON metacharacter) could
break out of the JSON string and corrupt the response.

Render the {"error": ..., "code": ...} body through JsonUtils instead of
string concatenation, which escapes the embedded value the same way the
KNOX-3423 (apache#1354) filter-layer error path does. The {error, code} shape
and ErrorCode contract used by the token lifecycle responses are kept.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@smolnar82 smolnar82 smolnar82 approved these changes
@moresandeep moresandeep Awaiting requested review from moresandeep
@pzampino pzampino Awaiting requested review from pzampino
@bonampak bonampak Awaiting requested review from bonampak
+1 more reviewer
@hsheinblatt hsheinblatt hsheinblatt approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

test-federation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@hanicz @hsheinblatt @smolnar82