Provide a plugin mechanism for authentication

[danballance]

Providing a means for the client to authenticate against an API endpoint is an important requirement for many consumers. This issue proposes the development of a plugin system for handling client authentication.

As was mentioned in #114 there are a few important topics to consider:

1. What set of auth policies might we need to support?
2. What does an example auth flow look like?
3. What information does the scheme itself need to present in order to make that possible?

[danballance]

A couple of initial comments on these three aspects follow:

1. What set of auth policies might we need to support?

HTTP basic, HTTP digest, OAuth2 and JWT would all be nice to haves (eventually)

2. What does an example auth flow look like?

These can be pretty varied. As an example I'm currently using Oauth2 password flow, there's a simple diagram here: here.

3. What information does the scheme itself need to present in order to make that possible?

The difficulty will obviously be trying to make this work across different API schema formats - so possibly these authentication plugins might need to work in tandem with a schema being used? So you might need to have an OAI-Oauth2 plugin? I don't know your code too well (yet) so it's hard for me to suggest a good way to do this. I'll try and dig in a bit deeper this week.

[danballance]

I've just looked through the code for our Guzzle-based PHP client that uses the OAuth2 password flow. We have a sequence of steps that run roughly like this:

1. Look at cache for a valid token
2. if no cached token, then POST an application/x-www-form-urlencoded form to the authorization endpoint to retrieve a new the token
3. cache the token
4. send the request with the obtained token as a Bearer HTTP header

Obviously this is just one kind of flow and the plugin system would need to be flexible enough to handle a range of different scenarios. I guess we shouldn't try to be too prescriptive and instead give the authentication plugin pretty much free rein to do whatever it needs in order to set up the request properly for authentication.

We may also need some kind of hook that can detect a 401 error and then try to get a new token and re-send the request. This commonly happens when a locally cached token is believed to be valid but the endpoint has decided that the token has expired. In these scenarios it's nice if the client is able to handle all of this internally and re-try with a new token without returning an authorisation error to the calling code.

[tomchristie]

We do have support for custom auth schemes now.
Needs proper documentation, and it doesn't handle auth flows.
Let's close this for now and reopen after 3.0 if it's clear that we're missing a trick.