Document when FE flow is applicable with regards to involved devices

[Elisabeth-Ericsson]

What type of PR is this?

• documentation

What this PR does / why we need it:

There is some misunderstanding about Authorization code flow, a.k.a. FE flow.
It is important to clarify that OIDC authorization code flow is meant to authorize the client/device, which originates the authorization code flow request. This is independent of whether an optional login_hint (e.g. an operator token) is provided or not. The access code generated for such a request (and the resulting access token) are ONLY applicable to API calls, where the target device of the API call is the same device, which has sent in the authorize request earlier.
Authorization code flow must not be abused by indicating an identifier in the optional login_hint, which deviates from the device, which starts the flow.

Which issue(s) this PR fixes:

Fixes #255

Fixes #

Special notes for reviewers:

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

[AxelNennker]

I hope that misunderstandings regarding OIDC Authorization Code Flow were removed by "Agreed conclusion statement about auth method in Auth Code Flow #253"
That PR added text to CAMARA Security and Interoperability Profile.

A quote from the conclusion:

CAMARA does not intend to limit the Authorization Code Flow to just network-based authentication in the future. New workstreams will be initiated to define the necessary changes that will ensure the Authorization Code Flow can be interoperably used with both network-based and non-network-based authentication methods.

I created several PRs that try to remove that "limit" e.g. #244

We created CAMARA Security and Interoperability Profile to clarify and add new meaning to e.g. OIDC and e.g. "abused" scope to introduce "purpose as a scope". @shilpa-padgaonkar proposal to introduce a new purpose parameter would have been a "cleaner" solution, but that was rejected because suppliers prefer implementing standards and are reluctant to add new parameters. If ICM decides that e.g. login_hint has more meaning in the future, without violating the standard, then that decision would follow the same reasoning as what we did regarding purpose.
We could define a new parameter "target_device" or use "login_hint". I propose to explore how far we can get with standard parameters before adding new parameters.

[jpengar]

@Elisabeth-Ericsson I guess this clarification is still being added under Spring25 scope, where network-based auth must be used in Auth Code Flow. Right?

[Elisabeth-Ericsson]

@Elisabeth-Ericsson I guess this clarification is still being added under Spring25 scope, where network-based auth must be used in Auth Code Flow. Right?

Yes, exactly

[AxelNennker]

The purpose of this PR is clarification what the two three-legged flows actually do regarding "devices", right?

As discussed in #215 OpenId Authorization Code Flow currently does network-based authentication.
We added clarifying text in this PR.
https://github.com/camaraproject/IdentityAndConsentManagement/pull/253/files
That documents the status quo.

We are currently working on TS.43 based and SIM-based (EAP-AKA) authentication. Which is going to change that status quo.

@Elisabeth-Ericsson Do we need this PR and the new definition of Target Device?

[Elisabeth-Ericsson]

@AxelNennker : I think that we need this PR even more, if we allow more methods for authentication.

• If we allow the operator_token as login hint at some point in time, then also here it must be understood that the operator token identifies the consumption device, which also acts as target resource.
• If you want to extend/modify this with your ideas on using FE flow for testing consent, and want to introduce another interpretation, than is it even more needed to have a clear understanding on what we have today and where we want to go.
• When I talk to my colleagues from E///, they really appreciate this clarification, because this is the basis for potential changes & extensions.
• We are writing our documentation for a broad audience and I learned that it is NOT properly understood by everbody that we have this "limitation" or call it "scenario" in the FE flow today that consumption device == target resource of API call.

[AxelNennker]

CIBA is necessary if Consumption Device and Authentication Device are different. If Consumption Device and Authentication Device are the same, then OIDC Authentication Code Flow SHOULD be used.

The API Provider MUST send a message to the authentication device, identified by login_hint, because otherwise there would be no authentication at all.

Note: In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.

User consent cannot be checked based on the login_hint value alone and without sending a message, because then CIBA would be a two-legged flow while according the the note above a three-legged flow is mandatory.

[Elisabeth-Ericsson]

Relation between consumption device and authentication device:

CIBA is necessary if Consumption Device and Authentication Device are different. If Consumption Device and >Authentication Device are the same, then OIDC Authentication Code Flow SHOULD be used.

The API invoker cannot know whether consumption device and authentication device are different. The API invoker in general has no awareness at all about authentication devices. The API invoker only knows the target device and potentially also the consumption device. Who is the legal responsbile (authorization device) of the target device is only known to the backend - the telco operator.

The OIDC Authentication Code Flow protocol does not foresee to communicate whether the consumption device is the authentication device or not. It would be beneficial to get this information in the response, but this is not the case today.

CIBA flow:

User consent cannot be checked based on the login_hint value alone and without sending a message, because then >CIBA would be a two-legged flow while according the the note above a three-legged flow is mandatory.
Can you please clarify this statement ?
AFAIK CIBA transports the information about the target resource/target device in the login_hint, The consent check happens for the target resource specified in the login_hint, The API invoker does not have any knowlege about the consumption device in this context.

[jpengar]

@Elisabeth-Ericsson I've added a few more comments to ensure the document's overall meaning and structure. Please take a look and consider replacing existing content with my suggestions if you agree.

[jpengar]

Perhaps we should also add a definition of an Authentication Device. The one in the CIBA standard looks good to me:

The device on which the user will authenticate/authorize the request, often a smartphone.
Ref: https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#terminology

[jpengar]

The applicability of the Authorization Code Flow is described in the Technical ruleset for the Frontend flow section. It may be better to move this statement there and integrate it with the rest of the information in that section here

Something like...

If all API use cases indicate the need for an 'On-Net' scenario and where the Consumption Device and Authentication Device are the same, the Front-end flow (Authorization Code Flow) SHOULD be used. e.g. Number Verification API.

Also note, the Authorization Code Flow is only applicable if the Consumption Device that initiates the process of obtaining a Three-Legged Access Token from the Authorization Server is also the Target Device of the intended CAMARA API call(s). Therefore, access tokens are issued for the network authenticated identifier.

This flow then enables On-Net scenarios where the mobile connection of the Consumption Device needs to be authenticated. For example, the [CAMARA Number Verification API](https://github.com/camaraproject/NumberVerification), due to the nature of its functionality, where the User's MSISDN needs to be compared with the MSISDN associated with the mobile connection of the Consumption Device. 

[jpengar]

The applicability of the CIBA Flow is described in the Technical ruleset for the Backend flow section. It may be better to move this statement there and integrate it with the rest of the information in that section here

Something like...

If the API use case(s) indicate the need for an "Off-net" scenario and/or if the Consumption Device and Authentication Device are different, the Backend flow (CIBA) SHOULD be used.

Also note that in the case of the CIBA flow, it is applicable if the Consumption Device is the same or different from the Target Device of the intended CAMARA API call(s).