Subject: [OAUTH-WG] Specification organization (Endpoints vs. Flows) - Vote by 1/17

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 12 Jan 2011 00:19:17 -0700

(Vote at the end, please read)

Background

Between draft -00 and -05 the document used a flow-based organization. This was changed to an endpoint-based organization in draft -06. I have received requests to go back to the flow-based organization, and with -12, have been planning to do that. It is important to note that -12 is not meant to include any change in normative language and that -11 code would remain unchanged under -12. This is purely editorial.

Part of that effort included reviewing the various flows in -05. The flow categories and definitions have always been a source of confusion. Some target specific client architecture (user-agent, web server, device), some are abstractions for future extensibility (assertion),  and some are useful features that can apply to a wide range of clients (client credentials, username and password). We also have the odd anti-profile of the native application flow, which in practice is a half-baked guide to navigating the entire range of flows.

In practice we have a few ways to get an access token which can be categorized in multiple ways:

1.       How authorization is obtained?

a.       Redirection-based - user-agent, web-server

b.      Direct credentials - client credentials, username and password, assertion

2.       Is the client authenticated?

a.       Yes - web-server, client credentials, username and password, assertion (based on type)

b.      No - user-agent, assertion (based on type)

In the past we had another (broken) organization of User delegation, User credentials, and Autonomous.

Analysis

After studying the document and breaking it apart (in my editor) I came to a few conclusions (which you are invited to disprove):

1.       Flow names must be consistent and based on the key differentiator of each flow. I believe the ability of the client to authenticate is the most significant aspect of each flow. I agree that ease of deployment and performance are important, but this is a security protocol and the security considerations should be the primary attribute used to select flows.

2.       The endpoint-based organization turned a few discrete flows into a single protocol. This protocol should be profiled based on some key client characteristics (such as redirection and ability of the client to authenticate). The main objective of the profiles would be to provide a security-focused description.

3.       The hybrid flow, combining the user-agent and web-server into a code-and-token solution is a distinct profile with its own unique security properties. While its implementation details are important for efficiency, the main differentiator is the client dual nature of being able to maintain secret credentials in some parts, but not in others. It produces two access tokens using a single authorization and client identifier.

4.       The document must not repeat the mistake of 1.0, focusing on a single client type at the expense of others. OAuth 1.0 focused on the web-server flow and treated everything else as second class citizens. -05 treated native applications similarly, giving much more attentions to the web-server and user-agent clients, even when their underlying flows could have been written primarily for some native applications. The issue is mostly in naming the profiles after one typical client type instead of their key property.

Options

I came up with two options for finalizing the specification's structure (please feel to suggest additional ideas):

1.       Keep the document's endpoint-based organization (-11) and add a Client Profiles section describing specific client implementations based on the protocol. These profiles will not include wire information (parameters, values, etc.), but will include security-minded normative language (MUST register, SHOULD match redirection URI, etc.).

2.       Switch back to flow-based organization and include 5 flows in 2 groups (note the new names), plus extensions:

a.       Redirection-based

                                                               i.      Authenticated client (web server)

                                                             ii.      Unauthenticated client (user-agent)

                                                            iii.      Mix authentication client (code-and-token)

b.      Direct Credentials

                                                               i.      Username and password

                                                             ii.      Client credentials

c.       Extensions

Option 1

-          Easier for server developers because it will include all the wire-protocol details for each endpoint in one place (single list of parameters, error codes, etc.).

-          Shorter, no repeating the same examples, parameters, and error definitions for each flow.

-          Reads like a reference.

-          Client developers are instructed which parameter values to use.

-          Server developer focus helps make security-based decisions (which are primarily the role of the server developer in OAuth).

Option 2

-          Easier for client developers focused on one flow at a time.

-          Longer, duplicating examples, parameters, and error definitions. Currently about 20-30 more pages.

-          Reads like a narrative / tutorial.

-          Client developers are instructed which client flow to use.

-          Client developer focus helps novice developers interoperate with protected resources.

I don't believe there is an obvious winner here because we each have a bias based on who we believe is the primary target audience (after all, this is a purely editorial decision - the protocol itself is mostly complete). In addition, I have done 80% of the work to get -12 to option 2 so it is no longer about investing the time in the transition.

Vote

Given the stable state of the specification, this might be the last big decision we get to make about the main specification. I've been planning to just come up with a new draft and ask for feedback but I rather take another week and ask this explicitly.

Which option do you prefer (or suggest another)?

Please reply with your preference by 1/17.

EHL

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 12 Jan 2011 00:25:57 -0700

I prefer #1.

EHL

From: [email-masked] [mailto:[email-masked]] On Behalf Of Eran Hammer-Lahav
Sent: Tuesday, January 11, 2011 11:19 PM
To: OAuth WG
Subject: [OAUTH-WG] Specification organization (Endpoints vs. Flows) - Vote by 1/17

