What needs to be done to extend OpenAPI security?

[pvretano]

This is a general issues about security and OpenAPI. It was motivated by a problem that @aaime and I have related to generating a parameterized OpenAPI document in a secure environment (although I don't think the problem is isolated to this approach of generating the OpenAPI document).
There is a bit of a chicken and egg situation. The basic problem boils down to this. A client needs to access the /api document in an unsecure way in order to read the security information in the OpenAPI document in order to know how to authenticate to access a WFS. What does the OpenAPI document look like in this initial unsecured access? It cannot be a "normal" OpenAPI document with the normal /collections information since the list of collections (either listed explicitly or as a enum for the {collectionId} parameter) that would appear in the OpenAPI document depends on the user's authentication and authorization in the first place.
Since this seems to be a general problem about OpenAPI and security, I created this issue to track discussion on this topic and specifically looks at how OpenAPI might be extend to better handle the needs of WFS.

[cmheazel]

I would build on the concept described in the OWS Security standard (pending). The unsecured request would receive sufficient information to understand the security controls supported by the service. In a simple case, the OpenAPI document could report support for two Security Requirement Objects. One would indicate support for anonymous access, the other for your selected authentication method. According to the OpenAPI spec, "The Paths MAY be empty, due to ACL constraints." So under anonymous access you would not see any of the details of the Paths objects.

[cportele]

Maybe the server could respond with the generic OpenAPI document at /api, i.e. with {collectionId} as a parameter and not collection-specific filter parameters. To determine the collections available to the authenticated user, she has to login and access the /collections resource.

Of course, a user that is logged in could also get an OpenAPI definition at /api with the explicit collection list and the additional filter parameters supported for each collection.

[cmheazel]

@cportele to keep things simple, the generic OAS document could only advertise the /api path, servers (optional), and security requirements. This is all you need to access a protected OAS document. It is also not tied to WFS so we can use it for any OGC service.

[cportele]

It would be good to understand the typical expectations of developers that access protected/restricted APIs, before we settle on a recommendation. What information is helpful, what is confusing, what information is needed, etc.

[cmheazel]

I'll see if we can put together a survey for our developers. What we can do now is identify the absolute minimum required to boot-strap access to a service. Developers can always add more.

[cmheazel]

See Section 10 of the Users Guide. If that is sufficient, then we will close this issue.