Subject: [OAUTH-WG] Draft 12 - Protocol flow not clear yet

From: Phil Hunt <[email-masked]>
Date: Sun, 23 Jan 2011 12:23:22 -0800

Section 4 seems to inter-mixes obtaining authorization grant with obtaining tokens. Yes it is called "Request an Access Token".  This seems particularly confusing after reading section 3 that separates requesting authorization from token end-points. My first reaction was, is there a section missing?

After I began reading section 4 it starts talking about obtaining authorization. Should section 4 be "protocol flow"?

I think it can work with an intro explaining the protocol at a high level. E.g. 3 steps:
1. Obtain authorization from Authorization Endpoint
2. Obtain access token from Token Endpoint
3. Access resource

Then for each flow pattern, show how steps 1, 2, and 3 are completed.  For 2-legged cases, indicate how step 1 is completed implicitly (e.g. by policy, previous arrangement, or OOB).

It might also be better if section 5 became a sub-section within 4.0. I see why it is separate, since the last step is always the same. But still it added to my initial confusion.  

The general impression I have is draft 12, is half way to a flow orientation as suggested by Eran. 

ps. I still remain neutral on structure (end-point vs. flow) as long as it is clear.

Regards,
 
Phil
[email-masked]

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 25 Jan 2011 23:42:02 -0700

Thanks Phil.

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Phil Hunt
> Sent: Sunday, January 23, 2011 12:23 PM
> To: [email-masked] WG
> Subject: [OAUTH-WG] Draft 12 - Protocol flow not clear yet
> 
> Section 4 seems to inter-mixes obtaining authorization grant with obtaining
> tokens. Yes it is called "Request an Access Token".  This seems particularly
> confusing after reading section 3 that separates requesting authorization
> from token end-points. My first reaction was, is there a section missing?

Section 4 describes how to ask for an access token using different grant types. Some of these grant types require an explicit authorization step.

> Should section 4 be "protocol flow"?

I don't have a strong view on the section title, but I do have a strong view on its structure.

> 1. Obtain authorization from Authorization Endpoint 2. Obtain access token
> from Token Endpoint 3. Access resource

You mean section 1.1? I will break it into two, one for roles and the other for protocol flow. I want to keep all the prose in the introduction and leave the rest only to implementation specific details.
 
> Then for each flow pattern, show how steps 1, 2, and 3 are completed.  For 2-
> legged cases, indicate how step 1 is completed implicitly (e.g. by policy,
> previous arrangement, or OOB).

I don't think this is necessary. If the introduction isn't detailed enough, we need to fix that.

> It might also be better if section 5 became a sub-section within 4.0. I see why
> it is separate, since the last step is always the same. But still it added to my
> initial confusion.

All the section 4 subsections are grant types and moving 5 there will be more confusing. I will add a document overview in the introduction to cover this.
 
EHL