Subject: [OAUTH-WG] Editorial feedback on 4/17 draft

From: Dick Hardt <[email-masked]>
Date: Sun, 18 Apr 2010 20:56:09 -0700

General comments:

Putting the flow description, diagram and steps in the section with the spec work well.

Use of "server" term. In numerous places, the term server is used instead of authorization server or resource server (maybe even web server). To avoid ambiguity, I would suggest the term server is never used, and the spec is explicit on which server is being referred to.

User authentication at AS: Suggest putting this in one section and then referring to it in 3.5.2.1 and 3.5.3.1 (and adding into 3.5.1)

Having 5 levels of sections seems overly deep with the bulk of the document being in 3.5 and 3.6.

Sections 4 and 5 seem weaker than the other sections. Would you like me to take a stab at rewriting those?

2. Introduction

These resources are usually private ...

Why the use of the word "private" instead of "protected"?

Description of autonomous flow is missing.

2.1 

authorization endpoint
         The authorization server's HTTP endpoint capable of
         authenticating the resource owner and obtaining authorization,
         issuing tokens, and refreshing expired tokens.

Does the authorization endpoint issue tokens and refresh tokens? I thought that was only the token endpoint.

   client identifier
         An unique identifier issued by the client to identify itself to
         the authorization server.  Client identifiers may have a
         matching secret.

Why does the client identifier have to be issues by the client? Could it not be issued by the AS?

Why are verification code, user code, device code not defined?

2.2

 access token (or under revoked), the authorization server should

Typo

 access token (or until revoked), the authorization server should

3

   In many cases it is desirable to issue access tokens with a shorter
   lifetime than the duration of the authorization grant.  However, it
   is undesirable to require the resource owner to authorize the request
   again.  Instead, the authorization server issues a refresh token in

suggested change:

   In many cases it is desirable to issue access tokens with a shorter
   lifetime than the duration of the authorization grant.  However, it
   may be undesirable to require the resource owner to authorize the request
   again.  Instead, the authorization server issues a refresh token in

3.3

In WRAP we had a section entitled Parameter Considerations where many errata about parameters was contained.

3.5

User delegation flows are used to grant client access to protected
   resources by the end user without sharing the end user credentials
   (typically a username and password) with the client.  Instead, the
   end user authenticates directly with the authorization server, and
   grants client access to its protected resources.

suggested change:

User delegation flows are used to grant client access to protected
   resources by the end user without sharing the end user credentials
   (such as a username and password) with the client.  Instead, the
   end user authenticates directly with the authorization server, and
   grants client access to its protected resources.

3.5.1

Why does the user not have to authenticate to the AS in this flow?

3.5.1.2

It is unclear to me how to make the user-agent NOT include the fragment. 

3.5.3

The terms for the different codes is not consistent. client code, client verification code, device code, device verification code

3.5.3.5.1

   If the end user authorized the request, the authorization server
   issues and access token and delivers is to the client by including it

typo:

 If the end user authorized the request, the authorization server
 issues an access token and delivers is to the client by including it

3.5.3.2.3

Great to have all the different error conditions. Spec should discuss what the client should do for each error code.

3.7.1 and 3.7.2 (diagrams 7 & 8)

Need to add

(w/ Optional Refresh Token) 

to be consistent with other diagrams and that refresh is optional in all calls

3.7.2.1

format parameter. Not sure why this undefined parameter is ok, but scope is not! :)
The example needs a little fleshing out. :)

4.

While the section introduction describes how it can be used to obtain tokens with different security parameters and getting a secret, how and when the developer would make different calls is unspecified.

The following statement is not always possible:

   The authorization server MUST invalidate the old access token being
   replaced.

If the access token is self contained, then the authorization server cannot invalidate it.

5.1

   The "Authorization" request header field is used by clients to make
   both bearer token and cryptographic token requests. 

This statement implies that this is the only way to make requests. Perhaps introduce section 5 by clearly stating there are different mechanisms for transporting the access token?

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Sun, 18 Apr 2010 23:35:54 -0700

Thanks Dick! This is incredibly useful. I'll apply all the comments to the spec tomorrow before pushing it as -00 (pending chairs approval).

I'll reply to the (very few) comments I didn't agree/understand once I have a new draft.

EHL

From: Dick Hardt [mailto:[email-masked]]
Sent: Sunday, April 18, 2010 8:56 PM
To: Eran Hammer-Lahav
Cc: OAuth WG
Subject: Editorial feedback on 4/17 draft

General comments:

2. Introduction

2.1

authorization endpoint

   client identifier

         matching secret.

2.2

Typo

3

suggested change:

3.3

3.5

suggested change:

3.5.1

3.5.1.2

3.5.3

3.5.3.5.1

typo:

3.5.3.2.3

Need to add

3.7.2.1

4.

   replaced.

5.1

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 21 Apr 2010 12:56:45 -0700

Thanks Dick!

Comments already applied are not listed below.

> -----Original Message-----
 
> Use of "server" term. In numerous places, the term server is used instead of
> authorization server or resource server (maybe even web server). To avoid
> ambiguity, I would suggest the term server is never used, and the spec is
> explicit on which server is being referred to.

In the user-agent flow, a web-server is another entity and is required.
 
> User authentication at AS: Suggest putting this in one section and then
> referring to it in 3.5.2.1 and 3.5.3.1 (and adding into 3.5.1)

3.1 has that text. The rest just say 'authenticate the end user'.

> Having 5 levels of sections seems overly deep with the bulk of the document

True, but if you look at the TOC, the structure makes sense.

> Sections 4 and 5 seem weaker than the other sections.

Not sure about section 4, but section 5 needs review before I spend more time on editorial work.
 
> Description of autonomous flow is missing.

Where?

> Why are verification code, user code, device code not defined?

I'm not sure they qualify as terms, but I can add them if people feel it is helpful. I felt they are more flow specific.

> errata about parameters was contained.

I'll import the missing bits in a later draft.
 
> It is unclear to me how to make the user-agent NOT include the fragment.

It is not supposed to. HTTP requests do not include the fragment. The user-agent removes it before making the request.

RFC 3986:

the fragment identifier is separated
   from the rest of the URI prior to a dereference, and thus the
   identifying information within the fragment itself is dereferenced
   solely by the user agent, regardless of the URI scheme.

> client should do for each error code.

We need to review first if the error codes are complete. I'm sure there are more.

> 3.7.2.1
> 
> format parameter. Not sure why this undefined parameter is ok, but scope is
> not! :) The example needs a little fleshing out. :)

It's not ok. I need to incorporate text from Chuck's proposal.

> 4.
> 
> While the section introduction describes how it can be used to obtain tokens
> with different security parameters and getting a secret, how and when the
> developer would make different calls is unspecified.

What do you mean by different calls?

EHL