CIBA in Camara OpenAPI yaml files

[AxelNennker]

Problem description Camara API OpenAPI yaml files should list the security schemes they offer or even require e.g. for OIDC and CIBA.

ICM defined a security scheme for OIDC but not for CIBA.

There is an issue in ICM to discuss an OpenAPI security scheme for CIBA.

Solution

After ICM defined an CIBA security scheme Camara API design guidelines should incorporate it into the existing OpenAPI definitions

Note: I, Axel, am speaking here as me not as a ICM maintainer/codeowner/chair. It is Commonalities decision how to write API design guidelines. Commonalities could integrate OpenAPI security schemes into the existing section or move the whole "OpenAPI defintions" sections into a separate document "owned" by ICM.

[jpengar]

Since ICM defines the guidelines for what refers to securitySchemes in API Specs, and considering that this topic has already been discussed and agreed in ICM in the past. I would suggest that this topic be moved to ICM.

[AxelNennker]

I agree. This document describes how a transfer could be done, but it seems I do not have the right permissions to transfer this issue. https://docs.github.com/en/issues/tracking-your-work-with-issues/transferring-an-issue-to-another-repository?tool=webui

So, I am going to create a new in ICM.

[AxelNennker]

I created an issue in ICM https://github.com/camaraproject/IdentityAndConsentManagement/issues/157

[jpengar]

Thanks Axel. I guess we can close this one then.

[AxelNennker]

Thanks Axel. I guess we can close this one then.

I would like to keep the issue for now until Commonalities decides what to do with OpenAPI definitions. Maybe Commonalities decides to add some backlog-label?! There is maybe/probably not enough time to integrate a CIBA security scheme into this release but I think, given the importance of CIBA for telcos, there should be a guideline for API designers on CIBA.

Option 1: I think that OpenAPI definitions should be in one place. Currently OpenAPI Definitions are in Commonalities OpenAPI definitions. Commonalities could incorporate the security schemes agreed upon in ICM. Option 2: I think the OpenAPI definitions are very important for Camara API designers and are big enough and important enough to merit a separate document. IdentityAndConsentManagement/OpenAPI-Definitions.md - maybe Option 3: Put the security schemes into the Camara Security and Interoperablity Profile. Option 4: your proposal here...

Thinking about "release documents", developers and API designers should find relevant information on ONE topic in ONE place not scattered over several documents that link to each other. There should be not too many release documents.

[jpengar]

Option 4: Leave it as it is which IMHO it's more than fine.

I don't see what is the problem with current state. The API-design-guidelines.md document contains "11.6 Security definition" including a reference to CAMARA API Specification - Authorization and authentication common guidelines (CAMARA-API-access-and-user-consent.md ICM doc) which is the official CAMARA ICM document where these guidelines are specified. These guidelines are the result of work done in the ICM and are documented in a document under the ownership of the ICM, which I think is correct. The ICM is the one with the context and background of these decisions and, in my opinion, is the best positioned WG to properly maintain their content.

Thinking about "release documents", developers and API designers should find relevant information on ONE topic in ONE place not scattered over several documents that link to each other. There should be not too many release documents.

@AxelNennker What is exactly the problem of including a reference in API-design-guidelines.md? And why is it a problem in this case and not when references are included in Camara Security and Interoperablity Profile for example? In that case WG supported the decision for a "delta" document approach instead of a self-contained document.

Option 3: Put the security schemes into the Camara Security and Interoperablity Profile.

Why should we move this content from ICM CAMARA-API-access-and-user-consent.md to ICM CAMARA-Security-Interoperability.md? From my perspective, CAMARA-Security-Interoperability.md is actually profiling CAMARA requirements on top of OAuth2 and OIDC standards. But there are other topics previously covered in CAMARA-API-access-and-user-consent.md (e.g. securityScheme guidelines) for a reason.

[AxelNennker]

Option 4: Leave it as it is which IMHO it's more than fine.

I don't see what is the problem with current state. The API-design-guidelines.md document contains "11.6 Security definition" including a reference to CAMARA API Specification - Authorization and authentication common guidelines (CAMARA-API-access-and-user-consent.md ICM doc) which is the official CAMARA ICM document where these guidelines are specified. These guidelines are the result of work done in the ICM and are documented in a document under the ownership of the ICM, which I think is correct. The ICM is the one with the context and background of these decisions and, in my opinion, is the best positioned WG to properly maintain their content.

As I said, I think there is no such thing as "ownership". ICM was founded out of Commonalities because identity and consent is a big enough topic and e.g. the Security and Interoperability Profile is a valuable result of ICM.

OpenAPI Definitions are in Commonalities API Design guidelines in the OpenAPI Definitions section and I think that OpenAPI security schemes should also be there, so that API designers have all OpenAPI definitions in one document. There is nothing agains one document referencing another but, I think, API Designers benefit from having OpenAPI guidelines in one place.

[jpengar]

As I said, I think there is no such thing as "ownership". ICM was founded out of Commonalities because identity and consent is a big enough topic and e.g. the Security and Interoperability Profile is a valuable result of ICM.

Fully agree. But it is a fact that there are different working groups and each of them working and maintaining documents on each github subproject. Please, don't get wrong.

[AxelNennker]

Fully agree. But it is a fact that there are different working groups and each of them working and maintaining documents on each github subproject. Please, don't get wrong.

All's good. We just seem to disagree where the OpenAPI definitions text on security schemes should be. I think it is Commonalities decision, whether to have them in one place where other OpenAPI definitions already are or in an ICM document.

Some view ICM as a subgroup of Commonalities. Whether one shares this view or not, I think that ICM is about Identity and Consent and the API guidelines have on OpenAPI definitions section. The openapi security scheme are in an intersection of OpenAPI definitions and Identity-related definitions.

I propose that Commonalities put the ICM defined OIDC and CIBA (later?) security schemes into OpenAPI definitions. ICM did our work defining them/it, but, I think, it is Commonalities decision where to put them.

[jpengar]

@rartych Now that PR #208 is MERGED and issue 207 is CLOSED. After transferring the issue to ICM https://github.com/camaraproject/IdentityAndConsentManagement/issues/157, I think we can close this issue. CC @shilpa-padgaonkar