Skip to content

Document JWT Bearer Flow trust assumptions #343

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
jpengar merged 4 commits into from
Feb 4, 2026
+3 −1
Merged

Document JWT Bearer Flow trust assumptions #343

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
71b4b1d
Document jwt bearer flow trust assumptions
sfnuser Jan 27, 2026
e9fb65e
Update documentation/CAMARA-API-access-and-user-consent.md
sfnuser Jan 28, 2026
2e8999d
Document the limitations of tel subject claim
sfnuser Jan 29, 2026
7064768
Update documentation/CAMARA-API-access-and-user-consent.md
jpengar Feb 2, 2026
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
4 changes: 3 additions & 1 deletion documentation/CAMARA-API-access-and-user-consent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -342,7 +342,9 @@ The JWT Bearer Flow enables an API Consumer (typically the Application Backend o

**Pre-requisite:** The API Consumer must share its public key with the API Provider during onboarding, so the API Provider can verify the signature of the JWT assertion.

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.
Copy link
Collaborator

@sebdewet sebdewet Feb 2, 2026

Choose a reason for hiding this comment

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

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.

Copy link
Collaborator

@jpengar jpengar Feb 2, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

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?

Copy link
Collaborator

@jpengar jpengar Feb 2, 2026

Choose a reason for hiding this comment

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

We may want to add something like this to the text above:

The JWT Bearer sub claim 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.

Copy link
Collaborator

@jpengar jpengar Feb 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

@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!

CC @tanjadegroot

Copy link
Contributor Author

@sfnuser sfnuser Feb 4, 2026

Choose a reason for hiding this comment

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

Please proceed 👍🏼

Copy link
Collaborator

@jpengar jpengar Feb 4, 2026

Choose a reason for hiding this comment

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

@sebdewet I created an issue on GitHub to track the topic about the phone number format for the sub claim: #345.


Example JWT assertion, which MUST be signed by the API Consumer and MAY be encrypted:

Expand Down