Skip to content

KNOX-3603: Refuse delegated tokens at the KnoxIDF client token endpoints - #1533

Merged
smolnar82 merged 1 commit into
apache:masterfrom
smolnar82:KNOX-3603
Nov 20, 2026
Merged

smolnar82 merged 1 commit into
apache:masterfrom
smolnar82:KNOX-3603

Conversation

@smolnar82

Copy link
Copy Markdown
Contributor

KNOX-3603 - KnoxIDF: Refuse delegated tokens at client revocation and enable/disable

What changes were proposed in this pull request?

KNOX-3600 refuses a delegated token (RFC 8693 act claim, an ActorChainPrincipal on the subject) at /knoxidf/api/v1/client/register. The other /client endpoints RegistrationResource inherits from TokenResource had no such check. They authorize the caller's effective principal, which for a delegated token is the user it acts for, and accept a bare token id. So whoever holds a user's delegated token could list that user's tokens and revoke, disable or re-enable any of them whose id it knows.

  • RegistrationResource overrides getUserTokens, revoke, revokeTokens, enable, enableTokens, disable and disableTokens. A delegated caller gets 403 access_denied ("A delegated token cannot list/revoke/enable/disable tokens.") before the parent runs, audited as authorization|…|failure|event=client_<token_listing|revocation|enablement|disablement> reason=delegated_caller_denied. Other callers reach the inherited implementation unchanged.
  • The existing knoxidf.client.registration.delegated.callers.denied (default true) now controls these endpoints too, so one switch decides whether delegated tokens may manage clients. false restores the previous behaviour.
  • Only the actor chain is checked, as in KNOX-3600: Shiro/LDAP callers, passcodes and non-delegated JWTs are unaffected.
  • Docs: configuration.md and security.md.

How was this patch tested?

Unit tests: new RegistrationResourceDelegatedTokenAccessGuardTest (13 tests). A delegated caller is refused with access_denied at all 7 endpoints, and a strict TokenStateService mock verifies the token state is untouched. With the param set to false, and for a non-delegated caller, revoke, disable and getUserTokens reach the parent and return 200. All 299 gateway-service-knoxidf tests pass, and mvn verify (checkstyle, PMD) is clean.

