Extracting phoneNumber from the 3-legg access token

[gregory1g]

Problem description
When a 3-legged auth is used, the access token is MSISDN specific. This has two important consequences:

1. an API must validate that that access token matches the MSISDN in the payload and issue an error if does not
2. there is a possibility to remove MSISDN from the payload and use one extracted from the access token

As far as I understand commonalities tends to prefer the second option (avoid duplication and use the token):
camaraproject/Commonalities#171

SimSwap does not use device object per se, however the question if one should use MSISDN from the access token instead of payload is relevant for the SimSwap. Moreover, phoneNumber is currently a mandatory parameter, therefore switching to access token based execution will be a not-backward compatible change.

Possible evolution
phoneNumber can be declared optional. Thus, it must be provided when client credentials auth is used, and must not be provided when 3-legged token is used. Or at least we can introduce such approach in the future without breaking backward compatibility.

[gregory1g]

Let's at least discuss and write down the decision about this topic

[eric-murray]

Hi @gregory1g

My comments would be:

• Making a required parameter optional is not a breaking change for the client

• When implementing the API using CIBA, it was recognised that there were two options for the phoneNumber passed in the request body:

  • Ignore it
  • Check that it matches the MSISDN of the end user associated with the access token, and flag an error if it does not

  Agreement on that behaviour is probably required. Note that the second option will consume additional time, however desirable this extra check might be.

[hdamker]

@gregory1g @eric-murray The question above looks for me very similar to the more general discussion in camaraproject/IdentityAndConsentManagement#174

[gregory1g]

commonalities has updated the guideline for 3-legged cases. The guideline says that if phoneNumber is provided in the payload the API must validate it towards the access token: camaraproject/Commonalities#233

[bigludo7]

For my perspective, first, the phone number should be optional (This is already the case) and second, we have the 403 INVALID_TOKEN_CONTEXT as specified here if these is mismatch between the phone number in the access token and the one in the request.

You think @gregory1g that we need more?

[gregory1g]

formally, I do agree. But as a API client developer and as an API server developer I would prefer more clear statements.
for example:

1. may I implement client-credential auth or 3-legged is a must?
2. I want to implement an API client with 3-legged auth, should I better send MSISDN in the body or not?
3. I want to implement an API client with client credentials, should I send MSISDN in the body or not?
4. If I want to implement SimSwap server must compare MSISDN in access token and in the payload, or I'm fine to prioritize token info and ignore payload?

We have discussed all these topic and have an agreed view, but they are very documented.

[bigludo7]

@gregory1g got it. From my perspective and happy to get yours & from the team

1.may I implement client-credential auth or 3-legged is a must?

Camara rule: It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory.
Mechanically... In case of sim-swap --> personal data are involved so 3-legs is a must.

2.I want to implement an API client with 3-legged auth, should I better send MSISDN in the body or not?

Better to not sent it to avoid to be in position 4.

3.I want to implement an API client with client credentials, should I send MSISDN in the body or not?

Given 1 I will say that if you use this API under CAMARA 'rules of engagement' this question is not relevant

4.If I want to implement SimSwap server must compare MSISDN in access token and in the payload, or I'm fine to prioritize token info and ignore payload

Your server must compare and must throw a 403 if mismatch.

[gregory1g]

Camara rule: It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory.
Mechanically... In case of sim-swap --> personal data are involved so 3-legs is a must.

Let's document this. One cannot expect that all developers (server and client slide) read all camara commonalities guideline AND understand them same way.
I personally recall that @AxelNennker brought client-credential option and we have agreed that SimSwap must support this as well, because there are scenarios when this is enough. We do discuss this topic because we did not documented supported flow explicitly.

Your server must compare and must throw a 403 if mismatch.

a. if 3 legged is a must, what's the point to provide phone number in the payload at all? Just to force server do a comparison? According to commonalties this should be avoided. So, if 3-legged is a must - we should better remove phone number from the payload.
b. 403 or 422 "DEVICE_IDENTIFIERS_MISMATCH"? Either way, it is better to explicitly document what the API returns in this case, then people do not need to make assumptions.

[bigludo7]

Hi @gregory1g

Let's document this.

Humm I'm bit uncomfortable to do that as the ICM team took weeks to agreed on the 'magic' sentences that we added in all API. I'm more in favor to keep as it at least for this meta-release.

@fernandopradocabrillo @AxelNennker wdyt?

[hdamker]

