Subject: [OAUTH-WG] Draft 20 last call comments

From: Justin Richer <[email-masked]>
Date: Thu, 11 Aug 2011 17:06:51 -0400

In addition to taking another read through the document myself, I asked
another developer here to give it a once over. She's never implemented
an OAuth client or server, but has knowledge of what it's for. Thus, an
experienced developer new to building with OAuth2 -- a key target
audience for these documents.

As you'll see here, most of our qualms are in the front matter of the
document. The actually gritty technical implementation details are
pretty solid at this point.

1.2/1.4: The term "authorization grant" remains confusing and the
introduction is riddled with jargon like "intermediate credential". With
the diagram in 1.2, it appears to be an explicit technological
underpinning of the protocol flow instead of a general conceptual
construct that is used in several different ways. Basically, what
"authorization grant" *means* is not obvious within this document.
Section 4 makes much more sense than the introduction text does here.
Perhaps we should just replace most of 1.4 with just the introductory
text to 4 (perhaps slightly expanded), and then a reference to the
sub-parts of section 4 for the meat of the concept (and in the process,
nix the subsections of 1.4 entirely).

1.2(B): "Provided" is wrong here (it implies a direct hand-over), and
the last sentence is awkward. Suggest reword to: 
        The client receives an authorization grant which represents the
        authorization granted by the resource owner.  The type of 
	authorization grant is dependent on which methods are supported
	by both the client and authorization server.

1.3/1.4/1.5: Consider switching order to Authorization Grant, Access
Token, Refresh Token

1.4.1: We probably want to mention a user agent here in the exposure
risk at the end. Since that's really the problem -- the browser could
steal the token, not the end user.

1.4.2: Still don't like the term "implicit". It's misleading. Even
"direct authorization" would be better, though still not ideal.

1.4.5: Throw a simple reference to 8.3 here?

2: Isn't "means" generally treated as singular in instances like this?
Thus "means ... is" instead of "means ... are".

2.1/2.2: The requirements (2.2) should go first in section 2. The client
types are part of deciding the requirements, and the concepts flow
better this way.

2.1: I like the calling out of the types of clients, it helps cement
things.

2.3: Suggest renaming to "Client Identification" to parallel "Client
Authentication" in 2.4

2.3: Should "... cannot be used alone" be made into a normative, as "...
MUST NOT be used alone"?

2.4.2: Want to mention the MAC binding as an example here? This would
parallel the OAuth2 method of signing the fetch for a request token more
directly.

3. Authorization endpoint's "used to obtain authorization from" should
be "used to obtain an authorization grant from", to be parallel with the
token endpoint description.

 -- Justin

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 17 Aug 2011 11:15:15 -0700

Thanks for the feedback.

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Justin Richer
> Sent: Thursday, August 11, 2011 2:07 PM

> introduction is riddled with jargon like "intermediate credential". With the
> diagram in 1.2, it appears to be an explicit technological underpinning of the
> protocol flow instead of a general conceptual construct that is used in several
> different ways. Basically, what "authorization grant" *means* is not obvious
> within this document.
>
> Perhaps we should just replace most of 1.4 with just the introductory text to
> 4 (perhaps slightly expanded), and then a reference to the sub-parts of
> section 4 for the meat of the concept (and in the process, nix the subsections
> of 1.4 entirely).
> 
> 1.2(B): "Provided" is wrong here (it implies a direct hand-over), and the last
> sentence is awkward. Suggest reword to:

Change (B) in 1.2 to:

              The client receives an authorization grant which is a credential representing
              the resource owner's authorization, expressed using one of four grant types defined
              in this specification or using an extension grant type. The authorization grant type
              depends on the method used by the client to request authorization and the types
              supported by the authorization server.

And changed 1.4 to:

          An authorization grant is a credential representing the resource owner's authorization
          (to access its protected resources) used by the client to obtain an access token. This
          specification defines four grant types: authorization code, implicit, resource owner
          password credentials, and client credentials, as well as an extensibility mechanism for
          defining additional types.

> 1.3/1.4/1.5: Consider switching order to Authorization Grant, Access Token,
> Refresh Token

Not sure. What do others think? I put access token first because it is a more important term to get out of the way.

> 1.4.1: We probably want to mention a user agent here in the exposure risk at
> the end. Since that's really the problem -- the browser could steal the token,
> not the end user.

Proposed text?

> 1.4.2: Still don't like the term "implicit". It's misleading. Even "direct
> authorization" would be better, though still not ideal.

It's the best we've got. "Direct authorization" is not a grant type, but a flow description.

> 1.4.5: Throw a simple reference to 8.3 here?

No forward references whenever possible.

> Thus "means ... is" instead of "means ... are".

Don't know.

> 2.1/2.2: The requirements (2.2) should go first in section 2. The client types
> are part of deciding the requirements, and the concepts flow better this way.

You need to first define client types before you can require it.

> 2.1: I like the calling out of the types of clients, it helps cement things.
> 

It's not about identification.
 
> 2.3: Should "... cannot be used alone" be made into a normative, as "...

I'm ok with that. Anyone else?

> parallel the OAuth2 method of signing the fetch for a request token more

Nah.

> 3. Authorization endpoint's "used to obtain authorization from" should be
> "used to obtain an authorization grant from", to be parallel with the token
> endpoint description.

Ok.

EHL

---