Background

Analysis

Options

a.       Redirection-based

b.      Direct Credentials

                                                                  i.      Username and password

                                                                 ii.      Client credentials

c.       Extensions

Option 1

Option 2

Vote

EHL

---

From: Mike Jones <[email-masked]>
Date: Wed, 12 Jan 2011 07:27:25 +0000

+1 for option 2 - flow based organization

Background

Analysis

Options

a.      Redirection-based

b.      Direct Credentials

                                                    i.     Username and password

                                                   ii.     Client credentials

c.      Extensions

Option 1

Option 2

Vote

EHL

---

From: "Richer, Justin P." <[email-masked]>
Date: Wed, 12 Jan 2011 10:02:50 -0500

+1 for option 2

I see, and have always seen, the target audience as server and client developers who are likely to be working against one flow and use case at a time. Also, I disagree that the primary role of the server developer is the security considerations. In theory, you may be right, but in practice, I think you'll find that many are going to be more concerned with just making it work at all with their API/framework/server.

 -- Justin
________________________________________
From: [email-masked] [[email-masked]] On Behalf Of Eran Hammer-Lahav [[email-masked]]
Sent: Wednesday, January 12, 2011 2:19 AM
To: OAuth WG
Subject: [OAUTH-WG] Specification organization (Endpoints vs. Flows) - Vote     by 1/17

Background

a.       Redirection-based – user-agent, web-server

b.      Direct credentials – client credentials, username and password, assertion

a.       Yes – web-server, client credentials, username and password, assertion (based on type)

b.      No – user-agent, assertion (based on type)

Analysis

Options

I came up with two options for finalizing the specification’s structure (please feel to suggest additional ideas):

1.       Keep the document’s endpoint-based organization (-11) and add a Client Profiles section describing specific client implementations based on the protocol. These profiles will not include wire information (parameters, values, etc.), but will include security-minded normative language (MUST register, SHOULD match redirection URI, etc.).

a.       Redirection-based

b.      Direct Credentials

                                                               i.      Username and password

                                                             ii.      Client credentials

c.       Extensions

Option 1

Option 2

I don’t believe there is an obvious winner here because we each have a bias based on who we believe is the primary target audience (after all, this is a purely editorial decision – the protocol itself is mostly complete). In addition, I have done 80% of the work to get -12 to option 2 so it is no longer about investing the time in the transition.

Vote

Given the stable state of the specification, this might be the last big decision we get to make about the main specification. I’ve been planning to just come up with a new draft and ask for feedback but I rather take another week and ask this explicitly.

EHL

---

From: Marius Scurtescu <[email-masked]>
Date: Wed, 12 Jan 2011 10:10:38 -0500

+1 for option 2 as well

Not convinced that naming the main flows Authenticated and
Unauthenticated makes sense, I think it will only increase confusion.
For example, native apps are not authenticated and they would be using
the "Authenticated" flow. I think we should stick with something along
the lines of "Code" and "Token".

Marius

On Wed, Jan 12, 2011 at 10:02 AM, Richer, Justin P. <[email-masked]> wrote:
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>

---

From: "Richer, Justin P." <[email-masked]>
Date: Wed, 12 Jan 2011 10:15:54 -0500

Marius makes a good point -- we probably want to avoid using language like that for part descriptions. I don't think "code" and "token" quite get it, but I don't have a better suggestion at the moment though...

 -- Justin
________________________________________
From: Marius Scurtescu [[email-masked]]
Sent: Wednesday, January 12, 2011 10:10 AM
To: Richer, Justin P.
Cc: Eran Hammer-Lahav; OAuth WG
Subject: Re: [OAUTH-WG] Specification organization (Endpoints vs. Flows) - Vote by 1/17

+1 for option 2 as well

Marius

---

From: Dick Hardt <[email-masked]>
Date: Wed, 12 Jan 2011 08:22:52 -0800