@bigludo7 @fernandopradocabrillo I'm also in favour to not change or interfere with the current documented statements. There is some reasoning behind, especially to decouple the technical specification from legal discussions which have to happen within a specific legal framework when onboarding a concrete application owner and application.

For example:

1.may I implement client-credential auth or 3-legged is a must?

Camara rule: It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory.
Mechanically... In case of sim-swap --> personal data are involved so 3-legs is a must.

It is for safe to assume and use 3-legged tokens here. But reading the sentence not mechanically, but with a legal mindset: there is an "and" between the two conditions. Which means: In cases where users don't have rights to opt-in or opt-out from a SimSwap check, for example if it is requested by local law from banks to do the check in certain cases, then the conclusion that 3-legged is mandatory is not automatically following. But it is still safe to use 3-legged, as also with a 3-legged token these cases can be handled. So as an API provider you might can decide to offer SimSwap only with e.g. CIBA flow, as this covers all cases in your market. But there might be other markets where SimSwap is expected to be offered with Client Credentials.

In short: the final decisions can't be taken by developers alone, it is also a subject of business and legal discussions within markets and during the onboarding of an application.

[gregory1g]

So, technically client-credentials and 3-legged are supported, therefore phoneNumber in the request payload must stay.
We assume that 3-legged to be a "default" option and in this case it is recommended to skip phoneNumber in the payload.
But we document neither of that in the API description.

If this is correct understanding, we can close this issue.

[hdamker]

So, technically client-credentials and 3-legged are supported, therefore phoneNumber in the request payload must stay. We assume that 3-legged to be a "default" option and in this case it is recommended to skip phoneNumber in the payload.

This understanding is correct from my point of view.

But we document neither of that in the API description.

