Add Support for OAuth2 Refresh Tokens

[darnjo]

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.

[bryanburgers]

Strong support.

In Zenlist's experience with Add/Edit, MLSes that support OAuth 2 refresh tokens have a much better user experience than MLSes that don't.

By using short-lived access tokens and long-lived refresh tokens, we're able to keep agents logged in to their MLS for a long time, so editing a listing is seamless.

Using only short- to medium-lived access tokens without refresh tokens, agents get frustrated that they need to frequently re-authenticate against their MLS to be able to edit their listings.

[darnjo]

This has been converted to an issue. Please see #107.