I prefer #1. EHL
From: oauth-boun...@ietf.org [mailto:oauth-boun...@ietf.org] 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 (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
_______________________________________________ OAuth mailing list OAuth@ietf.org https://www.ietf.org/mailman/listinfo/oauth
