Review of draft-wmills-oauth-lrdd-06.txt

[Jan Algermissen <[e-mail]>]

[Resending this and added some comments on decoupling at the end]

Hi,

this is a review of draft-wmills-oauth-lrdd-06.txt

Jan


Overall:

"link type" -> "link relation type"


1. Introduction

I don't think that the I-D needs to reference "Web Host Metadata" and "Web Finger" specs. The means of using the relation types is orthogonal to their specification.

3. OAuth 2 Link Types  (-> "Link Relation Types" :-)

Consider s/endpoint/entrypoint/g - I know that OAuth uses 'endpoint', but the proper term on the Web would really be 'entry point'

3.1 [Change headline to:] The 'oauth2-authorize' Link Relation Type

Suggested rewording:

"This link relation type indicates a resource that represents an OAuth 2 authorization entry point to be used
  for user authentication/authorization to grant access to a protected
  resource."


3.2 [Change headline to:] The 'oauth2-token' Link Relation Type

Suggested rewording:

"This link relation type indicates a resource that represents an OAuth 2 token entry point to be used for obtaining
tokens to access protected services.  This link type has two link-extensions: ...."


4.1 - 4.3

Likewise 3.1 and 3.2 change the headline and text. What is to be defined here is not the endpoint (erm, entry point) but the link relation type.


In addition, I second Julian's comments made here:

http://www.ietf.org/mail-archive/web/link-relations/current/msg00418.html

One final remark,

Given that there are a number of OAuth-ish protocols existing and emerging I think it would be a good idea to investigate decoupling the link relation types from these protocols - if possible. An 'authorization endpoint' likely has the same semantic across all of those protocols.

If clients can determine the actual variant at runtime, *after* discovering the entry point resources we would not need to register virtualy the same link relation types over and over again for all the protcols.

Please do take a look whether this is possible. (Your I-D does this already for OAuth 1 and 2)

UPDATE:

What I mean is that the semantics of link relations for, for example, the authorization resource are the same for any OAuth-ish protocol. Ther eis no need to provide different link relation types for OAuth 1.0a and 2.

For a client (no matter whether 1.0a or 2 ... or maybe OZ[1]) it will be sufficient to look for an 'authorization' resource. The differentiation of the particular protocols should is a runtime issue. There is no need to duplicate the semantics for each new OAutish protocol that comes around.

To illustrate: likewise you would not need new 'service' or 'edit' link relations for each new AtomPub version that comes around. Client and server will figure tat out at runtime.

Such decoupling greatly improves the maintainability and evolvability of specifications[2].

Hence, I suggest to remove the differentiation between 1.0a and 2 where possible and to specifiy the link relations in a more genral sense. For example:

"The 'authorize' Link Relation Type

Suggested rewording:

"This link relation type indicates a resource that represents an authorization entry point to be used
  for user authentication/authorization to grant access to a protected
  resource.""

That way Link: </auth>;rel=authorize will work for all OAuths, present and future ones. The same goes for all the other link relation types.

Clearer now?

Jan


[1] http://github.com/hueniverse/oz
[2] http://www.w3.org/TR/webarch/#orthogonal-specs