Discussion on API access mechanism

[jgarciahospital]

During followup#7, discussion about the usage of 2-3 legged access tokens for this API(s) was raised as AoB.

Offline feedback to be provided.

[jgarciahospital]

As in Follow-up meeting #8, APi is to be considered as 2-legged access token. @bigludo7 is it required any modification in the API spec?

[bigludo7]

As in Follow-up meeting #8, APi is to be considered as 2-legged access token. @bigludo7 is it required any modification in the API spec?

@jgarciahospital I think we are good as we have:

  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration

To be 100% sure adding @AxelNennker to get his feedback

[gregory1g]

I just heard that this QoD PR is the currently expected way to define security schemas: https://github.com/camaraproject/QualityOnDemand/pull/295/files

As far as I understood openID (as in the QoD example) automatically means 3-legged. So, since pplDensity is client-credentials it should not use openID.

Also a purpose and scope must be indicated.

However, my interpretation can be inaccurate.

[jgarciahospital]

OIDC is generally including both options, and it's generically included in the APIs where the option is opened, as the rule that applies depending on each region-regulation is that:

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.

So, up to know, we consider that the generic reference to OIDC is ok for this API, as also it's only considering Scopes (not PI scopes), but I agree that maybe commonalities or Identity&Consent should also consider this situation where the API is never considered as 3-legged at all. If that is finally agreed we can update based on commonalities.

[jgarciahospital]

To be considered in next I&C release as current discussions are already closed. OpenIDConnect is defined as the generic auth, which in this case implies clientCredentials.

@gregory1g @bigludo7 is that ok?

[bigludo7]

@jgarciahospital For me this is OK for this release. We could stick with the 'CAMARA Statement' on this for this API.

[AxelNennker]

Putting some info from camaraproject/IdentityAndConsentManagement#157 here.
Also from camaraproject/IdentityAndConsentManagement#57
And some TSC discussion
And my interpretation of what TSC might or might not have decided on
camaraproject/IdentityAndConsentManagement#157 (comment)

My understanding is that

  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration

is the default security scheme Camara APIs should use. Especially if personal information is involved in the API.

OIDC is a profile of OAuth2 and OIDC does not forbid OAuth2 client credentials.

But, I find that always just specifying openIdConnectsecurity scheme as a security mechanism for an endpoint does not help API consumers e.g. if the endpoint is CIBA or client credentials protected.
Deferring to discovery does not help because the authorization server might support all kinds of flows and does not provide any info which flow is expected at specific endpoints.

There might be endpoints that use CIBA and then an SMS is sent to the authentication device. But a client might reject CIBA because of the user experience. There might be one endpoint that is OIDC protected and a different one that is protected by CIBA.
A Camara API should be able to express that, and an API client should be able to choose the endpoint that fits its expectations on user experience.

If an API or some of its endpoints do not involve user information than OAuth2 client credentials is totally fine and the API should be able to express that.
E.g. this API seems to be client credentials only
https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qos-profiles.yaml
And they define an security scheme for OAuth2 client credentials named oAuth2ClientCredentials.
https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qos-profiles.yaml#L131

Which I think is much more meaningful than using the ICM openid defined security scheme.

I think TSC did not forbid the possibility of defining other security schemes. I think that TSC decided that for now discovery is the way to go for OIDC.

I want to state that I fully support the decision to use the openid security in all APIs and endpoints that involve personal information.
BUT if an API endpoint is CIBA protected then the API yaml should express that, and if an endpoint is client credentials protect (hopefully not involving personal data) then the API yaml should express that. And most importantly be transparent to the API consumer.

[gregory1g]

I do agree with @AxelNennker. We have discussed and agreed that this API must be exposed using client credentials - this design decision must be documented in the API.

[jgarciahospital]

Since I&CM group is not considering it, I'd prefer to stick in the current official WoW which is still generic OIDC, waiting for the next guidelines in the next meta release.

Proposal is then to maintain current generic OIDC and adapt for following version, when I&CM and commonalities are clearer on this topic.

[AxelNennker]

@jgarciahospital
I see it as a step back if e.g. qos_profiles.yaml would remove their oAuth2ClientCredentials security-scheme definition just to be compliant with the API Design Guideline. API Consumers would loose information.

I do not see a problem with adding e.g.

    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.example.com/oauth/token
          scopes: {}

Whether or not client_credentials is allowed for a client is decided/granted at onboarding time. I would like to keep these onboarding concerns out of these technical documents.
I am a strong supporter for OpenId Connect when personal information is involved.
But I think the API Design Guidelines should include guidelines for client_credentials if an API, like qos-profile, needs client_credentials. The information about the grant types should be in the technical documentation for API consumers like the yaml files. I think uniform security schemes are valuable and that API subgroups should not each invent their own security scheme, but I think it makes no sense to force API subgroups to use one security scheme that does not fit their needs.

[jgarciahospital]

@AxelNennker while I understand it, I'm not comfortable modifying current version while there is not common agreement apart from the generic OIDC profiling. As soon as there is a mandate coming from TSC, I&CM or commonalities, we'll adapt as in any other required rule, but up to now I still suggest to maintain ourselves aligned with the current rules (of course, not asking other APIs to do the same).

[AxelNennker]

