Re: [OAUTH-WG] OAuth 2.0 Resource Registration draft -- FW: New Version Notification for draft-hardjono-oauth-resource-reg-00.txt

[Eve Maler <[e-mail]>]

On 28 Dec 2012, at 5:58 AM, "Anganes, Amanda L" <[e-mail]> wrote:

> Hi Eve and Thomas,
> 
> On 12/27/12 8:11 PM, "Eve Maler" <[e-mail]> wrote:
> 
>> Amanda, thanks for the lightning-fast comments back. A couple of additional notes on top of Thomas's response:
>> 
>> The "scope type" language is indeed new this time -- of course this whole modular spec is newly broken out, but the previous text from UMA's rev 05 still said "scope". (There's a new member in the JSON description of a resource set that is called "type", but this is actually the resource set's type: different thing.) Maybe this should just be changed back to "scope" and "scope description", as we really do mean the same construct as in plain OAuth, although here it's enhanced with a machine-readable description, and it's mappable to resource sets that have been explicitly identified. One thing we've been learning lately is that terminology impedance mismatches are not worth the cost; this one is a recent back-sliding. :)
> 
> I think it would make much more sense to stick with "scope" and "scope description". I assumed that you were trying to avoid collisions with OAuth by changing it, but it sounds like that is not the case. 
> 
> There might be a better way to denote that these are enhanced scopes, but "type" isn't quite right for that as it does imply a class or kind of thing (to which many particular things might belong), rather than a special or enhanced particular thing. 

Our experience so far is that enhanced versions of things should just use the name for the thing. Hence, in the UMA core spec we've finally started using OAuth terminology directly rather than sticking with our original names (which dated from OAuth 1.0). I for one find it a LOT clearer, now that OAuth's architecture has become more widely understood.

> 
>> 
>> Eve: Regarding the sentence "Without a specific resource set identifier path component, the URI applies to the set of resource set descriptions already registered." in Section 2.3: I suspect this can just be deleted entirely. It's redundant with the "List resource set registrations" bullet item just below, which literally shows the {rsid} component of the path being absent. This is the only supported method in this API that has no {rsid} path component.
>> Thomas: Resource set registration API:  If Alice (the RO) has already previously registered some resources at the AS, then Alice will already have a PAT token (and the AS knows about Alice, her PAT, her resource sets and scopes). If Alice comes back again with the same PAT and forgets to specificy the path component, we assume the AS is smart enough to figure out which sets Alice is refering to. Does this help? (or does it still read weirdly).
>> 
> These two explanations are very different. If Thomas's assessment is correct, I would move that explanatory text up to the end of the paragraph starting with "The authorization server MUST present an API…" and explain that the PAT can also be used to figure out the {rsid} for any requests where it is left off (implying that the {rsid} component MAY be left off of any of the following API calls). Otherwise if Eve is correct and that additional caveat is NOT meant to be there, I would suggest removing the phrase entirely as it does seem to imply that {rsid} may be left off. 

I think Thomas might been thinking about a different issue we have faced in the past regarding URIs, which is the question of how protected-resource endpoints are disinguishable per resource owner. I won't deep-dive on that issue here to save confusion, but suffice to say I think we can remove the offending sentence.

> 
>> 
>> Regarding {rsreguri}: I do see it defined, in this same Section 2.3. Basically this notation is simply a device to allow for referring to a "resource set registration endpoint" (defined in the Terminology section) in the URIs here that serve as method templates. Is there a better way to do this?
> 
> Yes, it is defined but not actually used to describe the API paths. The definition is fine but if it is there it should be used; for example the "Create resource set description" path should change from "PUT /resource_set/{rsid}" to "PUT {rsreguri}/resource_set/{rid}".

It's used just above the explanation: 

The authorization server MUST present an API for registering resource set descriptions at a set of URIs with the structure "{rsreguri}/resource_set/{rsid}", where the PAT provides sufficient context to distinguish between identical resource set identifiers assigned by different hosts.

Calls to this API are made to that endpoint, but don't include it in the in-band HTTP request syntax. Does this make sense, or am I crazy?...

> 
> --Amanda

Thanks again,

	Eve


Eve Maler                                  http://www.xmlgrrl.com/blog
[phone]                         http://www.twitter.com/xmlgrrl