Re: [OAUTH-WG] First draft of OAuth 2.0

[David Recordon <[e-mail]>]

Thanks!  Comments inline and updated the repo
(http://github.com/daveman692/OAuth-2.0/commit/3193098ff45168dd0a65456334428b20215f848a).

On Sun, Mar 21, 2010 at 12:03 PM, Eve Maler <[e-mail]> wrote:
> David, great stuff -- thanks for putting this together!  Here are a few comments and questions from a quick read on the plane down to Anaheim, in spec order (the weight/priority therefore varies widely).
>
> Abstract
>
> - "delegate": The use of this word seems like it's different from how it's been used in the past, e.g. in "user delegation".  It's not a big deal, but possibly confusing.

Rephrased a bit, but someone should just rewrite the abstract to begin with.


> Introduction:
>
> - I'm glad there's a hint here of "autonomously or on behalf of an end-user", but I notice the distinction between "user delegation flows" and "autonomous-client flows" introduced by WRAP seems to have been made more implicit in this draft.  UMA has an interest in understanding very carefully how flows get distinguished along these lines, and in fact we may need to define even more flows and types of flows for our own purposes (see our Lexicon at http://kantarainitiative.org/confluence/display/uma/Lexicon for more).  Hope to discuss this a bit tomorrow.  (And see more below in my comments on 2.5.)

Made it more implicit, but not trying to remove the autonomous-client
flows.  Reworded a little.


> - "provisioning tokens": I'd say resource owners don't personally provision tokens, but rather signal that authorization servers should do so on their behalf.

Rephrased, but the entire introduction needs (re)writing.


> - The use of "server" in the intro is very natural.  See terminology comments below for more.
>
> 1.3. Terminology
>
> - access token: The client might instead be making requests on behalf of itself, not "the user", right?

Thanks, changed.


> - authorization server and protected resource: These definitions cry out to have a formal definition of "server" (or "protected resource server"?) in this section as well, since "server" is already invoked quite naturally in a few places to mean the server of a protected resource.  Though the definition of protected resource says it's the resource served by an HTTP server, a few remaining WRAP-inherited instances of the term elsewhere try to force it to be both. I have some additional comments below that rely on a nice clean distinction between the authorization server and the server of a protected resource, because even though they're often colocated in pure-OAuth use cases, UMA makes strategic use of the option to separate them.  (Oh, also: s/A HTTP/An HTTP/)

Added the OAuth 1.0 definition.  Had it before, but someone convinced
me to remove it.


> - client identifier: s/used used/used/

Thanks!


> - resource owner: "such that it issues...": This is a bit awkward.  Maybe say "to approve the issuing of an access token to a client"?

Thanks!


> 1.3.1. Endpoints
>
> - "such as via documentation": FWIW, because UMA goes for dynamic introduction of various parties, we're using hostmeta and XRD to do this sort of thing.  Is there any wider interest in providing a (perhaps merely advisory) method of documentation that involves these technologies (or similar), to get greater interop?

This wording isn't meant to limit future discovery technologies.
Rephrased to "The client discovers the following three URI endpoints
from the server (such as via reading documentation):"


> - "API request": Because I'm coming from a mindset that sees all web resources as possibly being "OAuth-protected", and because we want to ensure the option of loose coupling between authorization server and protected resource server, I'm struggling to figure out (a) if calling this "API request" is too limiting given that maybe every resource on the server (e.g. every photo in a directory) is subject to a request for access, and (b) if this is something the protected resource server itself should advertise (vs. the authorization server), as appropriate.

Changed to "endpoint(s)" and removed "authorization" from the previous
sentence.  I think that we should stick with the "API Request"
wording.


> - "user authorization request": s/resource owners's/resource owner's/g (the typo appears in a bunch of places)

Thanks, fixed three times.


> 2. Getting an Access Token
>
> - "MUST implement at least one...": Are its implementation choices something the authorization server should advertise in documentation?

I imagine so, but doing so seems orthogonal to the spec.


> - It would be helpful to give really concrete examples/use cases of all of the profiles in the intro, so people can determine from this single place which profiles interest them.

Each flow starts with one or two sentences trying to describe when
they should be used.  I'm perfectly willing to admin that they might
not be complete.  Happy to accept text from anyone! (Same goes for the
intro.)


> 2.1. Web Server Flow
>
> - "without acquiring and end-user's credentials": Is this an obliquely stated version of "avoiding the 'password anti-pattern'"?  I think it could be useful to mention this phrase here somewhere.  Also, it's a little confusing to mention the resource owner and an end-user without seeming to connect them.

Added.


> - oauth_callback_url: It says this is required, but what if the authorization server already required the client to pre-register this?

Always required even if pre-registered.  Makes the request really
explicit about what the client intends to have happen without relying
on magic.


> - "MUST first verify the identity of the resource owner": Should this be followed with "...and seek their approval of the authorization request" or similar?  (This whole thing doesn't seem testable since it's outside the view of the protocol, so I'm wondering if uppercase MUST is warranted.)

I'll rely on Eran's editing pass to correct my must/MUST usage. :)

Could make seeking approval more defined, though the next sentence
begins with "If the resource owner approves the authorization
request".


> - oauth_error_reason: Does "user_denied" mean "the user denied the request"?  Since the spec holds out the (slim) possibility of the resource owner not being an end-user, should this be "resource_owner_denied" or "request_denied" or something?

Changed to "owner_denied".


> - I'm thinking oauth_error_reason is where UMA could define an extension that gives an error like "claims_required".  I need to sort this out with my gang, but provide it here as food for thought.  Should we be defining our own parameter instead (and if so, should this spec say something about cases where this is done by others)?  Alternatively, should this spec allow for extended error codes in some formal fashion?

Error codes are coming up quite a bit.  In general you should rely on
HTTP error responses, but there are cases where they're not specific
enough.  I'd really appreciate a list of error reasons that
implementors would like to see in the protocol.  A combined list will
help make it happen.  Seems like we should start a thread about this.


> - "The server must retain the scope...": I *think* this means the authorization server, given that it's the one issuing the token, so this should be explicitly stated.  Keep in mind that UMA has reason to keep the kinds of servers architecturally separate, which means we needed to build a way for an UMA host (effectively an OAuth protected resource server) to be able to correlate the client's desired scope (as retained by the authorization server and baked into the issued token somehow, such that it can be validated when presented by the client) and the actual type of access attempted by the client.  Actually, I think OAuth has this need too, so perhaps UMA isn't all that different.

Yes, the authorization server is what's meant.  Changed five times.


> 2.2. Web Client Flow
>
> - s/a mobile device/on a mobile device/

Thx.


> - "the client is downloaded to the resource owner's user-agent": I *think* I can make sense of this, but the order just seems weird and backwards. :-)  Is the client, in fact, functioning as an HTTP user-agent itself?  Or is the client downloaded to the user's physical device (in which a separate user-agent is colocated)?

Both.


> - "SHOULD verify that the callback URI provided ... is valid": Why not MUST?  It seems eminently doable.

Changed to MUST given that callback URL verification is one of the few
ways to protect this flow.



> 2.3. Device Flow
>
> - "The client MAY both poll and have...": Cleaner to say "The client MUST either poll or have an interface element, or both."

Changed.


> 2.4. Username and Password Flow
>
> - "The client MUST discard the resource owner's username...": This is obviously very desirable, but seems untestable.  Is the uppercase MUST warranted?

Lowercased.


> - "The authorization server ... MAY verify that the client is authorized to use this flow": Why and how would this MAY work?  I'm not quite understanding the goal here.

Idea is that this flow will probably not be offerred to any client.  I
think Raffi is working on some text around making this flow seem
scarier already.  The goal is to discourage it's use given that the
other flows do a better job of protecting user security.


> 2.5. Client Identifier and Secret Flow
>
> - "This flow is suitable when the client is also the resource owner": I think this was supposed to be the "two-legged"/"autonomous-client" solution, but this phrase throws that into doubt for me.  What was the intent here?  Note that UMA (like a lot of others) is interested in solving automated self-registration of an autonomous client at an authorization server.  (In case it's of interest, we've been trying to sort out the legal implications of parties who are *not* the resource owner seeking authorized access; this is where our "claims_required" stuff comes in.  Sometimes the client represents "itself", or rather a company or org acting on its own behalf; sometimes it represents a person different from the resource owner; etc.  See our Lexicon at http://kantarainitiative.org/confluence/display/uma/Lexicon.)

You're right.  Can you help reword please?


> - Probably this is an effect of needing more time for study, but why does this profile not use oauth_error_code like the others do, relying only on a 401?

See earlier reply on error codes.  Happy to add some if they're well defined.


> 3. Refreshing an Access Token
>
> - "The authorization server MUST verify that the resource owner...": This seems untestable.  Is the uppercase MUST warranted?

Will let Eran fix.


> - "the protected resource MUST NOT allow the user of the corresponding access token without its secret": This is a case where "[protected resource] server" would work way better than "protected resource", as resources don't allow or disallow actions; they just exist.

hmm, does read a bit better in most cases.  Means changing the
definition as well.  What do others thing?


> 4.1.2. Client Calls Protected Resource Using URL Query Parameter
>
> - "Prior to making a request": Just FYI, UMA makes use of a key stage prior to a client making an access-token-bearing request; the client (UMA requester) can hit the resource out of the blue, and in this way learns the relevant access token request endpoint from the protected resource server (UMA host).

Sure, don't see this spec as limiting that.


> - "the following examples use the HTTP GET method": Should the wording here and in the next section ("The client constructs an HTTP 'POST'...") be rationalized to be more similar?

Hoping Eran cleans this up a bit more.


> Look forward to discussing more tomorrow,

Definitely, looking forward to it!

Thanks again!

--David

>
>        Eve
>
> On 19 Mar 2010, at 6:28 PM, David Recordon wrote:
>
>> As I mentioned a few weeks ago [1], I started working on editing the first draft of OAuth 2.0 over the past two weeks.  While I realize that it's 6pm Friday (sorry about that), I hope to have a solid discussion about it at Monday's meeting.  You can find the current draft of it – plus all of the document history – on my public GitHub account a thttp://github.com/daveman692/OAuth-2.0.  Eran will be doing an initial editing pass before Monday and then spend more time with it next week.
>>
>> I've attached both a HTML and TXT copy to this email and plan to officially submit it as an Internet Draft.
>>
>> The following are highlighted changes from draft-hardt-oauth-01:
>>   1.  A Web Client flow designed for use within JavaScript.  It also
>>       supports the use cases of the rich app profile so that they're
>>       not two separate flows.
>>   2.  A new device flows which is based on the Netflix/Tivo flow (TV
>>       shows you a code that you type in on your computer).
>>       http://www.ietf.org/mail-archive/web/oauth/current/msg01346.html
>>   3.  Remove captchas from the username/password flow.  They haven't
>>       been successfully implemented within this context and create
>>       complexity especially when we use other signals to detect
>>       compromised accounts.
>>       http://www.ietf.org/mail-archive/web/oauth/current/msg01293.html
>>   4.  Don't allow bearer tokens without either SSL and/or signatures.
>>       While some providers may offer this ability, they should be out
>>       of spec for doing so though technically it won't break the flows.
>>   5.  Abstract the refresh token flow out of each profile into its own
>>       section.  Support the ability to request access token secrets
>>       when refreshing.
>>   6.  Support signatures for making API requests but not for getting
>>       access tokens.  If you want to use signatures, you'll get an
>>       access token and then make a refresh call where you ask for a
>>       token secret.  This causes the auth server to mark the token as
>>       no longer being valid as a bearer token via SSL.  This
>>       performance tradeoff seems realistic given many use cases focus
>>       on high-volume API transactions and thus the one additional
>>       request at the onset should be noise.  The signature mechanism is
>>       currently from OAuth 1.0.
>>
>> Obviously I couldn't have made so much progress so quickly if it weren't for WRAP and I hope that 2.0 both addresses the WRAP use cases as well as those we all have been discussing here.  I hope that I haven't missed anyone who contributed to prior work and am happy to add other authors if I have (and they wish to be added)!
>>
>> Thanks,
>> --David
>>
>> [1] http://www.ietf.org/mail-archive/web/oauth/current/msg01225.html
>>
>
> Eve Maler
> [e-mail]
> http://www.xmlgrrl.com/blog
>
> _______________________________________________
> OAuth mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/oauth
>