Skip to content

Clarify need to validate the signature on signed subject tokens #253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Nov 3, 2025
Merged

Clarify need to validate the signature on signed subject tokens #253

Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
07e0e7f
Clarify need to validate the signature on signed subject tokens
PieterKas Sep 18, 2025
1ef8b15
Merge branch 'main' into PieterKas-patch-8
PieterKas Sep 23, 2025
5adb8cc
Merge branch 'main' into PieterKas-patch-8
PieterKas Sep 23, 2025
0fa48dc
Update draft-ietf-oauth-transaction-tokens.md
PieterKas Oct 8, 2025
be59dd7
Update draft-ietf-oauth-transaction-tokens.md
PieterKas Oct 8, 2025
4d21d29
Merge branch 'main' into PieterKas-patch-8
PieterKas Oct 20, 2025
b5b85ea
Merge branch 'main' into PieterKas-patch-8
PieterKas Nov 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 14 additions & 19 deletions draft-ietf-oauth-transaction-tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -566,25 +566,19 @@ A requester MAY use an unsigned JSON object as a `subject_token` value. In that
The unsigned JSON object MAY contain other fields, and the Txn-Token Service MAY consider them when generating the Txn-Token.

## Txn-Token Request Processing
When the Transaction Token Service receives a Txn-Token Request it MUST validate the requesting workload client authentication and determine if that workload is authorized to obtain the Txn-Tokens with the requested values. The authorization policy for determining such issuance is out of scope for this specification.

Next, the Transaction Token Service MUST validate the `subject_token` and determine the value to specify as the `sub` of the issued Txn-Token. The Txn-Token Service MUST ensure the `sub` value is unique within the Trust Domain defined by the `aud` claim.

The Transaction Token Service MUST set the `iat` claim to the time of issuance of the Txn-Token.

The Transaction Token Service MUST set the `aud` claim to an identifier representing the Trust Domain of the Transaction Token Service. If the Transaction Token Service supports multiple Trust Domains, then it MUST determine the correct `aud` value for this request.

The Transaction Token Service MUST set the `exp` claim to the expiry time of the Txn-Token. The Txn-Token Service MAY consider any `exp` value present in the `subject_token` parameter of the Txn-Token Request in determining the `exp` value of the resulting Txn-Token.

The Transaction Token Service MUST set the `txn` claim to a unique ID specific to this transaction.

The Transaction Token Service MAY set the `iss` claim of the Txn-Token to a value defining the entity that signed the Txn-Token. This claim MUST be omitted if not set.

The Transaction Token Service MUST evaluate the value specified in the `scope` parameter of the request to determine the `scope` claim of the issued Txn-Token. The value of this claim, as issued by the Transaction Token Service, does not need to match the requested `scope` value as the Txn-Token `scope` claim represents the intent or purpose of the transaction within the Trust Domain.

If a `request_context` parameter is present in the Txn-Token Request, the data SHOULD be added to the `rctx` object of the Txn-Token. In addition, the Transaction Token Service SHOULD add the authenticated requesting workload identifier in the `rctx` object as the `req_wl` claim.

If a `request_details` parameter is present in the Txn-Token Request, then the Transaction Token Service SHOULD propagate the data from the `request_details` object into the claims in the `tctx` object as authorized by the Transaction Token Service authorization policy for the requesting client.
When the Transaction Token Service receives a Txn-Token Request it:

* MUST validate the requesting workload client authentication and determine if that workload is authorized to obtain the Txn-Tokens with the requested values. The authorization policy for determining such issuance is out of scope for this specification.
* Next, the Transaction Token Service MUST validate the `subject_token`, including verifying the signature, if it is signed.
* The Txn-Token Service determines the value to specify as the `sub` of the Txn-Token and MUST ensure the `sub` value is unique within the Trust Domain defined by the `aud` claim.
Copy link
Collaborator

@gffletch gffletch Sep 23, 2025

Choose a reason for hiding this comment

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

If workloads are going to be obtaining transaction tokens, and sub represents the workload "class" then it won't be unique. Is it ok to drive workload use cases to use an instance identifier for the workload rather than the "class" identifier?