+1 for flow based option (#2) -- it prioritizes the security implications, and then readability for a much larger audience (client developer)

---

From: Jeremy Kemper <[email-masked]>
Date: Wed, 12 Jan 2011 09:54:36 -0800

+1 for option 2.

Implementing and testing against draft 5 was wonderful.

On Tue, Jan 11, 2011 at 11:19 PM, Eran Hammer-Lahav <[email-masked]> wrote:
> Between draft -00 and -05 the document used a flow-based organization. This
> was changed to an endpoint-based organization in draft -06. I have received
> requests to go back to the flow-based organization, and with -12, have been
> planning to do that. It is important to note that -12 is not meant to
> include any change in normative language and that -11 code would remain
> unchanged under -12. This is purely editorial.
>
>
>
> Part of that effort included reviewing the various flows in -05. The flow
> categories and definitions have always been a source of confusion. Some
> target specific client architecture (user-agent, web server, device), some
> are abstractions for future extensibility (assertion),  and some are useful
> features that can apply to a wide range of clients (client credentials,
> username and password). We also have the odd anti-profile of the native
> application flow, which in practice is a half-baked guide to navigating the
> entire range of flows.
>
>
>
> After studying the document and breaking it apart (in my editor) I came to a
> few conclusions (which you are invited to disprove):
>
>
>
> 1.       Flow names must be consistent and based on the key differentiator
> of each flow. I believe the ability of the client to authenticate is the
> most significant aspect of each flow. I agree that ease of deployment and
> performance are important, but this is a security protocol and the security
> considerations should be the primary attribute used to select flows.
>
> 2.       The endpoint-based organization turned a few discrete flows into a
> single protocol. This protocol should be profiled based on some key client
> characteristics (such as redirection and ability of the client to
> authenticate). The main objective of the profiles would be to provide a
> security-focused description.
>
> 3.       The hybrid flow, combining the user-agent and web-server into a
> code-and-token solution is a distinct profile with its own unique security
> properties. While its implementation details are important for efficiency,
> the main differentiator is the client dual nature of being able to maintain
> secret credentials in some parts, but not in others. It produces two access
> tokens using a single authorization and client identifier.
>
> 4.       The document must not repeat the mistake of 1.0, focusing on a
> single client type at the expense of others. OAuth 1.0 focused on the
> web-server flow and treated everything else as second class citizens. -05
> treated native applications similarly, giving much more attentions to the
> web-server and user-agent clients, even when their underlying flows could
> have been written primarily for some native applications. The issue is
> mostly in naming the profiles after one typical client type instead of their
> key property.
>
>
>
> Options
>
>
>
> I came up with two options for finalizing the specification’s structure
> (please feel to suggest additional ideas):
>
>
>
> 1.       Keep the document’s endpoint-based organization (-11) and add a
> Client Profiles section describing specific client implementations based on
> the protocol. These profiles will not include wire information (parameters,
> values, etc.), but will include security-minded normative language (MUST
> register, SHOULD match redirection URI, etc.).
>
> 2.       Switch back to flow-based organization and include 5 flows in 2
> groups (note the new names), plus extensions:
>
> a.       Redirection-based
>
>                                                                i.
>                                                                i.
> Username and password
>                                                              ii.      Client
> credentials
> -          Easier for server developers because it will include all the
> wire-protocol details for each endpoint in one place (single list of
> parameters, error codes, etc.).
>
> -          Server developer focus helps make security-based decisions (which
> are primarily the role of the server developer in OAuth).
>
>
>
> Option 2
>
> I don’t believe there is an obvious winner here because we each have a bias
> based on who we believe is the primary target audience (after all, this is a
> purely editorial decision – the protocol itself is mostly complete). In
> addition, I have done 80% of the work to get -12 to option 2 so it is no
> longer about investing the time in the transition.
>
>
>
> Vote
>
>
>
> Given the stable state of the specification, this might be the last big
> decision we get to make about the main specification. I’ve been planning to
> just come up with a new draft and ask for feedback but I rather take another
> week and ask this explicitly.
>
>
>

---

From: Torsten Lodderstedt <[email-masked]>
Date: Wed, 12 Jan 2011 22:06:10 +0100

+1 for option 2 because it will facilitates security analysis of the 
protocol.

 From a security analysis perspective, I think we need two views:
1) A structural view, describing the OAuth architecture (entities, 
interfaces, communication paths) and
2) a flow-oriented view, which is built based on this interfaces, this 
is where the more complex threats show up. For example, the session 
fixation attack makes use of properties of the flow along both OAuth 
end-points.

I assume a structural view will given as well?

I agree with Marius regarding naming. I don't believe we can forsee 
today which clients will be authenticated in the future and which not. I 
could imagine deployments with support for web applications w/o 
authentication. It depends on the security policy and the value someone 
sees in client authentication (for the purpose of client authorization). 
On the other hand, by using dynamically created client_ids and secrets, 
even native apps could authenticate to the authorization server.

regards,
Torsten.

Am 12.01.2011 16:15, schrieb Richer, Justin P.:
> On Wed, Jan 12, 2011 at 10:02 AM, Richer, Justin P.<[email-masked]>  wrote:
>> +1 for option 2
>>

---

From: Brian Campbell <[email-masked]>
Date: Sun, 16 Jan 2011 20:29:09 -0700

I guess I'm in the minority but I prefer option #1.

I do agree with others that naming with respect to authenticated vs.
unauthenticated clients is likely problematic.

On Wed, Jan 12, 2011 at 2:06 PM, Torsten Lodderstedt <
[email-masked]> wrote:

