[RCP-46] Add Support for OAuth2 Refresh Tokens

[darnjo]

Discussed in #82

^{Originally posted by darnjo April 18, 2023}

Background

One of the primary use cases for the RESO Web API is machine-to-machine transfer of information, such as replication or webhooks. It is not practical for auth to require human interaction in these scenarios.

Data producers and consumers need to be able to automate the transfer of data in order for it to be manageable at scale. Consider the case of 500+ markets and wanting data no older than 10m.

For this reason, either OAuth2 Bearer tokens and/or Client Credentials are required for the current RESO Web API Endorsements, as well as Data Dictionary.

However, there are improvements to security that can be made to Web API auth mechanisms given that long-lived bearer tokens are not a best practice in many settings. More info on access tokens and lifetimes.

Proposal

In addition to Bearer Tokens and Client Credentials, OAuth2 supports a feature called "refresh tokens," which allows providers to issue short-lived bearer tokens be able to expire, as needed, with the ability for a client to request a new access token in an automated manner.

A summary of the workflow with examples is shown here.

The proposal would be to add refresh tokens as a third, machine-friendly auth option in cases like the RESO Web API and Webhooks, as well as APIs that support RESO Common Format.

[darnjo]

@bryanburgers, maybe you'd like to pair on writing a spec for this?

[bryanburgers]

I'll pass, but thank you for the offer!