OAuth Core 1.0 Reborn

OAuth Shine First, a few disclaimers. This is the unofficial work of a single individual (me), not a community endorsed specification. While it is a significant improvement over the official OAuth Core 1.0 specification (if I may say so myself), there is only one OAuth Core 1.0 specification, and until decided otherwise by a strong community consensus, it will remain the only one. And last, this revision was designed as a purely editorial rewrite of the specification. It should not change how the protocol works in any way (except for a few bug fixes which were discussed and agreed to by the community).

Now that I got that out of the way…

I am excited to announce and share the publication of the unofficial OAuth Core 1.0 “Editor’s Cut” edition (you know, like they do with movies). This is what OAuth would have looked like if I had 2 years of specification writing experience prior to writing the original specification (editorially speaking).

As important, this “Editor’s Cut” edition comes complete with a shiny new “Messina’s Cut” logo version (equally unofficial). Special thanks to Chris Messina for the special edition logo.

As I wrote before, I decided to revise the core specification as we prepare to begin the standardization work within the IETF. I wanted to have a better, more consistent baseline to work with, but even more, I wanted to offer developers a better document to read today, instead of having to wait for the IETF profile of the protocol which is expected to take about a year.

The result is a completely new approach to explaining OAuth. It includes a new, much simplified set of terms (gone are the confusing consumers, service providers, and multiple types of tokens). The new document structure has also been completely revised, flipping the specification on its head. The new specification first explains how to make OAuth-authenticated requests, before explaining how to obtain tokens via redirection.

Another benefit of the new format is that it places less emphasis on the browser-based authorization workflow. Instead, it positions it as one of many possible methods for exchanging usernames and passwords for tokens.

This new “Editor’s Cut” is still a draft. I hope to receive feedback and comment from people who have read the official specification, as well as people reading it for the first time. Even if you have read OAuth Core 1.0 before, you should read this from start to finish. This is a brand new document (except for the security considerations section which is mostly the same).

(For all you HTML-challenged folks, the draft-hammer-oauth IETF version has been updated to this new edition.)

5 thoughts on “OAuth Core 1.0 Reborn

  1. Eran, this is well written and pretty easy to understand. The specific examples make it easy to follow. Great call reversing the order of the document as well.
    Why the decision to collapse request_token and access_token into one term, “oauth_token”? I understand that it seems to offer simplicity (oh, only one token) but I actually think keeping the names separate made sense. I was thinking you’d make oauth_token as the default term (the one used to actually make requests), but keep oauth_request_token around. Maybe call it oauth_temporary_token to emphasize its ephemeral nature? Or am I misunderstanding what’s going on here?
    How does this new nomenclature interact with the OpenID/ OAuth hybrid spec? There are provisions in there spec for the term “request_token”. I assume if this is approved that the other spec will need to be revised.
    For that matter, how does this affect backwards-compatibility with existing OAuth implementations?
    Also, here’s a use case I was considering recently, curious to hear your thoughts. How does one upgrade an existing token? Suppose I have a token that gives access to scope A, and I now want access to scope B – can I ask the service provider to just increase the scope without necessarily chnaging tokens? Or do I have to re-authorize and go through the whole flow, and then get a new token that has both scope A and B? I know this isn’t directly related but I’ve been wondering about the “best practice” advise for that situation.
    Specifics:
    3.3: parameter => parameters
    3.3.1.3: I don’t know much about ports, but are there any other ports that should be default included? What if it’s a telnet transaction or something? If HTTP and HTTPS are the ONLY ports that should be left off, then I suggest including a line saying that explicitly.

  2. First, this spec does not change the protocol in any way. There is no worry about backward compatibility because it is the exact same protocol.
    It would be great if we could renamed the parameters (mostly oauth_consumer_key) but we can’t without breaking stuff at this point. Maybe in the IETF version, but even there it will be a hard sell.
    The fact that the hybrid proposal uses OAuth terms in parameter names is unfortunate, and I would hope they change it. But the two “token” types are still there, they are just called temporary credentials and token instead of request token and access token.
    Your question about “upgrading” tokens is directly addressed by Allen Tom’s OAuth Session extension (http://oauth.googlecode.com/svn/spec/ext/session/1.0/drafts/1/spec.html).
    And last, regarding 3.3.1.3, the OAuth spec only deals with HTTP requests so these are the only two schemes relevant. The reason why the language allows for other protocols is because HTTP might be used over other transports in the future and there is no reason to prevent that. But for now, it is just http and https.

  3. Eran,
    Section 3.2 states:
    To avoid the need to retain an infinite number of nonce values for
    future checks, servers MAY choose to restrict the time period after
    which a request with an old timestamp is rejected. Server applying
    such restriction SHOULD provide a way for the client to sync its
    clock with the server’s clock.
    This mechanism for syncing the client and server clock should be elaborated further.
    If SP chooses to transfer the timestamp to it’s consumer when this timestamp diff. occurs then this communication could also be violated like a DOS attack by repeating such invalidated timestamp requests to the SP.
    One more thing to consider is that how do we transfer the timestamp unless we are sure that the Consumer is valid and this validity can only be made if the verification succeeds, which cannot, unless the timetamp is valid. So we have a circular dependency over here.
    However, I think that syncing timestamp request should work correctly in invalidated mode.
    any comments?

  4. Eran,
    I’m planning to include it in my SP implementation because we don’t want to restrict our consumers to be on the same (similar) time.
    (Note that I’m trying to implement 1.0a along with suggestions in your draft and posts)
    What I can think of is to ease the step 6.1.1 (OAuth Core 1.0a) while verifying the timestamp/nonce i.e. if the timestamp doesn’t matches, then we can still continue and pass the consumer the server’s timestamp in 6.1.2 (OAuth Core 1.0a).
    All others steps should stay the same and timestamp/nonce verification should be as described in 3.2 (your draft).
    If there are any other suggestions, please throw them in.
    Thanks,

Comments are closed.