> 2) a flow-oriented view, which is built based on this interfaces, this is
> where the more complex threats show up. For example, the session fixation
> attack makes use of properties of the flow along both OAuth end-points.
>
> I agree with Marius regarding naming. I don't believe we can forsee today
> which clients will be authenticated in the future and which not. I could
> imagine deployments with support for web applications w/o authentication. It
> depends on the security policy and the value someone sees in client
> authentication (for the purpose of client authorization). On the other hand,
> by using dynamically created client_ids and secrets, even native apps could
> authenticate to the authorization server.
>
> regards,
> Torsten.
>
>  Marius makes a good point -- we probably want to avoid using language like
>> that for part descriptions. I don't think "code" and "token" quite get it,
>> but I don't have a better suggestion at the moment though...
>>
>>  -- Justin
>>> I see, and have always seen, the target audience as server and client
>>> developers who are likely to be working against one flow and use case at a
>>> time. Also, I disagree that the primary role of the server developer is the
>>> security considerations. In theory, you may be right, but in practice, I
>>> think you'll find that many are going to be more concerned with just making
>>> it work at all with their API/framework/server.
>>>
>>>  -- Justin
>>> Between draft -00 and -05 the document used a flow-based organization.
>>> This was changed to an endpoint-based organization in draft -06. I have
>>> received requests to go back to the flow-based organization, and with -12,
>>> have been planning to do that. It is important to note that -12 is not meant
>>> to include any change in normative language and that -11 code would remain
>>> After studying the document and breaking it apart (in my editor) I came
>>> to a few conclusions (which you are invited to disprove):
>>>
>>>
>>> 1.       Flow names must be consistent and based on the key
>>> differentiator of each flow. I believe the ability of the client to
>>> authenticate is the most significant aspect of each flow. I agree that ease
>>> of deployment and performance are important, but this is a security protocol
>>> and the security considerations should be the primary attribute used to
>>> select flows.
>>>
>>> 2.       The endpoint-based organization turned a few discrete flows into
>>> a single protocol. This protocol should be profiled based on some key client
>>>  Authenticated client (web server)
>>>
>>>                                                             ii.
>>>                                                             ii.
>>>  Client credentials
>>> -          Server developer focus helps make security-based decisions
>>> (which are primarily the role of the server developer in OAuth).
>>>
>>> Option 2
>>>
>>> -          Longer, duplicating examples, parameters, and error
>>> definitions. Currently about 20-30 more pages.
>>>
>>> I don’t believe there is an obvious winner here because we each have a
>>> bias based on who we believe is the primary target audience (after all, this
>>> is a purely editorial decision – the protocol itself is mostly complete). In

---

From: Anthony Nadalin <[email-masked]>
Date: Tue, 18 Jan 2011 17:44:26 +0000

I also support option #1

From: [email-masked] [mailto:[email-masked]] On Behalf Of Brian Campbell
Sent: Sunday, January 16, 2011 7:29 PM
To: OAuth WG
Subject: Re: [OAUTH-WG] Specification organization (Endpoints vs. Flows) - Vote by 1/17

I do agree with others that naming with respect to authenticated vs. unauthenticated clients is likely problematic.
On Wed, Jan 12, 2011 at 2:06 PM, Torsten Lodderstedt <[email-masked]<mailto:[email-masked]>> wrote:
+1 for option 2 because it will facilitates security analysis of the protocol.

>From a security analysis perspective, I think we need two views:
1) A structural view, describing the OAuth architecture (entities, interfaces, communication paths) and
2) a flow-oriented view, which is built based on this interfaces, this is where the more complex threats show up. For example, the session fixation attack makes use of properties of the flow along both OAuth end-points.

I agree with Marius regarding naming. I don't believe we can forsee today which clients will be authenticated in the future and which not. I could imagine deployments with support for web applications w/o authentication. It depends on the security policy and the value someone sees in client authentication (for the purpose of client authorization). On the other hand, by using dynamically created client_ids and secrets, even native apps could authenticate to the authorization server.

regards,
Torsten.

 -- Justin
From: Marius Scurtescu [[email-masked]<mailto:[email-masked]>]

+1 for option 2 as well

Marius

On Wed, Jan 12, 2011 at 10:02 AM, Richer, Justin P.<[email-masked]<mailto:[email-masked]>>  wrote:
+1 for option 2

 -- Justin
________________________________________
From: [email-masked]<mailto:[email-masked]> [[email-masked]<mailto:[email-masked]>] On Behalf Of Eran Hammer-Lahav [[email-masked]<mailto:[email-masked]>]
Sent: Wednesday, January 12, 2011 2:19 AM
To: OAuth WG
Subject: [OAUTH-WG] Specification organization (Endpoints vs. Flows) - Vote     by 1/17

Background

Analysis

Options

a.       Redirection-based

b.      Direct Credentials

                                                              i.      Username and password

                                                            ii.      Client credentials

c.       Extensions

Option 1

Option 2

Vote

EHL

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

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