Web-based authentication integrations in Pugpig apps using PKCE

The Pugpig platform offers several methods for users to gain access to paywalled content, these include in-app purchases of subscriptions or editions and a native sign-in UI which we can connect to the authentication system of your choosing.

We also know that in some cases customer will have built mature, powerful sign in flows of their own, and the app would be better served by handing off the authentication process to these systems. To cater for such cases, all Pugpig apps now support presenting an externally-hosted web page to conduct the authentication, and then securely passing the result to the app.

Rather than devise a method of our own, our implementation utilises the OAuth 2.0 framework, specifically Proof Key for Code Exchange (PKCE hereafter). This is a security protocol specifically designed for use in mobile apps and is ideally suited to what we're trying to achieve. 

Specifically, our apps will allow a user to:

1. When required, open a web-page hosted at a destination of your choosing
2. Securely verify the validity of the client to the authentication server
3. Conduct an authorisation challenge using the user-supplied login details
4. Interpret the response and subsequently give access to all, none, or a subset of the app's content.

Because of our adherence to the PKCE protocal, Pugpig doesn't maintain a spec or implementation guide for our web-based authentication integrations, instead we'll refer you to the docs detailed below to help guide design and planning. 

PKCE spec. This is the canonical source of truth that our code's expectations are based on, and should serve to detail the necessary server-side configuration: https://tools.ietf.org/html/rfc7636 

OAuth 2.0 PKCE explainer. Details how PKCE fits into the OAuth framework: https://oauth.net/2/pkce 

Frequently-encountered issues:

1. Identity providers which do not support PKCE or through misconfiguration require a client secret. As all Pugpig apps/clients are considered "public" by RFC7636's definition, they cannot contain secrets, and therefore may only use the PKCE flow.
2. Incorrect scope and/or lack of authorising API. The default openid scope is only sufficient only for id_token, which is insufficient for authorising access to content. id_tokens are designed for authentication (who you are) not authorisation (what you're allowed to do). We therefore require a scope which yields an access_token which we can use to query your authorisation API.
3. In order to save users from having to login every time the use the app/reader, we require a refresh_token, either using the standard "offline_access" scope or some other scope. It is also important that the TTL of the refresh token be at least double the mean duration between user sessions. E.g. If you publish monthly, users are likely to read once a month (unless they go on holiday, in which case they might miss a month etc), but they should not be logged out just for missing one publication. Worse still if the refresh tokens last less time than the mean time between publications, then users are likely to be logged out every time they return to their app/client.