Add mechanism to indicate token refresh is needed

[mike-marcacci]

The scopes of a self-contained authorization tokens (such as JWTs) are intrinsicly limited to a snapshot of available scopes taken at the moment of token creation.

This currency limitation is frequently discussed in the context of token revocation, but is much less considered in cases that require limitation or expansion of a token’s scopes.

We will very quickly encounter both of these scenarios in our architecture, so it’s important that we understand the challenge here and establish a pattern for dealing with it. While these scenarios are rare in a read-only environment, they seem pretty easy to encounter while performing mutation operations that span multiple resources.

The problem...

1. A user has the ability to create new test customers in the production system, but does not generally have the ability to make changes to production customer accounts.
2. She uses a tool to create a new test customer. The tool:
3. Ensures her token can someapi.prod:v1.demo.customer:create
4. Creates the new customer in the accounts resource using its service token
5. Adds new administration scopes to the “demo account admin” role using its service token

At this point, the user should have access to the created customer account, as reflected in subsequent queries (even within the same request); however, because the token is self-contained this will not be the case.

Internal workarounds...

Before the tool makes any such changes, it must ensure that the token provide by the user contains the scope:
authx:v2.authorization..(authorization_id).(client_id)..(grant_id)..(user_id):r..r.r.
It can then perform steps 1 through 3 above, adding a 4th: get a new token from the same authorization for use in subsequent requests to resources.

Workarounds between the tool and the client...

There is currently no standard mechanism to inform the client that it must refresh its token while still conveying a successful request (a 401 could be used to force a refresh, but this would convey a failure of the request). We should consider reusing the WWW-Authenticate header to indicate the need for a refresh alongside the successful response. The AuthX proxies can look for this and purge their cache.