feat(validator): parse and expose On-Behalf-Of Token Exchange claims (RFC 8693) - #407
feat(validator): parse and expose On-Behalf-Of Token Exchange claims (RFC 8693)#407developerkunal wants to merge 5 commits into
Conversation
…(RFC 8693) Add first-class validation support for tokens issued via On-Behalf-Of / Token Exchange (RFC 8693). RegisteredClaims now includes the act (actor) chain, azp, org_id, and org_name, populated automatically during validation. Add ValidatedClaims helpers CurrentActor(), DelegationChain(), and HasActor() that distinguish the current actor (for authorization, per RFC 8693 §4.1) from the informational delegation chain (for audit). Reject delegation chains deeper than 5 levels as malformed.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #407 +/- ##
==========================================
+ Coverage 94.42% 94.51% +0.08%
==========================================
Files 25 25
Lines 2154 2206 +52
==========================================
+ Hits 2034 2085 +51
- Misses 81 82 +1
Partials 39 39 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
The cnf claim is now extracted in extractSupplementaryClaims alongside act, azp, and the organization claims, so the standalone extractConfirmationClaim method is unused and flagged by the linter. Remove it and fold its cnf test coverage into the extractSupplementaryClaims tests.
| return payload.Cnf, nil | ||
| // Enforce the RFC 8693 delegation chain depth limit. Depth counts the | ||
| // number of nested actors; a chain deeper than the limit is malformed. | ||
| if actorChainDepth(payload.Act) > maxActorChainDepth { |
There was a problem hiding this comment.
This rejects any token whose act chain nests deeper than 5, at verification time. Two things :
The requirements say generic verification shouldn't fail because of the act claim, and the 5-level cap is described as something the authorization server enforces when it issues the token, not something the verifier re-checks. So a chain deep enough to trip this could only have come from a trusted issuer that already applies the limit.
Is the verifier-side rejection deliberate, or should we let the issuer own that limit? And if we do want to keep a ceiling, would a configurable option (defaulting to 5) sit better than a fixed constant?
There was a problem hiding this comment.
The original intent was a defensive backstop at verification time, but the 5-level cap is really the authorization server's responsibility at issuance, and a chain that deep could only have come from a trusted issuer that already applies the limit. Hardcoding it as a constant also gave callers no way to adjust it.
We made it configurable instead of removing it. WithMaxActorChainDepth defaults to 5 to match the Auth0 issuer limit, so callers who trust their issuer can raise it while the default keeps the check for everyone else. It is positive only and errors at construction for zero or negative values, matching the other options in this package.
There was a problem hiding this comment.
The configurable option helps, but I want to check the direction: the spec says 5 is the cap and the issuer enforces it, so what's the case for letting a caller set the limit above 5?
Lowering it to be stricter makes sense, but raising it seems to allow chains the spec says can't legitimately be issued. If the intent is to support non-Auth0 issuers with different rules that's reasonable, it just feels like it should be a deliberate, documented choice rather than something the option quietly allows. WDYT?
There was a problem hiding this comment.
Yes, my initial understanding was that the limit of 5 was a general limit, so I hardcoded it based on the Auth0 behavior. After your comment, I realized that this is an Auth0 specific limit and that other issuers may have different requirements.
That's why I made it configurable, so users can set the limit based on their own issuer's behavior and use case, rather than assuming every issuer follows Auth0's limit.
- Decode cnf and act independently so a malformed act can no longer drop the cnf claim and silently downgrade a DPoP-bound token - Add WithMaxActorChainDepth option (positive-only, default 5) so the delegation chain depth limit is configurable instead of a fixed const - Stop DelegationChain at the first empty subject so it agrees with HasActor and CurrentActor on what an empty subject means - Align docs and comments with the invalid_claims error actually returned - Add end-to-end ValidateToken tests for actor/org/azp, over-depth rejection, configured depth, and cnf survival with a malformed act
| // entries. | ||
| func (v *ValidatedClaims) DelegationChain() []string { | ||
| var chain []string | ||
| for a := v.RegisteredClaims.Act; a != nil && a.Subject != ""; a = a.Act { |
There was a problem hiding this comment.
This stops the walk the moment it hits an actor with an empty sub, and returns whatever it collected up to that point with no error.
An empty subject as end-of-chain should be surfaced as an error
There was a problem hiding this comment.
Pushed the changes in latest commit.
…n error Per RFC 8693 §4.1 generic verification must not fail on the act claim, so an actor with an empty sub no longer needs handling at ValidateToken. Change DelegationChain to return ([]string, error): it walks the full chain and returns ErrMalformedDelegationChain along with the subjects collected so far when an actor has an empty sub, instead of silently truncating. HasActor and CurrentActor keep their existing empty-sub semantics.
3 participants
📝 Checklist
🔧 Changes
Adds first-class validation support for access tokens issued through On-Behalf-Of / Token Exchange (RFC 8693), for example when an MCP server exchanges an incoming user token for one scoped to a downstream API. This SDK validates and inspects such tokens; performing the exchange itself is done by the authorization server, not this middleware.
These claims are now parsed automatically during validation, so no extra configuration is required.
validator.RegisteredClaims(new fields, additive)Act *Actor— theact(actor) claim chain per RFC 8693 §4.1AuthorizedParty string— theazpclaimOrgID string— theorg_idclaimOrgName string— theorg_nameclaimNew
validator.ActortypeModels the nested
actclaim:Subject(sub), optionalIssuer(iss), and a nestedAct *Actorfor the prior actor.New helpers on
validator.ValidatedClaimsCurrentActor() string— the current actor (outermostact.sub), the client that performed the most recent exchange. Per RFC 8693 §4.1, this is the only actor value that may be used for access-control decisions.DelegationChain() []string— the full actor chain ordered from current to original, intended for audit and logging only.HasActor() boolThe API is shaped so the safe call (
CurrentActor) is the obvious one, andDelegationChainis explicitly documented as audit-only, matching the RFC 8693 §4.1 guidance that nested actors must not drive authorization.Delegation chains are limited to 5 levels; a token whose
actclaim nests more than 5 actors is rejected as aninvalid_claimsvalidation error.All changes are additive. No existing fields, signatures, or behavior changed, and no new dependencies or network calls are introduced. Extraction of
act,azp,org_id, andorg_nameis folded into the existing single payload decode alongside thecnfclaim.📚 References
actclaim)🔬 Testing
CurrentActor,DelegationChain, andHasActorhelpers cover the no-actor, empty-subject, single-exchange, and chained-exchange cases (validator/claims_test.go).invalid_claims), and a malformed token (validator/validator_test.go).go test ./...(865 tests),go vet ./...clean,gofmtclean.