Define requirements for OpenAPI FAPI securityScheme type

[Lukasz Jaromin]

The current generic OpenAPI oauth2 securityScheme type is not descriptive enough to accurately convey FAPI security profile requirements.

FAPI is an API security profile and as such should have its own securityScheme type in the OpenAPI specification. It will enable open data ecosystems and other financial-grade API designers to mark APIs that require FAPI SP with the security scheme of such type. It will enable generation of accurate API documentation and clients. It will also likely increase recognition and adoption of FAPI and will make application of FAPI easier.

I envision that in scope of this task, we would generate requirements for the security scheme type and create a proposal for Open API Initiative (OAI) to include this in the specification.

It is to be considered what should be explicitly and implicitly included in the type e.g. scopes, fapi version, allowed flows, RAR authorization_details types, required headers.

[Nat Sakimura]

Do we just need to talk to OAI? What is the process needed? Do we need to create a new document in their format?

[Kosuke Koiwai]

I think having FAPI in the OpenAPI spec also helps CAMARA project to adopt FAPI as their API definitions are also in OpenAPI.

https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#11-definition-in-openapi

[David Hyland]

Hi there - I had a look at this last year, forked the spec and drafted the sorts of changes that I felt were required, using the RAR spec examples
https://github.com/dphhyland/OpenAPI-Specification/blob/main/versions/3.1.x.md
Requires review, and in summary I made the following changes:
- Up the top of the doc I added a new “authorizationDetails” Component
- New the end of the doc in the “OAuth Flow Object” section added a new “authorization_details” field and included a RAR example
- Updated the Security requirement object to allow Auhtorization Details to be listed alongside scopes
- Added an example
- Added a new Authorization Details Object section to describe the RAR payload

Was a quick experiment to see what it would take to drop RAR in … think it works and my edits could use some better examples (i.e. mixing petshop with payments is a bit jarring)
Next steps were to present to the FAPI WB (here we are) with the objective to then present to OAI …