[WG-UMA] UMA core: be more explicit about PAT

Eve Maler eve at xmlgrrl.com
Mon Oct 13 09:52:04 CDT 2014


I think I can square all these circles, but it's going to get philosophical. :-) Gil, I know I forwarded you the writeup[1] I did in response to Hal's XACML/OAuth paper, and you also saw the "authz concepts" slide deck[2]; I'll be leveraging some of that here but very briefly.

On 13 Oct 2014, at 4:44 AM, Gil Kirkpatrick <gil.kirkpatrick at viewds.com> wrote:

> This area of scopes really confuses me. I'm an OAuth noob so it may just be my ignorance, but it seems to me that OAuth leaves the semantics of scopes completely undefined. Outside of an equality relationship and a completely undefined ordering relationship (6749 refers to the notion of a "narrower" scope in section 1.5), it appears to me that scopes can mean anything, and the semantics are left to the implementation of the resource server. Am I correct on that?

OAuth purposely doesn't standardize scopes, but clearly uses them to mean something like a "named bucket of API calls" carved off the entire set of possible API calls at an API.

UMA defines "protection" and "authorization" scopes, same as OpenID Connect defines "email" etc. scopes and Salesforce.com defines scopes, because it actually defines APIs that need protection. Real APIs need real scope semantics. The OAuth security mechanism needs abstraction.

> 
> UMA core takes a slightly different view of scopes: "A scope is a bounded extent of access that is possible to perform on a resource set." So a scope refers to an "extent of access" that can be "bounded" and "performed on a resource set". This is all still pretty fuzzy to me, but it sounds like a scope in this doc is meant to be more like an operation or a set of operations that can be applied to a resource set. And the example in 2.2 seems to bear that out... it presents scopes of "...view" and "...all". Coming from the XACML world, this makes a lot more sense to me... resources are entities that are completely distinct from the operations ("scopes") that can be requested on them.  Resource-reg reenforces the notion of scopes as operations in section 8.

While OAuth keeps the "resource set" (the API, or a set of endpoints) implicit, UMA makes this explicit and requires that it be named, so that different scopes can be matched to different resource sets explicitly. If you want to think of a resource set as a set of endpoints, you can, but this is a tidy fiction, because there's no requirement that the RS expose the exact endpoints to the AS. Also, there's no requirement that it be a true API vs., say, a bunch of JPEGs or HTML files or whatever.

Also, the two-tier resource set/scope convention can map to object/verb, but in fact you could split the semantics any way you like.


> 
> Looking at the collection of Salesforce scopes Eve provided leads me to think they are more like resources than operations. So I fear that Marcello's goal of grandfathering in existing OAuth implementation is going to fall down when the implementer has to support resource-reg.

If SFDC wanted to UMA-protect its API, it could split things all kinds of ways. But when it comes to UMA's defined APIs that are in fact OAuth-protected, it's as simple as: "protection" scope for the RS is just an OAuth scope, and "authorization" scope for the client is just another OAuth scope. Resource registration is for UMA-protected resources.

> 
> Because we're hoping to achieve interoperability between independently developed implementations (and not just making it easy for someone to write a customer client for a specific resource service), I think we have to very specific about what scopes mean, and we should reinforce the notion that in UMA, scopes correspond to operations, and are independent of resources.

We could take a harder line about the "verb" semantics of UMA scopes, but it's very hard to do in practice, because...

> 
> FWIW, resource-reg has this text: "The resource server is free to use its own methods of describing resource sets. A resource set description is a JSON document with the following properties..." On the one hand the implementation is free to describe resources sets any way it wants, and on the other, it has to describe them with a specific JSON document? I think I understand what is intended, but the wording is confusing. Maybe this would be better: "A resource server is free to define and implement resource sets in any way it sees fit. The resource server registers resource sets with the AS using a JSON document that meets the following requirements."

...we give a syntactic data-structure syntax for describing the semantic, and all such things could be "abused". When I was doing SGML, we called this "Tag Abuse Syndrome".[3] The only known mitigation is to try and model semantics along lines that are friendliest to what your audience actually wants to do anyway. :-) But in any case, the "protection" and "authorization" scopes are in the realm of OAuth and aren't subject to this foible...

