Subject: [OAUTH-WG] return to draft 6 spec org?

From: Brian Eaton <[email-masked]>
Date: Sat, 10 Jul 2010 21:15:20 -0700

I think it would be a good idea to return to the draft 6 organization.

Draft 6: normative language for each flow was called out separately,
and was described from start to finish, in chronological order, with
no interruption.  Each step showed what a client should send, and what
an authorization server should return.

Draft 7 and further: flows are merged to reuse spec language.  Steps
for any given use case are now interrupted with steps for other use
cases.

For example, consider a client developer who wants to implement the
web server flow.

First they have to read section 3.1, to describe the redirect they
need to send to the authorization server.

Then they read section 3.2, to see the redirect back.

Then they read section 4.1.1, to see the request they send to the
authorization server.

Then they skip a few pages, because they don't care about assertions
or passwords or refresh tokens.

They they read section 4.2, to see the response from the authorization server.

Then they skip several more pages to get to section 5, so they can access data.

Then they skip back to section 4.1.4, because they need to refresh their token.

Compare this to draft 6:
- read section 2.5
   this is everything you need to get a token, with no intervening
cruft about credentials you don't have.

- read section 4
   this is everything you need to use a token.

- read section 3
   this is everything you need to refresh a token.

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Sun, 11 Jul 2010 07:37:43 -0700

The spec organization isn't about reusing prose, but about providing a consistent and well-defined protocol architecture. WRAP called the different flows for each client 'profiles' which was wrong in WRAP because it wasn't actually profiling anything - it was describing completely separate flows. The current spec went back to calling them profiles because now they are truly profiles of the generic framework defined by the two endpoints.

I am unhappy with the current state of the client profiles in the introduction so we agree on that. But where you call for a complete restructure, I prefer making the current structure more useful.

I think the way to solve it is to make them more detailed and normative. This will retain the general framework as current specified, but will provide a reference-able description of useful profiles. This will also make it easier to discuss the security attributes of each profile. In addition, it is probably only be useful to define the user-agent and web-based as fully specified profiles, given that the rest are not really profiles but vague guidelines as to how to use OAuth for other "stuff".

EHL

On 7/10/10 9:15 PM, "Brian Eaton" <[email-masked]> wrote:

Compare this to draft 6:
- read section 2.5

- read section 4

- read section 3

Cheers,
Brian
_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: Brian Eaton <[email-masked]>
Date: Mon, 12 Jul 2010 23:22:34 -0700

On Sun, Jul 11, 2010 at 7:37 AM, Eran Hammer-Lahav <[email-masked]> wrote:
> I think the way to solve it is to make them more detailed and normative.
> This will retain the general framework as current specified, but will
> provide a reference-able description of useful profiles. This will also make
> it easier to discuss the security attributes of each profile. In addition,
> it is probably only be useful to define the user-agent and web-based as
> fully specified profiles, given that the rest are not really profiles but
> vague guidelines as to how to use OAuth for other “stuff”.

Actually, the old "vague guidelines" weren't vague, and they weren't
guidelines.  They were very specific instructions on how flows should
be implemented.  They dated back to the WRAP specification, which
multiple organizations reviewed carefully because they were all going
to implement those flows the exact same way.

The new spec has turned what used to be very precise language into
mush.  It's introduced confusion and security problems that weren't
present originally.  Please fix them.

The client credentials flow is a great point of comparison.

Here's dick's draft:
http://tools.ietf.org/html/draft-hardt-oauth-01#section-5.1.2

Here's draft 6: http://tools.ietf.org/html/draft-ietf-oauth-v2-06#section-2.9.1

Here's draft 10: http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-4.1

Dick's draft:
- clear guidance on use case
- obvious normative language specifying exactly one way to send a request,
- one success response
- one error response
- normative language specifying error handling

Draft 6:
- vague guidance on use case
- obvious normative language specifying exactly one way to send a request,
- two success responses, with no way to distinguish which the server
should send.  But one of them is insecure.
- one error response
- no normative language specifying error handling

Draft 10:
- no guidance on use case
- confusing normative language
- two success responses, with no way to distinguish which the server
should send.  But one of them is insecure.
- six different error responses (most of which don't make sense for
the use case and will never be used.)
- no normative language specifying error handling

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 13 Jul 2010 08:11:15 -0700

On 7/12/10 11:22 PM, "Brian Eaton" <[email-masked]> wrote:

>> vague guidelines as to how to use OAuth for other ³stuff².
> 

I used 'vague guidelines' to described the information provided for *when*
to use the flows, not *how* to use them.

- user-agent and web-server are suitable for clients other than just code
running in a browser or on a web-server, as made clear by the native
application text.

- assertion flow was always underspecified (for a reason) and provided
little to no useful information on when it should be used - it assumed
people who currently use SAML or similar assertions will just "know what to
do". This isn't very helpful to new readers.

- client credentials information was always problematic because people
expressed interest in using it with pre-arranged authorizations, in which
case, the client may be acting on behalf of an end-user.

