Setting the Stage for the New OAuth Discovery Protocol

OAuth Discovery PreviewIf you like the new direction discovery is taking, you can give the credit to the original work on OAuth discovery. My first attempt at defining a discovery framework for OAuth over a year ago was a highly complex spec that confused more than it helped. But it identified the need for a simpler profile of XRDS, and so, the second draft of OAuth discovery introduced XRDS-Simple.

Problem was, while it was simpler, it wasn’t simple.

The work on XRDS-Simple exposed some basic flaws in the overall architecture. These are being addressed head-on with XRD. Yesterday I started sharing how the new discovery framework can be applied to OpenID. Now it’s time to take a look at the original use case: OAuth.

The requirements for OAuth discovery include:

  1. A way for clients to find out how to obtain token credentials when receiving an HTTP 401 Unauthorized response.
  2. A document format for storing OAuth configuration used for online discovery, as well as a static configuration file.
  3. A framework to enable extensions interoperability by providing a way to declare support for them.

The problem with the first two drafts was the coupling of the OAuth provider with the protected resource. The boundaries between the description of the protected resource and the description of the OAuth endpoints were blurred. In OAuth, when the client is denied access to a protected resource, it has to go and interact with some other entity to obtain the needed token credentials.

In many cases today, that entity is the server hosting the resource, but in large systems, this can be another server dedicated to issuing tokens. This is the approach taken by Yahoo! and Google with their centralized security facilities. While this is merely a deployment choice (an implementation detail), it actually exposes the separation of roles within OAuth discovery.

The new OAuth discovery process introduces the concept of an OAuth Provider (different term from Service Provider). The OAuth Provider is the entity clients interact with to obtain authorization from the resource owner, and request tokens to access resources. It is the OAuth Provider that “owns” the various endpoints used in performing the OAuth redirection flow, or other new methods to obtain tokens in the future.

The way OAuth discovery should work, is that protected resources simply indicate who their OAuth Provider is. The client performs discovery on the OAuth Provider URI (which is not to be confused with the URIs listed in the OAuth Core 1.0 specification) to find out about its configuration, what methods it supports for getting a token, and its various endpoints.

The resource identified by the OAuth Provider URI does not play a direct role in the discovery process, only its XRD descriptor. It may however, offer a human readable HTML page providing its documentation as is currently the practice by many providers. It is almost as if the OAuth Provider is an abstract identifier.

Ready to see what this looks like?