Document JWT Bearer Flow trust assumptions#343
Conversation
sfnuser
requested review from
AxelNennker,
jpengar and
sebdewet
as code owners
jpengar
left a comment
jpengar
left a comment
There was a problem hiding this comment.
LGTM. Just one small writing suggestion.
Co-authored-by: Jesús Peña García-Oliva <jesus.penagarcia-oliva@telefonica.com>
|
@sebdewet @AxelNennker and all, |
| The API Consumer selects the User Identifier. The User is identified by the `sub` claim in the JWT assertion, which must uniquely identify the User in the Operator's system. As per the CAMARA Security and Interoperability Profile, the `sub` claim MUST be either a phone number prefixed by "tel:" or a TS.43 token prefixed by "operatortoken:". | ||
| The API Consumer selects the User Identifier. The User is identified by the `sub` claim in the JWT assertion, which must uniquely identify the User in the Operator's system. As per the CAMARA Security and Interoperability Profile, the `sub` claim MUST be either a phone number prefixed by `tel:` or a TS.43 token prefixed by `operatortoken:`. | ||
|
|
||
| Unlike the `operatortoken:` prefix for the `sub` claim, which originates from a TS.43 flow and provides a stronger binding to a Subscriber context, the use of the `tel:` prefix in the JWT Bearer Flow is applicable in scenarios where a pre-established trust relationship exists between the API Consumer and the API Provider. In this case, the API Consumer is responsible for asserting the phone number in the sub claim and for ensuring that this value accurately represents the intended Subscriber. The API Provider, in turn, relies on this trust relationship when accepting the assertion and does not independently validate the origin of the phone number. The mechanism by which the API Consumer obtains or verifies the phone number used in the `sub` claim is outside the scope of CAMARA specifications. |
There was a problem hiding this comment.
Can we add a part where it is define clearly that the API Consumer must ensure the verification and validation of the phone number, including checking that the number is in the correct international format. The operator should not solely rely on the assertion in the JWT but expect the API Consumer to perform proper formatting and validation before asserting the number.
There was a problem hiding this comment.
I think this topic about formatting phone numbers is quite relevant, but not strictly related to the issue this PR is trying to fix. As we did for the login_hint, I think the phone number format in the JWT Bearer assertion must be specified in the ICM profile. The format would be the same as "tel:" in login_hint.
Considering this PR is the only dependency currently needed to generate the ICM Spring26 release candidate PR, we can take advantage of this PR to complete the format clarification in the profile if it can be done with minimal effort or discussion. Otherwise, I will not include the format clarification for "tel:" in the JWT Bearer "sub" claim in this PR, handling it as an editorial correction in a new issue instead. This will not block the RC generation.
WDYT?
There was a problem hiding this comment.
We may want to add something like this to the text above:
The JWT Bearer
subclaim format for CAMARA is defined in the [CAMARA Security and Interoperability Profile](link to sub format definition in ICM profile).
Then, add the required changes to the ICM profile.
There was a problem hiding this comment.
@sebdewet @sfnuser @AxelNennker Given that there hasn’t been further response on the remaining Seb's comment about the phone number format, my suggestion is that we go ahead with merging this PR if there are no outstanding objections. The current change is stable and tidy, and merging it will allow us to proceed with preparing the ICM Spring26 release candidate.
We can address the "tel:" prefix formatting concern in a follow-up issue after this merge and include it as an editorial fix post-RC. That lets us keep momentum on the release cadence without blocking on a detail we can clean up soon after.
To keep the schedule aligned with the Spring26 meta-release plan, let’s aim to merge this PR by tomorrow so that the release candidate can be created in time for the TSC approval next Thursday.
If you have any objections to this plan, please comment here before noon tomorrow. Otherwise, I will proceed with merging.
Thanks!
3 participants
What type of PR is this?
What this PR does / why we need it:
As agreed on the issue #338 discussion, this commit explicitly documents the trust relationship when using
tel:prefix assubclaim.Which issue(s) this PR fixes:
Fixes #338
Special notes for reviewers:
Changelog input
Additional documentation
N/A