Manual test on a local gateway, on two delegated-token paths. In both, the test first registers two clients C1 and C2 owned by the user, then calls getUserTokens, disable/enable C1, disableTokens/enableTokens C2, revoke C1 and revokeTokens C2, first with the delegated token, then with a non-delegated token of the same user. The knoxidf-auth-clientregistration topology (JWTProvider, lowercase principal mapping, thirdPartyApp=true, knoxidf.client.registration.delegated.callers.denied=true) serves /client. A test-only PathAcls rule opens /knoxidf/api/v1/client/* there, so the requests reach RegistrationResource instead of being stopped by the existing register-only ACL.

RFC 8693 on-behalf-of token. knoxidf-tokenexchange (delegation.server.enabled=true, knoxidf.knox.token.enable.delegated.auth=true, passthrough audience validator) exchanges admin's KNOXSSO token with guest's as the actor, under a delegation policy (guest may act for admin at audience knoxidf) set at knoxidf-admin. The registration topology trusts that issuer. The same-subject exchange of admin's token is the non-delegated control.

1. delegation policy: guest may act for admin at audience knoxidf (upsert at knoxidf-admin)
  HTTP 201
2. KNOXSSO tokens for admin (subject) and guest (actor)
3. admin's same-subject exchange at knoxidf-tokenexchange (no act)
{"iss":"http://knox.knox.svc.cluster.local:8443/gateway/knox-knoxidf-tokenexchange","sub":"admin","aud":null,"act":null}
4. OBO exchange at knoxidf-tokenexchange: subject admin, actor guest
{"iss":"http://knox.knox.svc.cluster.local:8443/gateway/knox-knoxidf-tokenexchange","sub":"admin","aud":"knoxidf","act":{"sub":"guest"}}
5. the OBO token registers a client (expect 403 access_denied)
{
  "error_description" : "A delegated token cannot register a client.",
  "error" : "access_denied"
}
HTTP 403
6. the same-subject token registers clients C1 and C2 (expect 200)
  C1=e2e35d79-46a4-4b48-a890-dc5beff80a1c C2=adabc6da-7fa3-4b2b-ae53-6fbaff80b2aa
7. the OBO token on admin's clients (expect 403 access_denied for each)
 getUserTokens
  HTTP 403  {  "error_description" : "A delegated token cannot list tokens.",  "error" : "access_denied"}
 disable C1
  HTTP 403  {  "error_description" : "A delegated token cannot disable tokens.",  "error" : "access_denied"}
 enable C1
  HTTP 403  {  "error_description" : "A delegated token cannot enable tokens.",  "error" : "access_denied"}
 disableTokens
  HTTP 403  {  "error_description" : "A delegated token cannot disable tokens.",  "error" : "access_denied"}
 enableTokens
  HTTP 403  {  "error_description" : "A delegated token cannot enable tokens.",  "error" : "access_denied"}
 revoke C1
  HTTP 403  {  "error_description" : "A delegated token cannot revoke tokens.",  "error" : "access_denied"}
 revokeTokens
  HTTP 403  {  "error_description" : "A delegated token cannot revoke tokens.",  "error" : "access_denied"}
8. the same-subject token on the same clients (expect 200 for each)
 getUserTokens
  HTTP 200  {"tokens":[{"tokenId":"21ae695d-db93-4882-a597-53f44a4357bf","issueTime":"2026-11-20T00:40:49.678+0100","expiration":"Never","maxLifetime":"
 disable C1
  HTTP 200  {  "setEnabledFlag": "true",  "isEnabled": "false"}
 enable C1
  HTTP 200  {  "setEnabledFlag": "true",  "isEnabled": "true"}
 disableTokens
  HTTP 200  {  "setEnabledFlag": "true",  "isEnabled": "false"}
 enableTokens
  HTTP 200  {  "setEnabledFlag": "true",  "isEnabled": "true"}
 revoke C1
  HTTP 200  {  "revoked": "true"}
 revokeTokens
  HTTP 200  {  "revoked": "true"}

Impersonation token with act. The test-only delegation topology from KNOX-3600 (doAs impersonation for guest, KNOXTOKEN with knox.token.enable.delegated.auth=true) mints a KNOXSSO token for admin with act.sub=guest. Steps 1–5 are the KNOX-3600 registration checks; admin's KNOXSSO token registers C1 and C2 and is the control.

4. guest gets a token for admin at delegation (doAs=admin, act.sub=guest)
{"iss":"KNOXSSO","sub":"admin","act":{"sub":"guest"}}
5. the delegated token registers a client (expect 403 access_denied unless delegated callers are allowed)
{
  "error_description" : "A delegated token cannot register a client.",
  "error" : "access_denied"
}
HTTP 403
6. admin's KNOXSSO token registers clients C1 and C2, admin's own tokens (expect 200)
  C1=d8d6a6e6-3e15-4e77-b5ee-d885b8514313 C2=f4730bd0-db23-41c6-9f7b-88a1b43538c0
7. the delegated token (sub=admin) on admin's clients (expect 403 access_denied for each)
 getUserTokens
  HTTP 403  {  "error_description" : "A delegated token cannot list tokens.",  "error" : "access_denied"}
 disable C1
  HTTP 403  {  "error_description" : "A delegated token cannot disable tokens.",  "error" : "access_denied"}
 enable C1
  HTTP 403  {  "error_description" : "A delegated token cannot enable tokens.",  "error" : "access_denied"}
 disableTokens
  HTTP 403  {  "error_description" : "A delegated token cannot disable tokens.",  "error" : "access_denied"}
 enableTokens
  HTTP 403  {  "error_description" : "A delegated token cannot enable tokens.",  "error" : "access_denied"}
 revoke C1
  HTTP 403  {  "error_description" : "A delegated token cannot revoke tokens.",  "error" : "access_denied"}
 revokeTokens
  HTTP 403  {  "error_description" : "A delegated token cannot revoke tokens.",  "error" : "access_denied"}
8. admin's own token on the same clients (expect 200 for each: the refusals above changed nothing)
 getUserTokens
  HTTP 200  {"tokens":[{"tokenId":"21ae695d-db93-4882-a597-53f44a4357bf","issueTime":"2026-11-20T00:40:49.678+0100","expiration":"Never","maxLifetime":"
 disable C1
  HTTP 200  {  "setEnabledFlag": "true",  "isEnabled": "false"}
 enable C1
  HTTP 200  {  "setEnabledFlag": "true",  "isEnabled": "true"}
 disableTokens
  HTTP 200  {  "setEnabledFlag": "true",  "isEnabled": "false"}
 enableTokens
  HTTP 200  {  "setEnabledFlag": "true",  "isEnabled": "true"}
 revoke C1
  HTTP 200  {  "revoked": "true"}
 revokeTokens
  HTTP 200  {  "revoked": "true"}

Each refusal is in the audit log, e.g.:

|KNOXIDF|admin|||authorization|principal|admin|failure|event=client_enablement reason=delegated_caller_denied
|KNOXIDF|admin|||authorization|principal|admin|failure|event=client_revocation reason=delegated_caller_denied

The KNOX-3600 client-caller check is unaffected: with knoxidf.client.registration.client.callers.denied unset, a registered client's own token still gets 403 "A registered client cannot register another client.".

Integration Tests

Two new tests in test_delegation.py, which already sets up delegation policies and RFC 8693 exchanges. Both use a token delegated to recursiveUser acting for tom (sub=tom, act.sub=recursiveUser) from knoxidf-token-delegation-policy.

  • test_delegated_token_refused_at_client_endpoints, on knoxidf-token-delegation-policy (default, delegated callers refused): tom's own token registers two clients. The delegated token gets 403 access_denied at register and at all 7 token endpoints, each with its verb in the message. Each refusal leaves one authorization failure audit record with the right event and reason=delegated_caller_denied, matched by an audit_marker query parameter as in the KNOX-3568 tests. tom's own token then gets 200 at all 7, so the 403s come from the delegated check.
  • test_delegated_token_reaches_client_endpoints_when_allowed, on the new knoxidf-client-delegated-allowed topology (JWTProvider, server-managed, KNOXIDF with knoxidf.client.registration.delegated.callers.denied=false): the same delegated token registers two clients and gets 200 at all 7 endpoints.
tests-1  | Your code has been rated at 10.00/10
tests-1  | 
tests-1  | Waiting for knox...
tests-1  | ============================= test session starts ==============================
tests-1  | platform linux -- Python 3.10.20, pytest-9.0.3, pluggy-1.7.0
tests-1  | rootdir: /tests
tests-1  | plugins: platformdirs-4.12.4
tests-1  | collected 164 items
tests-1  | 
tests-1  | test_clientid_credentials.py .......                                     [  4%]
tests-1  | test_delegation.py ..............                                        [ 12%]
tests-1  | test_gateway_identity_cert.py ......                                     [ 16%]
tests-1  | test_health.py .....                                                     [ 19%]
tests-1  | test_k8s_delegation.py ........                                          [ 24%]
tests-1  | test_k8s_jwks_ca.py ...........                                          [ 31%]
tests-1  | test_k8s_serviceaccount_validation.py ......                             [ 34%]
tests-1  | test_knox_admin_path_traversal.py ...                                    [ 36%]
tests-1  | test_knox_auth_service_and_ldap.py ...                                   [ 38%]
tests-1  | test_knox_configs.py .                                                   [ 39%]
tests-1  | test_knox_ldap_backend_password_alias_retry.py ..                        [ 40%]
tests-1  | test_knox_ldap_cache.py ...                                              [ 42%]
tests-1  | test_knox_ldap_injection.py .......                                      [ 46%]
tests-1  | test_knox_ldap_proxy_search.py ...............                           [ 55%]
tests-1  | test_knoxauth_preauth_and_paths.py ......                                [ 59%]
tests-1  | test_knoxauth_token_forwarding.py ...........                            [ 65%]
tests-1  | test_knoxidf.py .......                                                  [ 70%]
tests-1  | test_knoxsso_redirect.py .                                               [ 70%]
tests-1  | test_knoxtoken_jwt.py ....................                               [ 82%]
tests-1  | test_remote_auth.py ...                                                  [ 84%]
tests-1  | test_remoteauth_extauthz_additional_path.py ....                         [ 87%]
tests-1  | test_token_exchange.py .................                                 [ 97%]
tests-1  | test_token_limit_by_type.py ....                                         [100%]
tests-1  | 
tests-1  | =============================== warnings summary ===============================
...
tests-1  | -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
tests-1  | ----------------- generated xml file: /tests/test-results.xml ------------------
tests-1  | ================= 164 passed, 142 warnings in 60.86s (0:01:00) =================
tests-1 exited with code 0

KNOX-3600 refuses a delegated token (act claim) at client registration.
RegistrationResource now also refuses it, with access_denied, at the
inherited getUserTokens, revoke, revokeTokens, enable, enableTokens,
disable and disableTokens endpoints, which authorize the user the token
acts for. knoxidf.client.registration.delegated.callers.denied (default
true) controls both checks.
@github-actions

Copy link
Copy Markdown

Test Results

  5 files    5 suites   1m 17s ⏱️
229 tests 228 ✅ 1 💤 0 ❌
294 runs  293 ✅ 1 💤 0 ❌

Results for commit 7630ce6.

@lmccay lmccay 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.

+1

@smolnar82
smolnar82 merged commit 48c3fe1 into apache:master Nov 20, 2026
3 checks passed
@smolnar82
smolnar82 deleted the KNOX-3603 branch November 20, 2026 20:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants