Authentication mechanism

[wetneb]

This is a proposal for the authentication mechanism proposed on the mailing list: https://lists.w3.org/Archives/Public/public-reconciliation/2019Jul/0010.html

This proposes to use GET parameters, however I am not sure this is a good idea. Since we also use POST requests, this would mean submitting the api_key as a GET parameter to a POST request, which is not very natural (and not very easy to do with many HTTP libraries).

Authentication in GET parameters also has the downside that authentication is leaked in logs.

The motivation for GET was that it was easier to debug requests in a web browser, but browser-based testing will not be doable anyway if we move to pure JSON batches submitted by POST (#32).

I would propose to use a header instead, such as X-API-Key suggested by Swagger: https://swagger.io/docs/specification/authentication/api-keys/

Closes #26.

[thadguidry]

I still think that Authentication can be left out of the Reconciliation-API specs itself, and instead approached with a Recommending or Guideline instead? Something how Google or Mozilla or Owasp approach this? It should be up to the Services themselves to determine how critical their "Authorization" needs are in response to "Authentication". OAuth 2.0 might be more preferred for providers that need to apply limits against particular resources, and since OAuth 2.0 combines both Authentication and Authorization, this becomes somewhat easier. Bearer tokens (API keys) might be preferred by others for simple identity lookups because they service only 1 resource type. Basic digest might be fine if someone is just trying to implement simple throttling of users on their own VM.

In other words, I don't think the Reconciliation-API specs should dictate which common API authentication mechanism can be used, HTTP Basic, API Keys, OAuth 2.0 , but instead educate providers/developers about them and point to external resources for security awareness. Stuff like this: https://cybersecurity.ieee.org/blog/2016/06/02/design-best-practices-for-an-authentication-system/ and others from Google, Mozilla, Owasp, etc.

[wetneb]

I still think that Authentication can be left out of the Reconciliation-API specs itself, and instead approached with a Recommending or Guideline instead? Something how Google or Mozilla or Owasp approach this?

In that case I don't see how to add support for authentication in OpenRefine. What would the user experience look like?

[thadguidry]

Ah, for OpenRefine, that's a client that's conforming to the Reconciliation-specs. A client would/should understand how to parse objects from the OpenAPI JSON or YAML returned, in particular a Security Requirement Object object and any provided securitySchemes. Then with that metadata knowledge a client could offer a UI or Config message to prompt and store the required values needed from the chosen Security Requirement Object.

In other words, I could discover how to generally interact with a Reconciliation service by querying its OpenAPI root document that describes its capabilities

Is OpenAPI really required?

• No

Is OpenAPI a good idea?

• Absolutely Yes

What does the above do for Reconciliation service providers?

• It puts a bit more work on Service providers to describe the Reconciliation service with OpenAPI specs.
• It benefits providers, because there is a machine readable way to describe the service parameters, security, etc. and generate documentation for the service.

What does the above do for Reconciliation clients?

• It allows them to easily discover the capabilities of the Reconciliation service and config their client accordingly (even auto config if the clients were programmed accordingly).

What does the above do for OpenRefine client?

• Makes our job a bit harder :)
• Helps with some of the other issues of how to describe the API for various parts (parameters, scoring, options, etc)
• Allows understanding of Reconciliation service offerings to generate a comfortable UI for the user
• The UI for Reconciliation in OpenRefine could be designed with tabs or list menus that appear as necessary with forms to fill or configure that are generated based on querying the OpenAPI root doc from the Reconciliation service.
• OpenRefine Recon column support could be enhanced with additional handling beyond the defaults now based on discovery of the OpenAPI object data. (scoring options, more parameters, etc.)

There's implementations in all major programming languages for OpenAPI. Some folks may view OpenAPI as unnecessary, but it solves many of the problems of knowing the capabilities and settings of the Reconciliation endpoint for clients like OpenRefine to make the user experience that much easier. I.E. a bit more pain on both client/server sides, in order to make users happier and reduce their pain.

[wetneb]

In other words, I could discover how to generally interact with a Reconciliation service by querying its OpenAPI root document that describes its capabilities

Ah ok, that's a more precise proposal then. That would mean adding support for the following authentication mechanisms:

• apiKey: that is what was discussed earlier and what this PR proposes
• http: basic HTTP auth
• oauth2: probably quite painful to implement and to use (since users would need to obtain OAuth client ids) but could be useful for hosted reconciliation client;
• openIdConnect: potentially a bit easier to use if endpoints support dynamic client registration…

It would be pretty involved to support all this in clients, but why not.

[thadguidry]

Is that a "strong" why not, or "casual" ? :) I'm not an authority here, just giving my thoughts. Tony also had some ideas when he and I talked about Swagger and OpenAPI stuff sometime last year, so I just threw up some of what I remembered he said (I was learning more at that time, still am). You might ping him on his email also, if you need to.

[wetneb]

It's a "why not" that depends on what other people think! :) If we are borrowing more and more concepts from OpenAPI, we might want to do a big overhaul of the entire specs to make it fit in that model (#17, #32, #33 and probably many other aspects we haven't thought about). It is a bit of work and likely to create a backwards-incompatible spec in many ways. But it might well be worth doing.

[thadguidry]

Ok, yeah my exact thoughts as well...might be worth the pain.