[OAUTH-WG] Draft 20 last call comments

Justin Richer <jricher@mitre.org> Thu, 11 August 2011 21:06 UTC

Return-Path: <jricher@mitre.org>
X-Original-To: oauth@ietfa.amsl.com
Delivered-To: oauth@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id C8DA621F87C3 for <oauth@ietfa.amsl.com>; Thu, 11 Aug 2011 14:06:53 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -6.554
X-Spam-Level:
X-Spam-Status: No, score=-6.554 tagged_above=-999 required=5 tests=[AWL=0.045, BAYES_00=-2.599, RCVD_IN_DNSWL_MED=-4]
Received: from mail.ietf.org ([12.22.58.30]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id OCbgV16dSln7 for <oauth@ietfa.amsl.com>; Thu, 11 Aug 2011 14:06:53 -0700 (PDT)
Received: from smtpksrv1.mitre.org (smtpksrv1.mitre.org [198.49.146.77]) by ietfa.amsl.com (Postfix) with ESMTP id 30ACD21F8783 for <oauth@ietf.org>; Thu, 11 Aug 2011 14:06:53 -0700 (PDT)
Received: from smtpksrv1.mitre.org (localhost.localdomain [127.0.0.1]) by localhost (Postfix) with SMTP id 5FE2C21B174F for <oauth@ietf.org>; Thu, 11 Aug 2011 17:07:24 -0400 (EDT)
Received: from imchub1.MITRE.ORG (imchub1.mitre.org [129.83.29.73]) by smtpksrv1.mitre.org (Postfix) with ESMTP id 57B7C21B094C for <oauth@ietf.org>; Thu, 11 Aug 2011 17:07:24 -0400 (EDT)
Received: from [129.83.50.1] (129.83.50.1) by imchub1.MITRE.ORG (129.83.29.73) with Microsoft SMTP Server id 8.3.192.1; Thu, 11 Aug 2011 17:07:24 -0400
From: Justin Richer <jricher@mitre.org>
To: "OAuth WG (oauth@ietf.org)" <oauth@ietf.org>
Content-Type: text/plain; charset="UTF-8"
Date: Thu, 11 Aug 2011 17:06:51 -0400
Message-ID: <1313096811.22073.96.camel@ground>
MIME-Version: 1.0
X-Mailer: Evolution 2.32.2
Content-Transfer-Encoding: 7bit
Cc: "Anganes, Amanda L" <aanganes@mitre.org>
Subject: [OAUTH-WG] Draft 20 last call comments
X-BeenThere: oauth@ietf.org
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: OAUTH WG <oauth.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/oauth>, <mailto:oauth-request@ietf.org?subject=unsubscribe>
List-Archive: <http://www.ietf.org/mail-archive/web/oauth>
List-Post: <mailto:oauth@ietf.org>
List-Help: <mailto:oauth-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/oauth>, <mailto:oauth-request@ietf.org?subject=subscribe>
X-List-Received-Date: Thu, 11 Aug 2011 21:06:53 -0000

In addition to taking another read through the document myself, I asked
another developer here to give it a once over. She's never implemented
an OAuth client or server, but has knowledge of what it's for. Thus, an
experienced developer new to building with OAuth2 -- a key target
audience for these documents.

As you'll see here, most of our qualms are in the front matter of the
document. The actually gritty technical implementation details are
pretty solid at this point.

1.2/1.4: The term "authorization grant" remains confusing and the
introduction is riddled with jargon like "intermediate credential". With
the diagram in 1.2, it appears to be an explicit technological
underpinning of the protocol flow instead of a general conceptual
construct that is used in several different ways. Basically, what
"authorization grant" *means* is not obvious within this document.
Section 4 makes much more sense than the introduction text does here.
Perhaps we should just replace most of 1.4 with just the introductory
text to 4 (perhaps slightly expanded), and then a reference to the
sub-parts of section 4 for the meat of the concept (and in the process,
nix the subsections of 1.4 entirely).

1.2(B): "Provided" is wrong here (it implies a direct hand-over), and
the last sentence is awkward. Suggest reword to: 
        The client receives an authorization grant which represents the
        authorization granted by the resource owner.  The type of 
	authorization grant is dependent on which methods are supported
	by both the client and authorization server.

1.3/1.4/1.5: Consider switching order to Authorization Grant, Access
Token, Refresh Token

1.4.1: We probably want to mention a user agent here in the exposure
risk at the end. Since that's really the problem -- the browser could
steal the token, not the end user.

1.4.2: Still don't like the term "implicit". It's misleading. Even
"direct authorization" would be better, though still not ideal.

1.4.5: Throw a simple reference to 8.3 here?

2: Isn't "means" generally treated as singular in instances like this?
Thus "means ... is" instead of "means ... are".

2.1/2.2: The requirements (2.2) should go first in section 2. The client
types are part of deciding the requirements, and the concepts flow
better this way.

2.1: I like the calling out of the types of clients, it helps cement
things.

2.3: Suggest renaming to "Client Identification" to parallel "Client
Authentication" in 2.4

2.3: Should "... cannot be used alone" be made into a normative, as "...
MUST NOT be used alone"?

2.4.2: Want to mention the MAC binding as an example here? This would
parallel the OAuth2 method of signing the fetch for a request token more
directly.

3. Authorization endpoint's "used to obtain authorization from" should
be "used to obtain an authorization grant from", to be parallel with the
token endpoint description.


 -- Justin