Subject: [OAUTH-WG] Publishing OAuth Core 1.0a as IETF Info RFC

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 22 Sep 2009 08:48:41 -0700

What do people think about the idea of publishing the current OAuth 1.0a as an Informational RFC? This will mean simply taking the pre-WG draft [1] and applying the Revision A changes [2] (as has been done to the WG drafts).

There is currently a lot of confusion about which spec people should be reading. The OAuth Core 1.0a spec also suffers from poor structure, uses a different set of terms from the WG draft, and contains bugs. By quickly publishing the I-D as an informational RFC which clearly states it is just a documentation of existing behavior, we will accomplish:

1. Clarity in the market with regard to which specs should be used
2. An easier upgrade path as the RFC will be marked as obsolete once the new work is completed
3. Reduce the need to preserve some features of the protocol because the info RFC will cover that for use cases the new spec will drop
4. Provide a consistent experience across the different protocol specifications, with common terminology, improving our ability to discuss old vs. new and reduce the learning curve for those transitioning

This will not be a working group deliverable. If enough people here feel this is a good idea, I will get this ready in a couple of days and post if for last call. The work is already done, we just need to decide if we want to push it out.

I am very much in support for such a publication.

EHL

[1] http://tools.ietf.org/html/draft-hammer-oauth
[2] http://code.google.com/p/oauth/source/diff?spec=svn1058&old=991&r=1058&format=unidiff&path=%2Fspec%2Fcore%2F1.0a%2Foauth-core-1_0a.xml

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 22 Sep 2009 13:30:23 -0700

I have submitted a new version of the OAuth Core 1.0 draft:

http://www.ietf.org/id/draft-hammer-oauth-03.txt

This should be the last update to the 1.0 (based on revision A) draft. This is NOT an working group item and is only submitted to document the current protocol.

I plan to request a last call by the end of the week.

If approved, this document will replace the specification currently published at http://oauth.net/core/1.0 and http://oauth.net/core/1.0a. It will become the official specification for OAuth Core 1.0.

Other than a complete editorial rewrite of the entire specification, it includes the following protocol changes:

   o  Adjusted nonce language to indicate it is unique per token /
      timestamp / client combination.

   o  Extended signature base string coverage which includes
      "application/x-www-form-urlencoded" entity-body parameters when
      the HTTP method used is other than POST and URI query parameters
      when the HTTP method used is other than GET.

   o  Requirement to normalize empty request URI paths as "/".

   o  Corrections to the instructions in each signature method to encode
      the signature value before inserting it into the "oauth_signature"
      parameter, removing errors which would have caused double-encoded
      values.

These changes were made with wide consensus from the OAuth community, should be considered errata, and for the most part reflect how existing implementations work. Some small changes will be required in some libraries to fully comply with this new edition.

EHL

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Eran Hammer-Lahav
> Sent: Tuesday, September 22, 2009 8:49 AM
> To: [email-masked]
> Subject: [OAUTH-WG] Publishing OAuth Core 1.0a as IETF Info RFC
> 
> What do people think about the idea of publishing the current OAuth
> 1.0a as an Informational RFC? This will mean simply taking the pre-WG
> draft [1] and applying the Revision A changes [2] (as has been done to
> the WG drafts).
> 
> There is currently a lot of confusion about which spec people should be
> reading. The OAuth Core 1.0a spec also suffers from poor structure,
> uses a different set of terms from the WG draft, and contains bugs. By
> quickly publishing the I-D as an informational RFC which clearly states
> it is just a documentation of existing behavior, we will accomplish:
> 
> 3. Reduce the need to preserve some features of the protocol because
> the info RFC will cover that for use cases the new spec will drop
> 4. Provide a consistent experience across the different protocol
> specifications, with common terminology, improving our ability to
> discuss old vs. new and reduce the learning curve for those
> transitioning
> 
> This will not be a working group deliverable. If enough people here
> feel this is a good idea, I will get this ready in a couple of days and
> post if for last call. The work is already done, we just need to decide
> if we want to push it out.
> 
> [2]
> http://code.google.com/p/oauth/source/diff?spec=svn1058&old=991&r=1058&
> format=unidiff&path=%2Fspec%2Fcore%2F1.0a%2Foauth-core-1_0a.xml
> 
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 23 Sep 2009 08:03:14 -0600

