No clear guideline in API documentation about Authcode flow vs CIBA flow

[gauravji2192]

Problem description
There is no clear guideline in API documentation about Authcode flow vs CIBA flow.
Current statement in SIM SWAP API https://github.com/camaraproject/SimSwap/blob/main/code/API_definitions/sim-swap.yaml, "
_# Authorization and authentication

The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile.

Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

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. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control._"

Similar issue is with many of existing CAMARA APIs.

Expected action
I think there must be an additional line in this statement," In case of 3-legged flow, if application is directly consumed by CSP subscriber then Auth code flow must be used. If application is not consumed directly by CSP subscriber, then CIBA flow must be used. CSP must support both grant type and provide application developer guidance to implement 3-legged oAuth 2.0 grant type based on use case."

Additional context
ASPs/Aggregators may face challenge that Operator A in a country X is exposing SIM swap using CIBA and Operator B in same country X is exposing SIM Swap using Auth code grant type. It must be dependent on use case and application requirement.

[eric-murray]

Hi @gauravji2192

Have you read this ICM document, where it says:

If all API usecases point to the need of On-net scenario and where the consumption device and authentication device are the same, the Frontend flow should be used. eg. NumberVerification

and

If some usecase/s for an API point to off-net scenarios and where consumption and authentication devices could be different, the Backend flow should be used.

Which is basically what you are saying. Of course, the text in CAMARA documents can always be improved.

In practise, you will not know which authentication schemes are supported until you read the API provider's .well-known/openid-configuration endpoint, which will be API specific. If only "authorization_code" is listed as a valid grant type, well there's your answer.

But specifically for SIM Swap, I'm curious to know who is using Authorisation Code Flow for this API? What is the use case?

[gauravji2192]

Hi @gauravji2192

Have you read this ICM document, where it says:

If all API usecases point to the need of On-net scenario and where the consumption device and authentication device are the same, the Frontend flow should be used. eg. NumberVerification

and

If some usecase/s for an API point to off-net scenarios and where consumption and authentication devices could be different, the Backend flow should be used.

Which is basically what you are saying. Of course, the text in CAMARA documents can always be improved.

In practise, you will not know which authentication schemes are supported until you read the API provider's .well-known/openid-configuration endpoint, which will be API specific. If only "authorization_code" is listed as a valid grant type, well there's your answer.

But specifically for SIM Swap, I'm curious to know who is using Authorization Code Flow for this API? What is the use case?

Yes, I have read this statement.
My concern is related to improvement in API documentation of SIM swap and other APIs. There can be cases where Operator are also exposing SIM Swap API using Authcode grant type. So, my request is to clarify this as part of API documentation to avoid future interoperability issues.

[eric-murray]

Improved documentation proposals are always welcome within the ICM working group. CAMARA is an open-source project.

But this documentation will remain guidance. CAMARA cannot force API providers to support a particular use case or authorisation flow. The API consumer will only find out what is supported when they check the API provider's .well-known/openid-configuration endpoint. You will need to look to other organisations, such as GSMA OGW, to enforce co-ordination between API providers.

I'm still curious as to who would support authorisation code flow for SIM Swap, and why.

[gauravji2192]

Actually, I am not sure if it is final implementation from a CSP, but I see an example of Auth code grant type for SIM swap API:

https://developer.orange.com/apis/camara-sim-swap-france/getting-started

I guess that there must be a reason or use case behind this.

[eric-murray]

Hmmm... so Orange require that the user of the mobile device give their explicit consent before the API consumer can call the SIM Swap API? If I were a fraudster that had successfully taken over somebody else's SIM, I suspect I would not give that consent. I don't think the author of that page has fully understood the SIM Swap use case.

[gauravji2192]

If we are almost certain that SIM Swap API will require CIBA flow in case of 3-legged flow, I would request modifying API documentation to mention this. This would help in reducing different implementation approaches.

[eric-murray]

If we are almost certain that SIM Swap API will require CIBA flow in case of 3-legged flow, I would request modifying API documentation to mention this. This would help in reducing different implementation approaches.

The problem is that this ultimately might depend upon regulation, over which CAMARA have no control. Some regulators might not require any end user consent at all (so client_credentials grant), whereas others might mandate explicit "in-band" end user consent via a pop-up (so "authorisation_code" grant).

CAMARA cannot mandate for regulations in all countries, only provide options for each possibility.