I hope this helps, at least a little!

	Eve

[1] http://kantarainitiative.org/pipermail/wg-uma/2013-July/002391.html (unfortunately missing internal links - let me know if you want me to forward a pretty-printed version with links)
[2] http://kantarainitiative.org/confluence/download/attachments/17760302/Authz%20concepts.pdf?api=v2
[3] http://www.xmlgrrl.com/publications/DSDTD/ch06.html

> 
> -gil
> 
> 
> 
> ------ Original Message ------
> From: "Eve Maler" <eve at xmlgrrl.com>
> To: "Zhanna Tsitkov" <tsitkova at mit.edu>
> Cc: "wg-uma at kantarainitiative.org UMA" <wg-uma at kantarainitiative.org>; "Zhanna Tsitkov" <eztsi at yahoo.com>
> Sent: 9/10/2014 11:44:44 AM
> Subject: Re: [WG-UMA] UMA core: be more explicit about PAT
> 
>> Hi Zhanna,
>> 
>> Indeed the PAT is just a plain vanilla OAuth token with a particular scope. Section 1.3.1 says: "The authorization server MUST present a TLS- and OAuth-protected, HTTP-based protection API for use by resource servers." and "An entity seeking protection API access MUST have the scope "http://docs.kantarainitiative.org/uma/scopes/prot.json". (This URI resolves to a JSON-encoded scope description, as defined in [OAuth-resource-reg]. The description is non-normative for UMA purposes.) An access token with at least this scope is called a protection API token (PAT) and an entity with this scope is definitionally a resource server." The comment about binding is just meant to be more an observation than anything, since OAuth tokens do this kind of binding anyway. We stayed away from showing normal OAuth flows since they are literally the "same as usual".
>> 
>> What do you suggest for making this clearer?
>> 
>> This actually relates to Marcelo's suggestion about backing off of the "MUST" around the scope statement I quote above, since -- if I understand correctly -- he's suggesting that someone with an existing OAuth-protected API could subsume UMA protection into an existing scope simply by declaring it to be the case in their developer documentation and any machine-readable versions thereof. (And it would apply with exactly the same logic to AATs too.)
>> 
>> What do people think of this idea? Since this part of UMA is strictly in OAuth-land, I'm inclined to agree that MUSTs arguably go a bit far. Scope semantics in OAuth frequently live outside of machines. E.g., I recently charted the interrelationships of the OAuth scopes for the Salesforce.com APIs for a presentation, and there's a *lot* of complex ones, to wit (I may have gotten some details wrong...):
>> 
>> full
>> - id
>> - api
>>  - id
>>  - chatter_api
>>    - id
>> - openid
>>  - id
>> - web
>>  - id
>>  - visualforce
>>    - id
>> - visualforce
>> refresh_token
>> custom_permissions
>> 
>> If someone wants to just "declare" that their scope includes "UMA protection" or "UMA authorization", why not?
>> 
>> (To be devil's advocate, OpenID Connect defines an API and also defines standard scopes that go with it: profile, email, address, phone.)
>> 
>> Eve
>> 
>> On 8 Oct 2014, at 1:19 PM, Zhanna Tsitkov <tsitkova at MIT.EDU> wrote:
>> 
>>> Hi,
>>> I suggest to clarify a little bit more the text related to PAT (Section 1,3,1.) to the benefit of UMA implementors. The following would be useful explicitly stated bits of information:
>>> 
>>> 1. Is PAT a plain OAuth access token or not?
>>> 2. "A PAT binds a resource owner, a resource server the owner uses for resource management, and an authorization server the owner uses for protection of resources at this resource server." Should the PAT token (explicitly) carry additional fields for the keeping track of the 3-way binding (relationship among the RO, the RS and the AS).
>>> 3. An example of PAT issuance would be useful too.
>>> 
>>> Thanks,
>>> Zhanna
>> 
>> Eve Maler http://www.xmlgrrl.com/blog
>> +1 425 345 6756 http://www.twitter.com/xmlgrrl
>> 
>> _______________________________________________
>> WG-UMA mailing list
>> WG-UMA at kantarainitiative.org
>> http://kantarainitiative.org/mailman/listinfo/wg-uma
> 


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



More information about the WG-UMA mailing list