<hat type="chair"/>

On 9/22/09 2:30 PM, Eran Hammer-Lahav wrote:
> This should be the last update to the 1.0 (based on revision A)
> draft. This is NOT an working group item and is only submitted to
> document the current protocol.

Thanks. I think it is a good idea to codify existing practice in an
informational RFC so that developers have a good, stable reference in
the RFC series. Then we can continue moving ahead with the standards
track work on "OAuth 1.1" or whatever we end up calling it.

Peter

- --
Peter Saint-Andre
https://stpeter.im/

---

From: "Manger, James H" <[email-masked]>
Date: Thu, 24 Sep 2009 00:28:13 +1000

I agree that publishing OAuth 1.0a as an Informational RFC would be helpful.

It needs a bit more text explaining the history and relationship to the original 1.0 and 1.0a specs. The abstract says “this document is based on revision A of the community specification and includes a few clarifications”. The end of the introduction adds a bit more (“[[ This draft is submitted for informational purposes to document the current use of the protocol.  It is not an item of the OAUTH working group… ]]”), however the brackets “[[ … ]]” suggests this text will be removed before publication.

Perhaps a paragraph like the following could be included in the introduction. Alternatively, the list of 4 protocol changes in Eran's email could be included in the document.

“This document is based on the original OAuth Core 1.0 document published in December 2007 and Revision A (correcting a session fixation attack) published in June 2009 -- both developed by the OAuth community (http://oauth.net/). The changes in this document are primarily editorial: a more sensible document structure and clearer terminology. A few errata are incorporated in this document reflecting how existing implementations work.”

A few other suggested changes:

Realm: Appendix A.1.
Change the realm parameter value from "http://photos.example.com/" to, say, "photos".
The http://photos... value is the same as the example in Core 1.0 and Rev A, however those documents used http requests, whereas this doc uses https. Consequently the http realm is misleading.
The realm does not have to be a URL as its definition in RFC 2617 section 1.2 (which OAuth refers to) is quite clear that a realm value is considered "in combination with the canonical root URL".

Editorial: Appendix A.2
Change "Jane approves the request and is redirects her back to"
To     "Jane approves the request and is redirected back to"

James Manger
[email-masked]
Identity and security team — Chief Technology Office — Telstra

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 23 Sep 2009 10:26:09 -0700

Is the new appendix with list of changes not enough?

EHL

On 9/23/09 7:28 AM, "Manger, James H" <[email-masked]> wrote:

It needs a bit more text explaining the history and relationship to the original 1.0 and 1.0a specs. The abstract says "this document is based on revision A of the community specification and includes a few clarifications". The end of the introduction adds a bit more ("[[ This draft is submitted for informational purposes to document the current use of the protocol.  It is not an item of the OAUTH working group... ]]"), however the brackets "[[ ... ]]" suggests this text will be removed before publication.

"This document is based on the original OAuth Core 1.0 document published in December 2007 and Revision A (correcting a session fixation attack) published in June 2009 -- both developed by the OAuth community (http://oauth.net/). The changes in this document are primarily editorial: a more sensible document structure and clearer terminology. A few errata are incorporated in this document reflecting how existing implementations work."

Realm: Appendix A.1.

Editorial: Appendix A.2

James Manger
[email-masked]
Identity and security team - Chief Technology Office - Telstra

---

From: "Manger, James H" <[email-masked]>
Date: Thu, 24 Sep 2009 09:19:20 +1000

>> It needs a bit more text explaining the history and relationship to the original 1.0 and 1.0a specs.

> Is the new appendix with list of changes not enough?

I saw the list of changes in Appendix D “Document History”, which will be removed before publication.

I hadn’t noticed Appendix B “Differences from the Community Edition”. Opps. That is sufficient.

James Manger
[email-masked]<mailto:[email-masked]>
Identity and security team — Chief Technology Office — Telstra

---

From: Seth Fitzsimmons <[email-masked]>
Date: Wed, 23 Sep 2009 18:30:23 -0700

> Is the new appendix with list of changes not enough?

Thank you thank you thank you.  Including such an appendix is
immensely useful, even if the list of changes is minimal (in this
case).

seth