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
_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth
