Wednesday, March 21, 2012

What has changed in the OAuth 2 drafts?

The current OAuth 2 draft is #25, the Google Developers page links to #22 and the Facebook Developers page to #12. While I have yet to use their OAuth 2 enabled APIs I cannot confirm whether their implementations match the drafts they link to.

Now, as an eager contributor to OAuthLib, the logical next step after the OAuth 1 features are stable is to progress to OAuth 2. The second version is much simpler to use as a consumer since the need to sign every request has been removed. However, implementing a provider, especially one supporting all of the many new workflows, is a daunting task. OAuthLib will make consuming OAuth 1 & 2 very simple yet flexible and intend to do the same for services wanting to give access to their APIs using OAuth. Since the first version is quite restricted in how it may be used creating an OAuth 1 provider is not extraordinarily challenging. This is not the case for OAuth 2.

Meet the social toaster. It will make an authorization request, followed by grilling a verification url onto your slice of bread, you type this on any device capable of running a web browser, authorize access upon which you are presented with a code. Using the switch on the side of the toaster and your newly brushed up Morse code skills you enter the code, the toaster downloads your preferences from a database and proceeds to scorch the Skyrim logo onto your second slice of bread. OAuth 2 has evolved from a reasonably simple redirection based protocol into a very flexible protocol for doing just about anything you can imagine, if it is not already in the spec you can create an extension.

Creating intuitive features that addresses all these different workflows and possible extensions is hard. To get a feeling for how difficult it might be I set out to compare the specifications used by two major vendors, Google and Facebook, with the current version. What follows is a very brief and incomplete summary of the changes found from quickly melding the drafts against each other and skimming over the 60+ pages spec, twice. I have omitted references to the changes but if interested I can dig them up.

Differences between draft #25 (Current) and #22 (Google):
  • Stronger focus on the need to use TLS for all interactions, preferably 1.2
  • Applications using multiple client types must register each of them as an independent client
  • Providers must support HTTP Basic Authentication 
  • Providers should fail requests with a missing scope parameter if no default scope parameter has been previously set, usually in the client registration
  • Providers must inform a client if the scope for a authorization grant differs from the requested or default scope by including the new scope in the response as a scope parameter
  • Stresses that the scope and state parameters should not include sensitive information
  • Providers must generate tokens which probability of being guessed is less than 2^-128 and should have a probability of at least 2^-160
  • There were a large number of minor changes to the text. 

Differences between draft #25 and #12 (Facebook), in addition to those between #22 and #25:
  • Substantial differences in wording with a lot of added clarifications
  • Tokens were described as "an identifier used to retrieve the authorization information, or self-contain the authorization information in a verifiable manner" which has been removed. Tokens should be random, non guessable sequences of alphanumeric characters. 
  • New authorization and access token response error types have been added ( "server_error" and "temporarily_unavailable", "invalid_client" has been removed.
  • Redirection URI must now be absolute, 3.1.2
  • Added section 9, Native Applications
  • Added section 10, Security, including the subsections:
    • Client Authentication
    • Client Impersonation
    • Access Tokens
    • Refresh tokens
    • Authorization codes
    • Authorization code redirection URI manipulation
    • Resource owner password credentials
    • Request confidentiality
    • Endpoints authenticity
    • Credentials guessing attacks
    • Phishing attacks
    • Cross site request forgery
    • Clickjacking
    • Code injection and input validation
    • Open redirectors
  •  Updated section 10 to section 11, IANA Considerations

Expiration dates for the drafts are as follows:
  • #25: September 9, 2012.
  • #22: March 25, 2012.
  • #12: July 25, 2011

This quick study shows that even with as much as 13 versions difference, with large amounts of text being modified, the changes made that directly impact implementations are small. From #12 to #25 the biggest change has been the addition of two error types and the removal of one. From this we can conclude that it is reasonable to implement support for OAuth 2 in OAuthLib as only minor changes might be required as the draft evolves into a RFC.