+1 for option 2 - flow based organization
From: [email protected] [mailto:[email protected]] 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
[email protected]
https://www.ietf.org/mailman/listinfo/oauth