- username and password is really the only straightforward flow because it
doesn't specify any client type, but only client conditions. However, this
is the one profile I'd like to make less prominent.

- device was removed (at your request) due to lack of deployment experience.

> present originally.  Please fix them.

You keep saying that (very dramatically!). However, you offer very little
details for these "security problems" and "confusion". I have addressed
every specific issue you raised.

I suggested adding actual profiles to the spec, which would accomplish what
your want to see "restored". However it is not clear to me how to name these
and how to guide developers when to use them. We have been unable to reach
agreement on these guidelines for months because everyone has other plans
for how they plan to use it (user-agent flow for mobile device as native
app, client credentials for pre-arranged delegation, assertions for both
client only and end-user resources, web server for in-browser).

> http://tools.ietf.org/html/draft-hardt-oauth-01#section-5.1.2

   This profile is suitable when the Client is an application calling
   the Protected Resource on behalf of an organization and the
   Authorization Server accepts account passwords for authentication.
   This enables the Authorization Server to use an existing
   authentication mechanism.  This profile SHOULD NOT be used when the
   Client is acting on behalf of a user.

I don't know what this mean. What is an 'organization' (it is the only time
the term is used)? What is the difference between an 'organization' and
'end-user'? Why can't this be used for end-user delegation when it is
pre-arranged, just like the assertion profile? After all, basic client
credentials are nothing more than one special case assertion.

> Here's draft 6: 
> http://tools.ietf.org/html/draft-ietf-oauth-v2-06#section-2.9.1

   The client credentials flow is used when the client acts on behalf of
   itself (the client is the resource owner), or when the client
   credentials are used to obtain an access token representing a
   previously established access authorization.  The client secret is
   assumed to be high-entropy since it is not designed to be memorized
   by an end-user.

This is my attempt to represent the group's consensus on when this flow
should be used. Previous text limiting it to only "client acts on behalf of
itself" were rejected.

> Here's draft 10: http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-4.1

   When requesting an access token using the "none" access grant type
   (no access grant is included), the client is requesting access to the
   protected resources under its control, or those of another resource
   owner which has been previously arranged with the authorization
   server (the method of which is beyond the scope of this
   specification).

This says the same thing as -06 but from the flip side (what 'none' means
instead of describing the use case). However, the introduction includes
additional information in section 1.4.4 which is where the client crendetial
text ended up.

http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-1.4.4

   Autonomous clients utilize an existing trust relationship or
   framework to establish authorization.  Autonomous clients can be
   implemented in different ways based on their requirements and the
   existing trust framework they rely upon.  Autonomous clients can:

   o  Obtain an access token by authenticating with the authorization
      server using their client credentials.  The scope of the access
      token is limited to the protected resources under the control of
      the client, or that of another resource owner previously arranged
      with the authorization server.

The reason why it is combined with the assertion profile is because I could
not come up with any text to really differentiate their user-cases (as I
said before, client secret is just a special case assertion).

> - no guidance on use case

Section 1.4.4.

> - confusing normative language

Use 'none'. Seems pretty straightforward.

> should send.  But one of them is insecure.

Where? One in 4.2, where is the other?

> the use case and will never be used.)

Relevant:

invalid_request - request sent incorrectly
invalid_client - bad client credentials
unauthorized_client - client is not allowed to use this profile
unsupported_grant_type - server doesn't support this profile
invalid_scope - client (explicitly) asked for invalid scope

Irrelevant:

invalid_grant

> - no normative language specifying error handling

Section 4.3.

---

I'll move the second paragraph of 4.1 into its own section. That will help
those looking for the "normative language for client credentials".

EHL

---

From: Darren Bounds <[email-masked]>
Date: Tue, 13 Jul 2010 11:34:27 -0400

+1

-- 
darren bounds
[email-masked]

---

From: Brian Eaton <[email-masked]>
Date: Wed, 14 Jul 2010 22:32:06 -0700

> case, the client may be acting on behalf of an end-user.
...
> and how to guide developers when to use them.
...

I've been giving some thought to this problem.

As far as I can tell, here is what has happened.

1) several people have gotten together and put together a
tightly-specified proposal to meet a particular use case
2) that's gotten added
3) others have chimed in with slight modifications to meet slightly
different use cases
4) that's gotten added
5) step 3 and 4 repeat for a while.
6) the detailed proposal written in step 1 and 2 has gotten screwed up

We haven't gotten to step 7 yet, but I'm pretty sure it involves
non-interoperable implementations.

I think the problem here is step 4.  Rather than making everything
optional so we can meet every possible use case, we need to start
telling people to go write up new profiles to meet their use cases.

Given the choice between two tightly specified protocol flows and a
single vague protocol flow, we should prefer tightly specified.

Cheers,
Brian

---

From: Nat <[email-masked]>
Date: Fri, 16 Jul 2010 09:10:18 +0900

As I see, the current draft is half way towards the complete modularization. It has abstracted what parameters are needed for each end points from various flows but failed to stop there and included how they are to be passed as well. IMHO, how they are passed is the profile/binding issue and all these language should be removed and moved to profile specs. 

=nat @ Tokyo via iPhone