I am suggesting to add an oauth2 security scheme to Camara guidelines.
camaraproject/IdentityAndConsentManagement#171
I think it is easy enough. I do not see the problem with adding a guideline on "your" security scheme oAuth2ClientCredentials. I am trying to get a guideline on oauth2 client credentials into Camara guidelines, so that APIs like PopulationDensityData can specify what it needs. Would be nice if you support this effort.

[jgarciahospital]

Thanks Axel, we'll take a look on the proposal. When it gets clarified and agreed, we'll adapt this API and any other affected accordingly.

[AxelNennker]

Thanks Axel, we'll take a look on the proposal. When it gets clarified and agreed, we'll adapt this API and any other affected accordingly.

Please chime in not only here but in the discussion in ICM and Commonalities.
At the time when TSC agreed to go for openid discovery, I think we did not have client-credentials-only APIs and I would like TSC to revisit this agreement. I do not even remember what the problem was that let to the ICM decision to mandate openid-only.

Do you or somebody else recollect?

[AxelNennker]

After DT-internal discussion we decided not to re-visit the TSC agreement from December.
So, the probably to be release guideline is that API have one security scheme and that is openid.

[jgarciahospital]

As discussed in Followup#9, API code is not to be modified, as following guidelines of I&CM of generic security scheme of OIDC, but documentation (as note) will be included to clarify this exact case (2-legged as no personal information).

[eric-murray]

@AxelNennker

Deferring to discovery does not help because the authorization server might support all kinds of flows and does not provide any info which flow is expected at specific endpoints.

You appear to be making an implicit assumption that an API provider can only provide a single OIDC discovery URL that is common to all APIs. I didn't think that was the case - I see no reason why the openIdConnectUrl‎ cannot be API specific, given that it is separately specified in each YAML.

So an API provider could specify:

openIdConnectUrl: https://api.developerportal.com/camara/population-density-data/.well-known/openid-configuration

In this case, the configuration would only list client_credentials within grant_types_supported, and the potential API consumer would then know what was expected of them. Whilst an API consumer (i.e. developer) would only get final details of authorisation scheme when they are onboarded, they could check this public discovery document in advance (should the API provider publish them separately in this way) without directly contacting the API provider.

[AxelNennker]

@AxelNennker

Deferring to discovery does not help because the authorization server might support all kinds of flows and does not provide any info which flow is expected at specific endpoints.

You appear to be making an implicit assumption that an API provider can only provide a single OIDC discovery URL that is common to all APIs. I didn't think that was the case - I see no reason why the openIdConnectUrl‎ cannot be API specific, given that it is separately specified in each YAML.

So an API provider could specify:

openIdConnectUrl: https://api.developerportal.com/camara/population-density-data/.well-known/openid-configuration

In this case, the configuration would only list client_credentials within grant_types_supported, and the potential API consumer would then know what was expected of them. Whilst an API consumer (i.e. developer) would only get final details of authorisation scheme when they are onboarded, they could check this public discovery document in advance (should the API provider publish them separately in this way) without directly contacting the API provider.

I know that. You could even go further and, an API with several endpoints could even have an endpoint-dependent meta-data url

openIdConnectUrl: https://api.developerportal.com/camara/population-density-data/retrieve/.well-known/openid-configuration

The text in https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#use-of-openidconnect-for-securityschemes is this:

The value for openIdConnectUrl in the CAMARA spec is an example, that must be substituted by the specific discovery endpoint for OIDC protocol of the API provider, when the API is exposed in one of its environments.

Which makes the assumption that openIdConnectUrl is the discovery endpoint of the API provider.

In Keycloak the Camara admin would then need to create a separate realm for each API, I think.
Or we host the openid-configuration somewhere else.

The ICM guidelines mandate that there is exactly one security scheme.
Specifying different security-schemes for endpoints is not possible. Maybe that use-case does not exist. Who knows?!

I think, that specifying different discovery URL whether OIDC or CIBA or client credentials be used is a hack.

If you think this is the way to go then we should have guidelines regarding this in ICM https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#use-of-openidconnect-for-securityschemes

[eric-murray]

I think, that specifying different discovery URL whether OIDC or CIBA or client credentials be used is a hack.

That wasn't my proposal at all. The proposal is that the discovery endpoint be API specific (not authentication scheme specific). If an API implementation supports or requires multiple authentication schemes, then the discovery endpoint for that API will list all of these.

[jgarciahospital]

@AxelNennker @eric-murray I think this is a pretty interesting discussion that should be handled in a broader forum than PopulationDensityData API. Can you please continue the conversation in an ad-hoc issue in I&CM?

[AxelNennker]

@AxelNennker @eric-murray I think this is a pretty interesting discussion that should be handled in a broader forum than PopulationDensityData API. Can you please continue the conversation in an ad-hoc issue in I&CM?

I created camaraproject/IdentityAndConsentManagement#176 in ICM after the TSC meeting.
We can discuss the various aspects there. Both technical aspects like discovery-url in THE security-scheme, and guidelines for API designers and API consumers and Telcos who implement an authorization server.

[jgarciahospital]

Thanks @AxelNennker

As agreed during Population Density Meeting for this APi version:

• Not modify security schema in the API code, as no different guidance in I&CM group is determined apart from OIDC
• Include clarification text in API documentation, establishing that the usage of this API is determined by CAMARA rules, in this case 2-leggged as no personal data is treated.

#30 includes such changes