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. 

Some example providers we've used in the past are:

• Auth0
• Piano
• Microsoft B2C
• Custom OIDC implementations (which all support OAuth 2.0)

This document explains what information you need to give to us, and what we need to supply to you. Note that the location you get this information, or configure your provider will differ based on your providers. Please refer to their documentation on details for this.

There is also an explainer of how it all works.

What we need from you

Important: We prefer to transmit sensitive details a secure way. We use Keybase (https://keybase.io/) and our user is pugpig. However, note that by design, using PKCE, nothing below needs to be considered sensitive except maybe the test users. If you even have a client secret, then by definition you aren't using PKCE.

• Client ID - normally one client ID per platform although some providers allow on client ID with multiple callback URLs
• Auth HTML page - the HTML page that displays the login/register screen, and an optional parameter specifying if the default is login or register e.g. https://www.acme.com/login.html?state=register
• Token endpoint - the standard OAuth 2.0 endpoint : https://www.acme.com/oauth/token
• PugPig Test Users - in order to test the flows, you need to provide us a user that covers every case you wish us to test (e.g. inactive, active with some permission, active with different permissions, etc)
• Entitlement specification - The details for the entitlement logic once we have the access token - this can be very custom. Although we do not recommend it, some clients will grant access based on just the access token. See Common Pitfalls. 

Note that you will still need an Authentication Pack - all the details are here: https://pugpig.zendesk.com/hc/en-us/articles/360003980897-Pugpig-Authentication-Setup-Pack

The only difference is that the sign in call will be handled using OAuth, not via an API call.

What you need from us

You will need the callback URLs that need to be configured in your provider. The callback URLs are usually of the form below. If you do not know your bundle ID/package ID or vanity domain, please let us know:

iOS: bundle.id://authcallback/ (e.g. com.acme.app://authCallback)
Android: package.id://authcallback/ (e.g. com.acme.app://authCallback)
Web: https://webreader.vanity.root.url/ (e.g. https://reader.acme.com/)

What is OAuth 2.0 with PKCE

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 protocol, 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.
4. Not having a separate entitlement call - if you used Claims Based Authorisation (e.g. you do not hit anything endpoint) the granting or revoking of access with take as long as the token TTL, or might even require the user logging in again. This is not recommended!