Subject: [OAUTH-WG] Working toward an initial draft of OAuth 2.0

From: David Recordon <[email-masked]>
Date: Wed, 3 Mar 2010 14:29:25 -0800

Over the weekend I took a quick stab at what a new draft of an OAuth 2.0 spec would look like.  I don't have a lot of normative text but wanted to share what I was thinking about in terms of the specification's structure and technical inner-workings.

This comes out of the survey from two weeks ago which Peter Saint-Andre summarized (http://www.ietf.org/mail-archive/web/oauth/current/msg01214.html) as there being consensus around:
 - OAuth 2.0 taking aspects from both the 1.0 and WRAP specs/drafts with a preference toward the WRAP draft
 - we should go back to working on a single document
 - OAuth 2.0 should support signatures as a mechanism for making requests

Documents involved:
 - OAuth 1.0: http://tools.ietf.org/html/draft-hammer-oauth-10
 - WRAP: http://tools.ietf.org/html/draft-hardt-oauth-01

Combined document structure:
My goal is that sections one through four are not more than fifteen to twenty pages combined.

0. Abstract

1. Introduction
1.1 Acknowledgments
1.2 Terminology
1.3 Notational Conventions

2. Getting an Access Token
2.1 Web App / JavaScript Profile (in browser)
2.2 Rich App Profile (can open a browser)
2.3 Device Profile (no browser, should be like the Netflix flow)
2.4 Username and Password Profile
2.5 Client key and secret (not in the context of a user)

3. Refreshing an Access Token

4. Accessing a Protected Resource
4.1 Using SSL
4.2 Using a signature

5. Security Considerations

Abstract
    OAuth 2.0 provides a method for an application (Client) to access the Protected Resource hosted on a server on behalf of a Resource Owner (such as a different client or an end-user).  It provides a process for end-users to authorize third-party access to their Protected Resources via a variety of Authorization Profiles which generally do not include having to share their credentials (typically, a username and password pair).  A server can additionally delegate authorization to one or more authorities (Authorization Server) which issue Access Tokens to Clients.

Introduction
 - This section should provide a longer description of the protocol flows and the evolution from OAuth 1.0.
 - The terminology should be based on updated OAuth 1.0 terminology which is already close to the WRAP terminology as well.  We should err on the side of more generally understood terms.
 - Both OAuth 1.0 and WRAP contain fairly complete introductory sections.  I think that the WRAP one is a bit too long and we should shoot for this section being a little over two pages (including terminology).

Getting an Access Token
 - This section really comes from WRAP.  I believe that a server MUST implement at least one of the profiles to be considered OAuth compatible.
 - The updated OAuth 1.0 spec could also be useful for more complete language around the Web App Profile though we should also draw from Luke Shepard's JavaScript profile (which needs updating) (http://groups.google.com/group/oauth-wrap-wg/browse_thread/thread/4840fab6935e6fbc).  I believe the main difference is the security characteristics.
 - While the SAML assertion profile has been in WRAP, I haven't seen strong advocates on the mailing list or in the survey for it.  Does someone want to argue for keeping it?  Could it be drafted as a separate profile from the core spec?

Refreshing an Access Token
 - In WRAP this functionality is described along with each individual authorization profile.  Some profiles require the client id and secret though not all of them.  In terms of writing more reusable code I imagine that implementors will write a single refresh_token(client_id, client_secret) function so breaking this out into its own section will be easier to implement.
 - We could either require the client id and secret for all profiles or keep them as optional for some profiles.  Personally I lean toward consistency.

Accessing a Protected Resource
 - This section is really a combination of WRAP and OAuth 1.0.  SSL support will be a MUST and signatures will be optional.
 - Bearer tokens (even short lived) without using SSL or signatures feels like a poor idea, but given the WRAP draft it seems like the security teams at Google, Microsoft and Yahoo! are all comfortable with doing so?  Given that we'll be adding signatures as an option do we still need unprotected bearer tokens?
 - The SSL section basically copies directly from WRAP section #4.  It's about a page and a half and really easy to implement.
 - We need to agree on the signature method though there is a lot of normative text in the OAuth 1.0 spec to draw from (http://tools.ietf.org/html/draft-hammer-oauth-10#section-3.4).   OAuth 1.0 is about three pages of text assuming people are happy with the mechanism; it would be good to simplify as much as possible.
    - We're missing an access token secret, but I'm wondering if we can treat the refresh token as the access token secret since it's only sent over the wire via SSL?
    - Alternatively we could modify the refresh token request to let the client specify that they'd also like an access token secret for that request. This seems like the right way of doing it.
    - Both break the idea that the API endpoint doesn't have access to secrets, but the deployment scenarios I've seen discussed as wanting signatures (at least Facebook and Twitter) won't be separating their architecture anyway.

Security Considerations
 - I'm the wrong person to write this section.

Misc
 - Rename parameters to oauth_

If I were to spend some time over the next week or two drafting this spec would folks generally be supportive of it?  If not, what would you change so that you could be supportive of it?  Note well, if you only reply with "I don't like it" without a reasonable technical explanation of why then your feedback will be disregarded. ;)

One of my goals is getting OAuth 2.0 to the point – fairly quickly – where we can start to architect the next version of OpenID on top of it.  WebFinger + OAuth 2.0 + identity would be sweet and finally give us a consistent story for both authentication and authorization.  I'd love whatever help I could get with all of this as well!

Thanks,
--David

(Cross posted on my blog: http://daveman692.livejournal.com/349384.html)

---

From: Igor Faynberg <[email-masked]>
Date: Wed, 03 Mar 2010 17:47:15 -0500

David,

I find this is an excellent starting point, and I share with you the 
urgency to move the work as quickly as possible.

I do think that we need to address a couple of items such as the use 
cases and requirements. The need for those also came quite strongly in 
the surveys. I do not see any problem in developing both in parallel 
(although I do expect that some people would insist on the 
requirements--in support of the use cases--coming first).

One way of addressing this is having the use case requirements sections 
in the document you are putting together. The other would be to work 
them in a separate document.

What is your opinion?

Igor

David Recordon wrote:
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 3 Mar 2010 19:30:39 -0700

Last week I started doing the same thing only with normative text in RFC format. I took a break the past two days to work on the LRDD and WebFinger specs (one published one pending). I plan to spend most of next week getting a feature complete draft for OAuth 2.0 based on a similar skeleton. I am going away on vacation until Monday afternoon so I will leave it up to you if you want to continue working and sync next week to see where we both are, or leave it where it is and wait for my attempt. I'm happy to move forward either way.

EHL

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of David Recordon
> Sent: Wednesday, March 03, 2010 2:29 PM
> To: OAuth WG
> Subject: [OAUTH-WG] Working toward an initial draft of OAuth 2.0
> 
> Over the weekend I took a quick stab at what a new draft of an OAuth 2.0
> spec would look like.  I don't have a lot of normative text but wanted to share
> what I was thinking about in terms of the specification's structure and
> technical inner-workings.
> 
> This comes out of the survey from two weeks ago which Peter Saint-Andre
> summarized (http://www.ietf.org/mail-
> archive/web/oauth/current/msg01214.html) as there being consensus
> around:
>     OAuth 2.0 provides a method for an application (Client) to access the
> Protected Resource hosted on a server on behalf of a Resource Owner (such
> as a different client or an end-user).  It provides a process for end-users to
> authorize third-party access to their Protected Resources via a variety of
> Authorization Profiles which generally do not include having to share their
> credentials (typically, a username and password pair).  A server can
> additionally delegate authorization to one or more authorities (Authorization
> Server) which issue Access Tokens to Clients.
> 
> Introduction
>  - The terminology should be based on updated OAuth 1.0 terminology which
> is already close to the WRAP terminology as well.  We should err on the side
> of more generally understood terms.
>  - Both OAuth 1.0 and WRAP contain fairly complete introductory sections.  I
> think that the WRAP one is a bit too long and we should shoot for this section
> being a little over two pages (including terminology).
> 
> Getting an Access Token
>  - This section really comes from WRAP.  I believe that a server MUST
> implement at least one of the profiles to be considered OAuth compatible.
>  - The updated OAuth 1.0 spec could also be useful for more complete
> language around the Web App Profile though we should also draw from Luke
> Shepard's JavaScript profile (which needs updating)
> (http://groups.google.com/group/oauth-wrap-
> wg/browse_thread/thread/4840fab6935e6fbc).  I believe the main
> difference is the security characteristics.
>  - While the SAML assertion profile has been in WRAP, I haven't seen strong
> advocates on the mailing list or in the survey for it.  Does someone want to
> argue for keeping it?  Could it be drafted as a separate profile from the core
> spec?
> 
>  - In WRAP this functionality is described along with each individual
> authorization profile.  Some profiles require the client id and secret though
> not all of them.  In terms of writing more reusable code I imagine that
> implementors will write a single refresh_token(client_id, client_secret)
> function so breaking this out into its own section will be easier to implement.
>  - We could either require the client id and secret for all profiles or keep them
> as optional for some profiles.  Personally I lean toward consistency.
> 
>  - This section is really a combination of WRAP and OAuth 1.0.  SSL support will
> be a MUST and signatures will be optional.
>  - Bearer tokens (even short lived) without using SSL or signatures feels like a
> poor idea, but given the WRAP draft it seems like the security teams at
> Google, Microsoft and Yahoo! are all comfortable with doing so?  Given that
> we'll be adding signatures as an option do we still need unprotected bearer
> tokens?
>  - The SSL section basically copies directly from WRAP section #4.  It's about a
> page and a half and really easy to implement.
>  - We need to agree on the signature method though there is a lot of
> normative text in the OAuth 1.0 spec to draw from
> (http://tools.ietf.org/html/draft-hammer-oauth-10#section-3.4).   OAuth 1.0
> is about three pages of text assuming people are happy with the mechanism;
> it would be good to simplify as much as possible.
>     - We're missing an access token secret, but I'm wondering if we can treat
> the refresh token as the access token secret since it's only sent over the wire
> via SSL?
>     - Alternatively we could modify the refresh token request to let the client
> specify that they'd also like an access token secret for that request. This
> seems like the right way of doing it.
>     - Both break the idea that the API endpoint doesn't have access to secrets,
> but the deployment scenarios I've seen discussed as wanting signatures (at
> least Facebook and Twitter) won't be separating their architecture anyway.
> 
> Security Considerations
> If I were to spend some time over the next week or two drafting this spec
> would folks generally be supportive of it?  If not, what would you change so
> that you could be supportive of it?  Note well, if you only reply with "I don't
> like it" without a reasonable technical explanation of why then your feedback
> will be disregarded. ;)
> 
> One of my goals is getting OAuth 2.0 to the point - fairly quickly - where we
> can start to architect the next version of OpenID on top of it.  WebFinger +
> OAuth 2.0 + identity would be sweet and finally give us a consistent story for
> both authentication and authorization.  I'd love whatever help I could get
> with all of this as well!
> 
> Thanks,
> --David
>

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 03 Mar 2010 22:19:42 -0700

<hat type='chair'/>

On 3/3/10 3:29 PM, David Recordon wrote:
> Over the weekend I took a quick stab at what a new draft of an OAuth
> 2.0 spec would look like.

Thanks, David, I think this is very helpful and a great start to more
rapid progress. I know Eran has been thinking along the same lines.
Let's definitely talk about this in tomorrow's conference call.

Peter

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

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 03 Mar 2010 22:32:35 -0700

<hat type='chair'/>

> requirements--in support of the use cases--coming first).