There is the Appendix A: info.description template for device identification from access token with a recommended text to be added into the info.description of the API YAML. You would need to change the text a bit (as you don't have device but only phoneNumber) but the general text should fit.

cc: @bigludo7 @fernandopradocabrillo

If this is correct understanding, we can close this issue.

Expected action could be to add the recommended text to the API description.

[AxelNennker]

A quote from https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#user-authenticationauthorization--consent-management

It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory.

From that is follows that because phoneNumer is personal user data, a 3-legged flow is mandatory.

Subscribers might have opted-out of the API and that opt-out check is still possible with client credentials, but there is no consent collection or opt-in with client credentials flow.

I would not add a optional phoneNumber parameter because that leads to all kinds of trouble. The case where phoneNumber from the access token and phoneNumber from the parameter were discussed above. But some telcos might implement a version of the API where if the two phoneNumbers have the same person or contract owner then they accept the API request based on the access token but the result is still for the parameter phoneNumber.
To have a clear API without a way of implementing this other interpretation, I would only have a required phoneNumber parameter in the client credentials flow and NO parameter phoneNumber in the 3-legged flow.

I would go for a separate endpoint with a separate scope for the client credentials version of the API and only clients who are eligible for client credentials get that scope. That way we can still have one openIdConnect security scheme as decided by TSC, but still decide at client-onboarding-time which client gets that client-credentials-scope.

  /sudocheck:
    post:
      security:
        - openId:
            - sim-swap:sudocheck
      tags:
        - Check SIM swap for any phoneNumber
      description: Check if SIM swap has been performed during a past period - OAuth2 client credentials
      operationId: sudoCheckSimSwap
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - $ref: '#/components/parameters/phoneNumber'

Any client credentials flow version of any API is NOT privacy friendly. Providing a client credentials flow should be the exception and not be used e.g. if a telco failed to implement OpenId Connect.

[jpengar]

I agree with @bigludo7 proposal in #117 (comment) and with @hdamker clarifications in #117 (comment). Thank you!

@fernandopradocabrillo @bigludo7 I think this issue can be resolved adding the corresponding explanation to API description and including the required error responses to both API endpoints. Appendix A: info.description template for device identification from access token is a good reference, but it is intended for APIs using device object. However it could be easily adapted for an API using just phone_number identifier.

P.D: Just to clarify. As stated in this Appendix...

Depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differs from the common device object definition. Not all APIs necessarily have to refer to a device, e.g. Carrier Billing API only defines a phone number as a way to identify the mobile account to be billed, Know Your Costumer only defines a phone number as a way to identify the associated account data or Home Devices QoD API defines public IP v4 address as a way to identify the user home network.

Therefore, the mechanism described in this template is not applicable to all APIs, but could be used as way to make device object more interoperable and usable for API consumers.

This is the case of the SIM Swap API, which defines phone_number as a way to identify the corresponding "user account" (no device concept is used). In cases where the device object commonality guideline does not apply, it is up to the API subproject to decide whether or not to rely on the access_token in 3-legged scenarios according to its own criteria and API requirements. And in this case, it was decided to follow an approach for the phone_number similar to the one recommended in the commonality guideline for the device object. Which I personally agree with.

[bigludo7]

Hello
In order to solve this issue and following the thread i got the feeling that we have a consensus for:

• add below text in the yaml documentation part (following @jpengar & @hdamker suggestion)
• add 422 UNIDENTIFIABLE_DEVICE in the yaml (this is mentioned in the text)
• add this TC in test definition

Please @AxelNennker @jpengar @hdamker @gregory1g @fernandopradocabrillo could you confirm your support for this?

# Identifying a device from the phoneNumber

This specification defines the `phoneNumber`  field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the phone number can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the information associated with the access token used to invoke the API.

## Handling of phoneNumber information:

### Optional phoneNumber field for 3-legged tokens:

- When using a 3-legged access token, the phoeNumber associated with the access token must be considered as the phone number for the API request. This means that the `phoneNumber`  field is not required in the request, and if included it must identify the same number, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations.

### Validation mechanism:

- The server will extract the phoneNumber identification from the access token, if available.
- If the API request additionally includes a `phoneNumber` object when using a 3-legged access token, the API will validate that the pnhoe number provided matches the one associated with the access token.
- If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the phone number information in the request does not match the token.

### Error handling for unidentifiable phone number:

- If the `phoneNumber` object is not included in the request and the phone number information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_DEVICE` error.

### Restrictions for tokens without an associated authenticated identifier:

- For scenarios which do not have a phone number associated to the token during the authentication flow, e.g. 2-legged access tokens, the `phoneNumber` object MUST be provided in the API request. This ensures that the phone number is explicit and valid for each API call made with these tokens.

[gregory1g]

• If the phoneNumber object is not included in the request and the phone number information cannot be derived from the 3-legged access token, the server will return a 422 UNIDENTIFIABLE_DEVICE error.

for the 3-legged auth this error must be issues even when phoneNumber is included in the payload. Because service cannot prove that access token matches it (we are in 3 legged scenario).

Suggested text version:
If the phone number information cannot be derived from the 3-legged access token, the server will return a 422 UNIDENTIFIABLE_DEVICE error.

[jpengar]

Please @AxelNennker @jpengar @hdamker @gregory1g @fernandopradocabrillo could you confirm your support for this?

@bigludo7 Looks good to me. But I see some typos in the suggested text. Some double spaces after replacing "device object" with phoneNumber and some "phoneNumber object"... I've tried to fix them in the suggestion below.

By the way, you might also consider defining a specific 422 error for this API, as suggested below as well.
422 UNIDENTIFIABLE_PHONE_NUMBER error.
Because this API does not use the device concept.

# Identifying a phone number from the access token

This specification defines the `phoneNumber` field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the phone number can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the information associated with the access token used to invoke the API.

## Handling of phone number information:

### Optional `phoneNumber` field for 3-legged tokens:

- When using a 3-legged access token, the phone number associated with the access token must be considered as the phone number for the API request. This means that the `phoneNumber` field is not required in the request, and if included it must identify the same phone number, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations.

### Validation mechanism:

- The server will extract the phone number identification from the access token, if available.
- If the API request additionally includes a `phoneNumber` field when using a 3-legged access token, the API will validate that the phone number provided matches the one associated with the access token.
- If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the phone number information in the request does not match the token.

### Error handling for unidentifiable phone number:

- If the `phoneNumber` field is not included in the request and the phone number information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_PHONE_NUMBER` error.

### Restrictions for tokens without an associated authenticated phone number:

- For scenarios which do not have a phone number associated to the token during the authentication flow, e.g. 2-legged access tokens, the `phoneNumber` field MUST be provided in the API request. This ensures that the phone number is explicit and valid for each API call made with these tokens.

[bigludo7]

Thanks @jpengar ! this is perfect for me.

@gregory1g I prefer to keep as it is If the phoneNumberfield is not included in the request and the phone number information cannot be derived from the 3-legged access token, the server will return a 422UNIDENTIFIABLE_PHONE_NUMBER error. because it covers all cases where we haven't any phoneNumber without any restriction.