Provide API Design guidelines for OAuth2 client credentials

[AxelNennker]

Problem description There are Camara APIs that do not involve personal data and by specifying the openid-security-scheme in the API yaml file API consumers are missing important information. If no personal data is processed then an OAuth2 client credentials security scheme is what API consumers should find in the API yaml file.

There is currently no guideline for API designers how to specify OAuth2 client credentials.

The following are two Camara APIs that do not involve personal data: https://github.com/camaraproject/PopulationDensityData/blob/main/code/API_definitions/population-density-data.yaml @jgarciahospital https://github.com/camaraproject/QualityOnDemand/ especially https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qos-profiles.yaml @jlurien @eric-murray

Expected action Provide a guideline for API designer on how to specify a security scheme that allows OAuth2 client credentials.

https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qos-profiles.yaml is currently using this security scheme

components:
  securitySchemes:
    oAuth2ClientCredentials:
      description: |
        The QoS Profiles API makes use of the OAUTH 2.0 client credentials grant which is applicable for server to server use cases involving trusted partners or clients without any protected user data involved. In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.example.com/oauth/token
          scopes: {}

Additional context

TSC agreed on October 19, 2023 :

Update OpenAPI security guideline (https://github.com/camaraproject/Commonalities/pull/57)

Agreement to use openId connect discovery clause in the Open API Specification (OAS) and provided API scheme for the API in another form (either in seperate file or as documentation section within the OAS).
Documentation must also list possible security schema for the APIs.
[Action] Telefonica will propose a wording.
We need also to check how security schema are managed in 3GPP
Tanja De Groot provided following links: [3GPP 5G APIs](https://forge.3gpp.org/rep/all/5G_APIs), esp. [TS29122_CommonData.yaml](https://forge.3gpp.org/rep/all/5G_APIs/-/blob/REL-18/TS29122_CommonData.yaml)
Shilpa added the following specific link: [TS24558_Eees_EASDiscovery.yaml](https://forge.3gpp.org/rep/all/5G_APIs/-/blob/REL-18/TS24558_Eees_EASDiscovery.yaml)
Voting in Commonalities and ICM groups: as their decisions affect many other working groups, discussions needing a voting should be escalated to TSC.Update OpenAPI security guideline (https://github.com/camaraproject/Commonalities/pull/57)

Agreement to use openId connect discovery clause in the Open API Specification (OAS) and provided API scheme for the API in another form (either in seperate file or as documentation section within the OAS).
Documentation must also list possible security schema for the APIs.
[Action] Telefonica will propose a wording.
We need also to check how security schema are managed in 3GPP
Tanja De Groot provided following links: [3GPP 5G APIs](https://forge.3gpp.org/rep/all/5G_APIs), esp. [TS29122_CommonData.yaml](https://forge.3gpp.org/rep/all/5G_APIs/-/blob/REL-18/TS29122_CommonData.yaml)
Shilpa added the following specific link: [TS24558_Eees_EASDiscovery.yaml](https://forge.3gpp.org/rep/all/5G_APIs/-/blob/REL-18/TS24558_Eees_EASDiscovery.yaml)
Voting in Commonalities and ICM groups: as their decisions affect many other working groups, discussions needing a voting should be escalated to TSC.

PopulationDensityData was created in December 2023 after the TSC agreement. QoS Profiles was split from QoS also after the TSC agreement.

I, @AxelNennker, think the TSC agreement should be re-visited because now we have Camara API that are client-credentials only. There should be a guideline for API Designers in API Design guidelines how to specify oauth2 client-credentials in API yaml files. API consumers would miss important information in the yaml files if the read the openid-security scheme in the API yaml file, but in fact the API requires client credentials.

[eric-murray]

There is an existing PR that will update the security scheme for the QoS Profiles YAML. This will use the openId scheme that is mandated by ICM, and the oAuth2ClientCredentials scheme deleted.

This scheme allows for the QoS Profiles endpoints to be called with either 3-legged or 2-legged access tokens - both are valid scenarios. The additional documentation that will be added to the OAS explains exactly how the API designer will find out the details of the applicable authorisation schemes, specifically: Which specific authorization flows are to be used will be determined during onboarding process

So they will find out which authorisation flows are applicable via the Operate APIs, with the details (endpoint URLs, supported endpoint authentication methods, supported scopes, etc.) found via the openIdConnectUrl.

[AxelNennker]

I saw the PR but no documentation of the API behavior you describe in the above comment. The yaml does not describe this behavior and that is where developers look.

Anyway, as long as there is one Camara API - population density - that is client credentials only, then there should be API designer guidelines on how that security scheme should be specified in the yaml.

[eric-murray]

The solution adopted by ICM was clear - developers (i.e. API consumers) will not know which authorisation schemes are applicable to an API until the onboarding stage. That is what is specified in the mandatory template to be included in each API. No more text is required, though anyone is free to propose additional documentation in the OAS itself.

The ICM "CAMARA API Access and User Consent Management" document already describes how client credentials are specified in the OAS. OIDC Discovery already allows additional grant types (such as client_credentials) to be specified in the openIdConnectUrl data.

[AxelNennker]

The solution adopted by ICM was clear - developers (i.e. API consumers) will not know which authorisation schemes are applicable to an API until the onboarding stage. That is what is specified in the mandatory template to be included in each API. No more text is required, though anyone is free to propose additional documentation in the OAS itself.

There are APIs that are client credentials only and I think their openapi yaml files should express that. Therefore there should be an Camara guideline for oauth2 client credentials. https://github.com/camaraproject/IdentityAndConsentManagement/pull/172

[AxelNennker]

After DT-internal discussion closing this issue.