Although I like requirements and use cases documents as much as the next
person, I think we can work on those in parallel with the protocol
document given that the WG participants have quite a bit of knowledge
about the problem domain (we're not starting from scratch here).

> them in a separate document.

My personal opinion is that it would be good to have a separate document
that captures and consolidates a wide variety of use cases (preferably
managed by one or two assigned document editors in accordance with RFC
2418), but that is something the WG would need to agree on. I hope we
can have some preliminary discussions about that in tomorrow's
conference call and perhaps come to consensus on the matter in Anaheim
or soon after.

Peter

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

---

From: Anthony Nadalin <[email-masked]>
Date: Thu, 4 Mar 2010 05:42:11 +0000

What the specification allows in terms of SSL is different than  deployment requirements, so I would not say that Microsoft is generally comfortable in not using SSL. We don't have a specific requirement for signatures.

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Igor Faynberg
Sent: Wednesday, March 03, 2010 2:47 PM
To: David Recordon
Cc: OAuth WG
Subject: Re: [OAUTH-WG] Working toward an initial draft of OAuth 2.0

David,

I find this is an excellent starting point, and I share with you the urgency to move the work as quickly as possible.

I do think that we need to address a couple of items such as the use cases and requirements. The need for those also came quite strongly in the surveys. I do not see any problem in developing both in parallel (although I do expect that some people would insist on the requirements--in support of the use cases--coming first).

One way of addressing this is having the use case requirements sections in the document you are putting together. The other would be to work them in a separate document.

What is your opinion?

Igor

David Recordon wrote:
> If I were to spend some time over the next week or two drafting this 
> spec would folks generally be supportive of it?  If not, what would 
> you change so that you could be supportive of it?  Note well, if you 
> only reply with "I don't like it" without a reasonable technical 
> explanation of why then your feedback will be disregarded. ;)
>
> One of my goals is getting OAuth 2.0 to the point - fairly quickly - where we can start to architect the next version of OpenID on top of it.  WebFinger + OAuth 2.0 + identity would be sweet and finally give us a consistent story for both authentication and authorization.  I'd love whatever help I could get with all of this as well!
>
> Thanks,
> --David
>
> (Cross posted on my blog: 
> http://daveman692.livejournal.com/349384.html)

---

From: David Recordon <[email-masked]>
Date: Wed, 3 Mar 2010 22:30:18 -0800

Awesome; that's great!

My main goal is helping to get an initial draft of 2.0 so collaborating makes far more sense than multiple efforts.  Is there anything I can do to help you work toward the draft next week?

What have you been thinking about differently from my outline?

Thanks,
--David