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

From: Thomas Hardjono <[email-masked]>
Date: Thu, 27 Dec 2012 19:24:35 +0000

Folks,

The OAuth 2.0 Resource Set Registration draft is essentially a generic first phase of the User Managed Access (UMA) profile of OAuth2.0.  This allows the RO to "register" (make known) to the AS the resources he/she wishes to share.

Looking forward to comments/feedback.

/thomas/

__________________________________________

-----Original Message-----
From: [email-masked] [mailto:[email-masked]]
Sent: Thursday, December 27, 2012 2:07 PM
To: Thomas Hardjono
Subject: New Version Notification for draft-hardjono-oauth-resource-reg-00.txt

A new version of I-D, draft-hardjono-oauth-resource-reg-00.txt
has been successfully submitted by Thomas Hardjono and posted to the IETF repository.

Filename:        draft-hardjono-oauth-resource-reg
Revision:        00
Title:           OAuth 2.0 Resource Set Registration
Creation date:   2012-12-27
WG ID:           Individual Submission
Number of pages: 19
URL:             http://www.ietf.org/internet-drafts/draft-hardjono-oauth-resource-reg-00.txt
Status:          http://datatracker.ietf.org/doc/draft-hardjono-oauth-resource-reg
Htmlized:        http://tools.ietf.org/html/draft-hardjono-oauth-resource-reg-00

Abstract:
   This specification defines a resource set registration mechanism
   between an OAuth 2.0 authorization server and resource server.  The
   resource server registers information about the semantics and
   discovery properties of its resources with the authorization server.

The IETF Secretariat

---

From: "Anganes, Amanda L" <[email-masked]>
Date: Thu, 27 Dec 2012 21:57:21 +0000

Hi Thomas,

Here is some initial feedback.

Introduction paragraph 2:

Remove duplicate "with": "the OpenID Provider (OP) component is a
specialized version of an OAuth authorization server that brokers
availability of user attributes by dealing *with with* an ecosystem of
attribute providers (APs)."

Section 1.2 Terminology:

This is more of a comment for the UMA WG in general: "scope type" is an
unfortunate term (which appears in the UMA core draft [1] as well - if
memory serves the term used to be just "scope" but I couldn't find a diff
reference for when that changed). Including "type" in the term makes it
sound like it refers to a class or kind of scope, which doesn't seem to be
what you mean. I understand that "scope" cannot be used since it is
already reserved by OAuth, but perhaps a better synonym could be found and
used instead? 

2. Resource set registration

2nd sentence reads oddly. Change from "For any of the resource owner's
sets of resources this authorization server needs to be aware of, the
resource server MUST register these resource setsŠ" to "If this
authorization server needs to be aware of any of the resource sets, the
resource server MUST register those resource setsŠ"

2.2 Resource set descriptions

"scopes" and to refer to sets of "scope type"s and "type" to refer to the
class/kind of resource set this is add to the argument above that "scope
type" is a misleading term.

2.3 Resource set registration API

I don't understand what this sentence means: "Without a specific resource
set identifier path component, the URI applies to the set of resource set
descriptions already registered." Can you clarify?

The {rsreguri} URI component is defined but never used. It looks like all
of the "/resource_set" URIs should be prefaced with this component
throughout the following sections?

[1] https://datatracker.ietf.org/doc/draft-hardjono-oauth-umacore/

-- 
Amanda Anganes
Info Sys Engineer, G061
The MITRE Corporation
781-271-3103
[email-masked]

On 12/27/12 2:24 PM, "Thomas Hardjono" <[email-masked]> wrote:

>Folks,
>
>The OAuth 2.0 Resource Set Registration draft is essentially a generic
>first phase of the User Managed Access (UMA) profile of OAuth2.0.  This
>allows the RO to "register" (make known) to the AS the resources he/she
>wishes to share.
>
>URL:             
>http://www.ietf.org/internet-drafts/draft-hardjono-oauth-resource-reg-00.t
>xt
>Status:          
>http://datatracker.ietf.org/doc/draft-hardjono-oauth-resource-reg
>Htmlized:        
>http://tools.ietf.org/html/draft-hardjono-oauth-resource-reg-00
>
>
>Abstract:
>_______________________________________________
>OAuth mailing list
>[email-masked]
>https://www.ietf.org/mailman/listinfo/oauth

---

From: Thomas Hardjono <[email-masked]>
Date: Fri, 28 Dec 2012 00:37:29 +0000

Thanks Amanda,

- Scope and types:  We went back and forth with regards to "scope type" and finally just used "type" with the assumption that the reader would know what we mean by it (ie. context dependent).  However, we're very open to going back to the previous language.