From: Justin Richer <[email-masked]>
Date: Wed, 17 Aug 2011 16:12:45 -0400

Comments inline.

>           defining additional types.

Much better for both overall though.

> Not sure. What do others think? I put access token first because it is a more important term to get out of the way.

I agree that access tokens are a more important topic to OAuth overall,
but the rest of the document presents things in protocol flow order: you
get the auth grant, then you get the tokens.

> > the end. Since that's really the problem -- the browser could steal the token,

   The authorization code provides a few important security benefits
   such as the ability to authenticate the client and issuing the access
   token directly to the client without potentially exposing it to
   others, including the resource owner or other applications in the resource
   owner's user agent.

(Still not good wording... but the idea is to point out that you the
leak possibility here stems from using the front channel.)

> It's the best we've got. "Direct authorization" is not a grant type, but a flow description.

Fair enough. I shall remain a conscientious objector. :)

> No forward references whenever possible.

Fair style point, but I think this one is worth it. This is why our
documents have hyperlinks.

For each of 1.4.x, I'd still rather see the 1.4.x sections just go away.

> > Thus "means ... is" instead of "means ... are".

I think it is, unless someone can put a stake in to say that's wrong.

> You need to first define client types before you can require it.

No you don't, you just need to reference them. You already don't define
the other requirements until after (such as the redirection urls). I
think it reads better to have the requirements up front, when the full
matter of what they're all about in the following sections. The client
As it is now, there are both forward and backward references in the
requirements paragraph and it's confusing to read like that.

> It's not about identification.

Then why is it called "Client Identifier"? Usually, one uses an
identifier for identification. :) Really, this comment was about
parallelizing the language in the two subsequent headers: Identification
and Authentication.

> > parallel the OAuth2 method of signing the fetch for a request token more

Let me put it stronger: I would like to see an explicit reference to the
MAC binding here as an example of a stronger auth binding, along with an
example. OAuth1 allowed for binding against the token endpoint using a
client secret that was not passed across the wire, and the MAC spec
gives that capability to OAuth2. I would really like to see that.

I see no problem in the core document pointing out the MAC and Bearer
documents as prime examples where appropriate.

 -- Justin

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 17 Aug 2011 14:59:01 -0700

> From: Justin Richer [mailto:[email-masked]]
> Sent: Wednesday, August 17, 2011 1:13 PM

> I agree that access tokens are a more important topic to OAuth overall, but
> the rest of the document presents things in protocol flow order: you get the
> auth grant, then you get the tokens.

Ok. I'll give it a try.

> > > risk at the end. Since that's really the problem -- the browser
> > > could steal the token, not the end user.
> >
> > Proposed text?
> 

How about:

            The authorization code provides a few important security benefits such as the ability
            to authenticate the client, and the transmission of the the access token directly to
            the client without passing it through the resource owner's user-agnet, potentially
            exposing it to others, including the resource owner.

> I think it is, unless someone can put a stake in to say that's wrong.

"It is plural when it refers to a group of strategies or methods"
 
> > > 2.1/2.2: The requirements (2.2) should go first in section 2. The
> > > client types are part of deciding the requirements, and the concepts flow
> better this way.
> >
> No you don't, you just need to reference them. You already don't define the
> other requirements until after (such as the redirection urls). I think it reads
> better to have the requirements up front, when the full matter of what
> they're all about in the following sections. The client As it is now, there are
> both forward and backward references in the requirements paragraph and
> it's confusing to read like that.

Ok.

> > > 2.4.2: Want to mention the MAC binding as an example here? This
> > > would parallel the OAuth2 method of signing the fetch for a request
> > > token more directly.
> >
> > Nah.
> 
> Let me put it stronger: I would like to see an explicit reference to the MAC
> binding here as an example of a stronger auth binding, along with an
> client secret that was not passed across the wire, and the MAC spec gives
> that capability to OAuth2. I would really like to see that.
> 

Pointing to the MAC specification in this context will be both confusing and against the balance we have reached (with great effort) in how we discuss authentication. No one is a bigger supporter of the MAC proposal than me... and I rather avoid this reference, here.

EHL

---

From: "Lodderstedt, Torsten" <[email-masked]>
Date: Thu, 18 Aug 2011 09:24:25 +0200

>Not sure. What do others think? I put access token first because it is a more important term to get out of the >way.

I would rather consider to change order to Access Token, Refresh Token, Authorization Grant since the first two are the core OAuth concepts developers must become familiar with. Authorization grants are "just" an mean to an end to get the token for certain client types. Moreover, I expect the number of authorization grants to increase over time.

>I'm ok with that. Anyone else?

+1

regards,
Torsten.

---

From: Justin Richer <[email-masked]>
Date: Thu, 18 Aug 2011 10:29:04 -0400

> I would rather consider to change order to Access Token, Refresh Token, Authorization Grant since the first two are the core OAuth concepts developers must become familiar with. Authorization grant…

You have to use *some* kind of authorization grant to get any kind of
token, and this part of the OAuth spec is all about "how to get a token
in a programmatic way". I agree that there will be many more types of
auth grants in the future, and that's why I think it should be the first
concept in the list.

I can see the logic of putting both token types first (though I still
prefer the auth grant first), but having the auth grant in between the
two token types is definitely a bad idea.

 -- Justin

---

From: Torsten Lodderstedt <[email-masked]>
Date: Thu, 18 Aug 2011 16:49:35 +0200

+1

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