Add companion whitepaper: Operator Token Acquisition for Number Verification on Android (TS.43/OpenID4VP)

[albertoramosmonagas]

What type of PR is this?

Add one of the following kinds:

• documentation

What this PR does / why we need it:

Adds a technical whitepaper describing the end-to-end Operator Token acquisition flow for Number Verification on Android, including TS.43, OpenID4VP, Digital Credentials API and JWT Bearer usage.

The document is intended as complementary implementation guidance and does not modify the CAMARA Number Verification API specification. It is informative, not normative, and fills the gap left by NV 2.1 regarding how an operatorToken is obtained and exchanged prior to calling the API.

Which issue(s) this PR fixes:

Fixes #237

Special notes for reviewers:

This document is informative/companion material, not a change to the NV API definition or YAML. Placement in this repository reflects where the work originated; there is an open discussion about eventually hosting this and similar cross-spec companion material in a dedicated whitepaper/reference repository rather than inside individual API Sub Project repos. Reviewers from Commonalities and ICM are encouraged to confirm alignment with the JWT Bearer flow as currently documented.

Changelog input

release-note
Added companion whitepaper: Operator Token Acquisition for Number Verification on Android (TS.43 / OpenID4VP / Digital Credentials API / JWT Bearer). Informative only; does not modify the NV API specification.

Additional documentation

This section can be blank.

docs

[AxelNennker]

The language could be clearer, I think, what is a "specification" and what is a recommendation.
The description of the PR writes "informative" but the language of the whitepater says "this specification".

[albertoramosmonagas]

The language could be clearer, I think, what is a "specification" and what is a recommendation.
The description of the PR writes "informative" but the language of the whitepater says "this specification.

Thanks for the feedback, Axel. Are you referring to a specific part of the document, or is this a general comment based on what you've seen throughout the document?

[bigludo7]

Hello @albertoramosmonagas
We will take a deep look with the team - this is great work. Thanks !
I have a comment probably close to Axel one about the document objective: is it a specification (that must be enforced) or a guide to help ? I tend to think that it should be initially a guide but as such we should state it explicitly. As you use standardises word for example in your text you're probably see it as a specification.

I have one first comment/question on the detail: Do you have rational to perform the phoneNumber retrieval from the tempToken in step 3 of your flow and not in the 4? I do not have a clear response on that. We have implement this way in some of our countries but I'm struggling to answer when IT architects told that is a Resource Server job and not AS one...

[bigludo7]

Another one (checked with @chatelgu) - in step (3) POST /token (from Application to the Aggregator) it is confusing to use operatortoken as sub type while 1/it is not an operator token (this is a openidv4 token) and 2/ the 'real' operator token is used in the next flow between the aggregator and the CSP auth server. Should defined here another name like vp_token? the assertion will be: assertion = JWT{sub=vp_token:SD-JWT}

Another option is to have in the assertion a dedicated vp_token claim.

[diegotid]

Hi @bigludo7

Once aligned internally at TEF, we thumb up to using vp_token as a prefix to the sub claim

Regarding the previous comment, our rational is as follows:

• We want the flow to be the same for both verify and retrieve, specifically regarding obtaining the access token.
• For verify, we don't want to/can't provide an access token without having identified the line. Therefore, in step 3, we absolutely have to query the entitlement server to find out which line it is (and thus the MSISDN).
• Since we've already done this in that step, we avoid doing it in step 4 (service API).
• So, it makes sense to do the same in retrieve, even though intuitively the data isn't returned until step 4. The access token still needs to have three legs (and therefore the MSISDN must be obtained in step 3).

What are your thoughts, guys?

[albertoramosmonagas]

Hi @bigludo7, @AxelNennker. Thanks for the feedback — pushed a revision addressing it:

• Informative guide, not a specification: status stated explicitly, RFC 2119 softened, "standardises" → "describes".
• Step-3 sub prefix → vp_token: App → Aggregator now uses vp_token:<SD-JWT>; Aggregator → CSP keeps operatortoken:<temp_token>.
• §5.4 rationale: the CAMARA access token is three-legged, so the MSISDN is resolved at step 3; same flow for verify and device-phone-number. Marked provisional.
• Aggregator → CSP hop now references the CAMARA JWT Bearer Flow with Operator Token as the source of the interface.

[kwokonn-looi]

Hi @albertoramosmonagas

Is there a typo in the end-to-end flows in Step 4? It's stated the Application calls the NV API directly but it's the Host: < aggregator-host > that's shown.

Our understanding would be that following Step 3, after the MNO access_token is obtained by the Aggregator, the Aggregator may correspondingly return the aggregator_access_token to the Application. Then in Step 4, the Application calls the Aggregator's API endpoint with the aggregator_access_token, and subsequently the Aggregator maps this to the MNO access_token to call the MNO's API endpoint (as per the standard CAMARA flows with an aggregator).

In this way,

• the Application is still integrated with the Aggregator and calls the Aggregator's API endpoints. The Application does not need to track the MNO's API endpoints per market (especially for global brands).
• the API consumption can be charged correctly by the MNO in relation to the Aggregator, and correspondingly between the Aggregator and the Application. Otherwise, the MNO and the Application may not have the processes properly established for the API consumption.
• the standard onboarding processes between the Aggregator and MNO, and between the Application and the Aggregator are already in place.

I'm not sure if the above is your intention for these flows.

[diegotid]

Hi @kwokonn-looi

You’re absolutely right with your arguments. That’s precisely why Step 4 instructs the application to make its service API request to the aggregator host, rather than the MNOs.

My guess on where the confusion might come from imho, is that many aggregators are not exposing raw CAMARA APIs and thus the understanding of "calling /number-verification/v2/device-phone-number directly" for them is that such call is expected to be performed on the MNOs host.

The white paper though, in the Step 4 description, refers to calling the NV API directly on the aggregator host with the aggregator's provided access_token. Maybe "directly" may result confusing here since it is not grammatically needed, or access_token could be referred to as aggregator_access_token, or it is actually the aggregator exposing raw CAMARA NV API what is confusing.

What's your thoughts on what could be reworded for better understanding?

[kwokonn-looi]

Hi @diegotid

Thanks for your understanding.

If possible, I'd propose to start with the end-to-end flow diagrams since the Application and the Aggregator are present and separated (unlike in the ICM docs). The Step 4 flows (e.g. GET /device-phone-number) may then be split from Application -> Aggregator, and then Aggregator -> CSP NV API, along with the respective API responses per leg.

In the Step 4 text section, you may then opt to describe each of these legs. This should then bring clarity to the Step 4 flows.

[albertoramosmonagas]

Hi @kwokonn-looi,

Thanks, this is a fair point and we appreciate the suggestion. Our sense is that the split you describe is already reflected in the sequence diagrams: both the §3 overview and the detailed Appendix A diagram model the Application and the Aggregator as separate participants (Appendix A even splits App Frontend / App Backend / Aggregator / CSP), so each hop already appears as its own arrow with its own response.

For Step 4 specifically, we have reworded the text so it is explicit that the Application calls the Aggregator's NV endpoint, and the Aggregator then maps the request to the MNO/CSP NV API internally — the same aggregator pattern used in Step 3. With that wording change, we think the per-leg behaviour is clear without adding separate diagrams that would duplicate what the participant columns already distinguish.

So we would propose to keep the current representation as is. If any specific leg still reads ambiguously to you, point us at it and we will refine that spot.

CC: @diegotid

[albertoramosmonagas]

Hi @bigludo7, any points from your side? can we proceed with merge this PR?