OIDC authorization code flow and/or CIBA

[AxelNennker]

Problem description During the 2024-06-06 TSC meeting @MarkCornall raised the question whether it is clear in one API whether it supports CIBA and/or OIDC authorization code flow. And whether telcos have to support one or the other or both.

Expected action Take the discussion to ICM. Which I interpret as. Provide guidelines and clarification in CAMARA APIs access and user consent management

Probably here:

Technical ruleset for the Backend flow NOTE: The technical ruleset is applicable only after a subproject has agreed to use a 3-legged authentication flow. This ruleset provides a recommendation which will help API providers to align on the 3-legged flow and help with aggregation.

And here:

Technical ruleset for the Frontend flow

NOTE: The technical ruleset is applicable only after a subproject has agreed to use a 3-legged authentication flow. This ruleset provides a recommendation which will help API providers to align on the 3-legged flow and help with aggregation. 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

Additional context Please see TSC meeting minutes.

In https://github.com/camaraproject/PopulationDensityData/issues/24#issuecomment-2151943496 @eric-murray raised the point that the openIdConfigurationUrl can point to different metadata. Using that an API could point to a CIBA-metadata or to a OIDC-metadata or to a metadata that contains both.

[AxelNennker]

Maybe it would help if ICM provided example openid metadata configuration and CIBA metadata configuration for Camara API's to choose from

e.g. one that supports authorization_code AND ciba

{
  "issuer": "https://az.example.com/openid",
  "subject_types_supported": [
    "public", "pairwise"
  ],
  "jwks_uri": "https://az.example.com/openid/jwks",
  "authorization_endpoint": "https://az.example.com/authorize",
  "token_endpoint": "https://az.example.com/token",
  "userinfo_endpoint": "https://az.example.com/openid/userinfo",
  "response_types_supported": [
    "code",
    "id_token token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "urn:openid:params:grant-type:ciba"
  ],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "claims_parameter_supported": false,
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "require_request_uri_registration": false,
  "frontchannel_logout_supported": false,
  "backchannel_logout_supported": false,
  "mutual_tls_sender_constrained_access_tokens": false,
  "backchannel_token_delivery_modes_supported": "poll",
  "backchannel_authentication_endpoint": "https://az.example.com/ciba/bc-authorize",
  "backchannel_authentication_request_signing_alg_values_supported": "RS256"
}

@eric-murray suggested API-specific metadata. So, the API could express support for the supported flows by pointing to an API-specific metadata configuration.

[MarkCornall]

The "How do you inform what you support" is important but my concern is as much about a standard "Thou shalt support" specific call out in the API groups that will then inform the operators what they must support.

[AxelNennker]

Hi @MarkCornall,

the "thou shalt support" would be in 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.

And then in the section "Technical ruleset for the Frontend flow". And then in the section "Technical ruleset for the Backend flow".

Comments on documentation/CAMARA-API-access-and-user-consent.md are very welcome. ICM (@jpengar and @sebdewet ) will pick your question up.

[jpengar]

Let me refer you to the ICM documentation:

CAMARA guidelines define a set of authorization flows which can grant API Consumers access to the API. Which specific authorization flows are to be used will be determined during the onboarding process, happening between the API Consumer (the direct API invoker) and the API producer exposing the API. When API access for an API consumer is ordered, the declared purpose for accessing the API can be taken into account. This is also being subject to the prevailing legal framework dictated by local legislation and eventually also considers the capabilities of the application (frontend and backend) ultimately involved in the API invocation flow. The authorization flow to be used will therefore be settled when the API access is ordered. The API Consumer is expected to initiate the negotiated authorization flow when requesting ID & access tokens. The AuthZ server is responsible to validate that the authorization flow negotiated between API Invoker and API producer for this application, purpose, API/data scopes is applied.

Ref: https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#camara-api-specification---authorization-and-authentication-common-guidelines

ICM has defined a "generic" security scheme that provides the flexibility to support any of the defined flows (Auth code, CIBA or Client Credentials) to access CAMARA APIs. In this way, the API specification remains generic and the technical specification of the API is completely decoupled from local regulations, legal decisions, definition of specific application use cases and so on...

So the allowed authorization flow(s) will be determined at onboarding time, taking into account all those context variables that have been decoupled from the API spec. IMHO, technically speaking, a CAMARA-compliant operator must be aligned with the CAMARA ICM Security and Interoperability Profile (which among other things defines Client Credentials, Auth Code and CIBA as the Auth flows used by CAMARA). I understand that this issue is coming from GSMA because of Opengateway scenario. So, if then an operator is allowed to be onboarded in Opengateway implementing only one of the auth flows because (say) that operator only exposes one API and that API only requires this specific auth flow... for me personally, that is a business decision of Opengateway and not a technical decision of CAMARA ICM nor CAMARA API subprojects. (*)

(*) NOTE: There may be exceptions of specific API subprojects that restrict the auth flow to use among those defined by CAMARA ICM due to the functionality provided, e.g. Number Verification API that necessarily requires to use the auth code flow.

As mentioned by @AxelNennker, the ICM also defines...

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.

...which is the criteria to decide whether client credentials (2-legged) is allowed or not. Or the other way around, when 3-legged access becomes mandatory. This MUST be followed by all APIs.

And finally, if during the onboarding process of a specific application, in a specific country, under a specific local regulation, it is determined that more than one auth flow is allowed, say Auth Code and CIBA as @MarkCornall mention... then the application developer will decide which auth flow to use depending on its particular use case or capabilities, e.g. Auth Code and CIBA allowed, application with no FE capabilities then CIBA will be used and the developer will develop its use case accordingly. For this the ICM also provides recommendations in a technical ruleset for Auth Code and CIBA as also mentioned by @AxelNennker above.

[eric-murray]

For APIs that may need to support 3-legged token access, I agree that a clear statement in the documentation as to whether the authorisation code flow, CIBA flow, or both could be applicable would be useful, and CAMARA should start to enforce that.

Given that CIBA allows the end user to be identified by IP address and port, and this should be known to any application server contacted by the end user device, I suspect that many APIs will find that authorisation code flow does not need to be supported at all. Even Number Verification would work using CIBA, though I understand that authorisation code flow and header enrichment is the traditional way of identifying the end user device.

Discovering that most APIs only require to support one of the 3-legged flows would greatly simplify things. The API consumer would then find out when on-boarding whether a 3-legged token was required for legal reasons, or a 2-legged token could be used. But the API provider would already know this, and hence would only need to implement one of the possible authorisation flows. And if only one flow is applicable, it does kind of become mandatory.

For the existing implementations "out in the wild", I'd be interested to know how many found it necessary to implement more than one authorisation flow.