- Resource set registration: yes that sentence does read weirdly, will fix :-)

- 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).

- The {rsreguri} URI component is defined but never used: hmm yes you are correct. Will fix this.

Thank you again.

cheers,

/thomas/

> From: Anganes, Amanda L [mailto:[email-masked]]
> Sent: Thursday, December 27, 2012 4:57 PM
> To: Thomas Hardjono; [email-masked]
> Subject: Re: [OAUTH-WG] OAuth 2.0 Resource Registration draft -- FW:
> New Version Notification for draft-hardjono-oauth-resource-reg-00.txt
> 
> Hi Thomas,
> 
> memory serves the term used to be just "scope" but I couldn't find a
> diff reference for when that changed). Including "type" in the term
> makes it sound like it refers to a class or kind of scope, which
> doesn't seem to be what you mean. I understand that "scope" cannot be
> used since it is already reserved by OAuth, but perhaps a better
> synonym could be found and used instead?
> 
> "scopes" and to refer to sets of "scope type"s and "type" to refer to
> the class/kind of resource set this is add to the argument above that
> "scope type" is a misleading term.
> 
> I don't understand what this sentence means: "Without a specific
> resource set identifier path component, the URI applies to the set of
> resource set descriptions already registered." Can you clarify?
> 
> The {rsreguri} URI component is defined but never used. It looks like
> all of the "/resource_set" URIs should be prefaced with this component
> >has been successfully submitted by Thomas Hardjono and posted to the
> IETF
> >repository.
> >

---

From: Eve Maler <[email-masked]>
Date: Thu, 27 Dec 2012 17:11:26 -0800

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. :)

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.

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?

	Eve

>>>  discovery properties of its resources with the authorization

Eve Maler                                  http://www.xmlgrrl.com/blog
+1 425 345 6756                         http://www.twitter.com/xmlgrrl

---

From: "Anganes, Amanda L" <[email-masked]>
Date: Fri, 28 Dec 2012 13:58:41 +0000

Hi Eve and Thomas,

On 12/27/12 8:11 PM, "Eve Maler" <[email-masked]<mailto:[email-masked]>> wrote:

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.

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.

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}".

--Amanda

Eve

On 27 Dec 2012, at 4:37 PM, Thomas Hardjono <[email-masked]<mailto:[email-masked]>> wrote:

Thanks Amanda,

-----Original Message-----
From: Anganes, Amanda L [mailto:[email-masked]]
Sent: Thursday, December 27, 2012 4:57 PM
To: Thomas Hardjono; [email-masked]<mailto:[email-masked]>
Subject: Re: [OAUTH-WG] OAuth 2.0 Resource Registration draft -- FW:
[email-masked]<mailto:[email-masked]>
On 12/27/12 2:24 PM, "Thomas Hardjono" <[email-masked]<mailto:[email-masked]>> wrote:
first phase of the User Managed Access (UMA) profile of OAuth2.0.
This
allows the RO to "register" (make known) to the AS the resources
he/she
-----Original Message-----
From: [email-masked]<mailto:[email-masked]> [mailto:[email-masked]]
Sent: Thursday, December 27, 2012 2:07 PM
To: Thomas Hardjono
Subject: New Version Notification for
draft-hardjono-oauth-resource-reg-00.txt
A new version of I-D, draft-hardjono-oauth-resource-reg-00.txt
has been successfully submitted by Thomas Hardjono and posted to the
IETF
repository.
Filename:        draft-hardjono-oauth-resource-reg
Revision:        00
Title:           OAuth 2.0 Resource Set Registration
Creation date:   2012-12-27
WG ID:           Individual Submission
Number of pages: 19
URL:
http://www.ietf.org/internet-drafts/draft-hardjono-oauth-resource-reg-
00.t
xt
Status:
http://datatracker.ietf.org/doc/draft-hardjono-oauth-resource-reg
Htmlized:
http://tools.ietf.org/html/draft-hardjono-oauth-resource-reg-00
Abstract:
  This specification defines a resource set registration mechanism
  between an OAuth 2.0 authorization server and resource server.  The
  resource server registers information about the semantics and
  discovery properties of its resources with the authorization
server.
The IETF Secretariat
_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth
_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth

---

From: Eve Maler <[email-masked]>
Date: Fri, 28 Dec 2012 11:31:13 -0800

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

> Hi Eve and Thomas,
> 
> On 12/27/12 8:11 PM, "Eve Maler" <[email-masked]> wrote:
> 

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.

> 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…

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.

> 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…

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