Skip to content

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

Open
hanicz wants to merge 2 commits into
apache:masterfrom
hanicz:KNOX-3423
Open

KNOX-3424: Switch to JSON error messages in Knox token validation paths#1354
hanicz wants to merge 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   12s ⏱️
55 tests 55 ✅ 0 💤 0 ❌
66 runs  66 ✅ 0 💤 0 ❌

Results for commit a87272e.

♻️ 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
Open
@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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@moresandeep moresandeep Awaiting requested review from moresandeep
@pzampino pzampino Awaiting requested review from pzampino
@bonampak bonampak Awaiting requested review from bonampak
@smolnar82 smolnar82 Awaiting requested review from smolnar82
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.

2 participants

@hanicz @hsheinblatt