Copy link
Collaborator Author

@PieterKas PieterKas Oct 8, 2025

Choose a reason for hiding this comment

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

@gffletch - it is up to the transaction token service to determine the "sub" claim. The way in which that is interpreted is domain specific.

* The Transaction Token Service MUST set the `iat` claim to the time of issuance of the Txn-Token.
* The Transaction Token Service MUST set the `aud` claim to an identifier representing the Trust Domain of the Transaction Token Service. If the Transaction Token Service supports multiple Trust Domains, then it MUST determine the correct `aud` value for this request.
* The Transaction Token Service MUST set the `exp` claim to the expiry time of the Txn-Token. The Txn-Token Service MAY consider any `exp` value present in the `subject_token` parameter of the Txn-Token Request in determining the `exp` value of the resulting Txn-Token.
* The Transaction Token Service MUST set the `txn` claim to a unique ID specific to this transaction.
* The Transaction Token Service MAY set the `iss` claim of the Txn-Token to a value defining the entity that signed the Txn-Token. This claim MUST be omitted if not set.
* The Transaction Token Service MUST evaluate the value specified in the `scope` parameter of the request to determine the `purp` claim of the issued Txn-Token.
* If a `request_context` parameter is present in the Txn-Token Request, the data SHOULD be added to the `rctx` object of the Txn-Token. In addition, the Transaction Token Service SHOULD add the authenticated requesting workload identifier in the `rctx` object as the `req_wl` claim.
Copy link
Collaborator

@gffletch gffletch Sep 23, 2025

Choose a reason for hiding this comment

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

Is adding the requesting workload a SHOULD because we don't want to be too prescriptive? My preference would be to make this a MUST.

Copy link
Collaborator Author

@PieterKas PieterKas Oct 8, 2025

Choose a reason for hiding this comment

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

@gffletch This PR was about making it clear that the signature should be validated (the additional text is just re-formatting). Perhaps @tulshi can add context on why the original text had a SHOULD vs MUST.

Copy link
Collaborator

@tulshi tulshi Oct 29, 2025

Choose a reason for hiding this comment

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

I had a different opinion of the rctx content in the TraT. I feel the TTS should take the request_context into consideration, but really use its own logic to arrive at the content of the rctx field in the TraT. So, I'd rather be silent in the spec rather than use either "SHOULD" or "MUST" regarding this.

My logic is that the requester may send it a number of different things in the request_context, and the TTS may decide to use only a subset of it, or may need to process the values for internal consumption before putting it into rctx.

Thoughts?

Copy link
Collaborator Author

@PieterKas PieterKas Oct 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@tulshi, @gffletch This PR was about making it clear that the signature should be verified - the rest was formatting...

However, if we want to discuss rctx content (which is not the subject of this PR, but clearly a valid thing to discuss), perhaps we can merge this and open a separate issue and discuss request_context and tctx there instead?

My preference is to contain the PR to the issue it was meant to address (clarifying that the signatture needs to be verified).

* If a `request_details` parameter is present in the Txn-Token Request, then the Transaction Token Service SHOULD propagate the data from the `request_details` object into the claims in the `tctx` object as authorized by the Transaction Token Service authorization policy for the requesting client.

The Transaction Token Service MAY provide additional processing and verification that is outside the scope of this specification.

Expand Down Expand Up @@ -797,6 +791,7 @@ The authors would like to thank the contributors and the OAuth working group mem
* Remove definition of Authorization Context [Be more specific on Authorization Context](https://github.com/oauth-wg/oauth-transaction-tokens/issues/192)
* Clarify text on use of empty parameter: https://github.com/oauth-wg/oauth-transaction-tokens/issues/235
* Clarify that workloads should ensure it is communicating with a legitimate instance of a transaction token service (https://github.com/oauth-wg/oauth-transaction-tokens/issues/233)
* Clarify need to validate signature on subject_token if it is signed.
* Clarify role of transaction tokens in call chain (https://github.com/oauth-wg/oauth-transaction-tokens/issues/203)
* Remove exp field from unsigend token (https://github.com/oauth-wg/oauth-transaction-tokens/issues/201)

Expand Down