[WG-UMA] Notes from 4 Jan 2011 ad hoc focus call

Eve Maler eve at xmlgrrl.com
Tue Jan 4 12:19:08 EST 2011


Thanks to the diehards who joined our ad hoc call, including new participant Paul Corriveau!  We used this Pirate Pad for our discussion:

http://piratepad.net/uma-rreg

Below is the content of the pad; italics are used for the notes we put on top of the spec content:

==================

http://mrtopf.clprojects.net/uma/draft-uma-resoure-reg.html

Goal for this ad hoc call: Work through the new Example section (reproduced below), and revise/answer questions/fix as required. Attending: Eve, Paul Corriveau, Christian, Susan, Sal, Domenico. Paul is putting together an IdM approach for his employer, and has become interested in implications of digital identity for personhood and privacy.

The following example illustrates the intent and usage of the resource registration protocol.
This example contains some steps that are exclusively in the realm of user experience rather than web protocol, to achieve realistic illustration; these steps are labeled "User experience only". Some other steps are exclusively internal to the operation of the entity being discussed; these are labeled "Internal only".

A user, Alice Adams, has just uploaded a photo of her new puppy to a host, Photoz.com, and wants to ensure that this specific photo is not publicly accessible.
Alice has already introduced this host to her AM, CopMonkey.com, and thus Photoz has already obtained an OAuth client ID and an UMA host access token from CopMonkey. However, Alice has not previously instructed Photoz to use CopMonkey to protect any other photos of hers.

Alice has previously visited CopMonkey to map a default "do not share with anyone" authorization constraint to any resource sets registered by Photoz, until such time as she maps some other less-Draconian constraints to those resources. (User experience only; this may have been done at the time Alice introduced the host to the AM, and/or it could have been a global or host-specific preference setting.) Other kinds of constraints she may eventually map to particular photos or albums might be "Share only with husband at email.com" or "Share only with people in my 'family' group".

Photoz itself has an API that allows for photo viewing and printing. It defines for itself, and for applications using that API, actions applicable to photos that are accessed by authorized third parties (internal only; this is comparable to determining and documenting OAuth scopes).

While visiting Photoz, Alice selects a link or button that instructs the site to "Protect" or "Share" this single photo (user experience only; Photoz could have made this a default or preference setting). Photoz defines for itself a resource set that represents this photo (internal only; Photoz is the only application that knows how to map a particular photo URL to a particular resource set).

Photoz prepares the following two action descriptions, which are probably standard for this site across all of its users. The "name" parameter values are intended to be used by Alice (and similarly by other users of the same site) in mapping authorization constraints to specific resource sets and actions when she visits CopMonkey, such that Alice would see the strings "View" and "Print", likely accompanied by the referenced icons, when she visits there.

{
        "action":
            {
            "name": "View",
            "icon_uri": "http://www.example.com/icons/reading-glasses"
        }
}

{
        "action":
            {
            "name": "Print",
            "icon_uri": "http://www.example.com/icons/printer"
        }
}

Photoz uses the "create action description" method of CopMonkey's resource registration API, presenting its Alice-specific host access token there, to register and assign identifiers to these action descriptions. The "photoz.com" path component reflects Photz's unique host identifier (its OAuth client ID). Since this is Photoz's first-ever use of this API, the "ABCD001" path component has the effect of assigning a unique identifier to an Alice-specific area underneath Photoz's host registration area. The "view" and "print" path components, respectively, assign unique identifiers to these action descriptions that can then be referenced in resource set descriptions. (Photoz likely could have registered action descriptions at any time upon being introduced to CopMonkey by Alice.) @@should we prepare for actions to be reusable across users by allowing/requiring them to be registered "above" the user-specific level? @@show token being used etc. in the method?

Change "* action description" methods to PUT (etc.) /host/photoz.com/action/view?
Change /host to /hosts, /action to /actions, /resource to /resource_sets?, and /user to /users?

Is it appropriate for Photoz to use an Alice-specific token to put generic actions into its host area? Should it get a "two-legged" access token for its own use when it first gets client credentials at this server anyway? We'd want to modularize the specs in a totally different way if we did the latter, since actions are generic but resource sets are user-specific. Alice wouldn't be able to revoke the two-way relationship, only the three-way relationship represented by what we've been calling the "host access token".

What would be affected in the Scoped Access spec (http://mrtopf.clprojects.net/uma/draft-uma-scoped-access.html) regarding the need for the AM to register scope descriptions in the "user-specific portion" of the host registration area?

Does it make sense to do things the other way around for actions, which is for the host to tell the AM the URL of the description of actions and the AM can pull that information? That way we can totally skip the registration at the AM of global/public information about the host's API, actions, and OAuth "scopes". The rreg API would be halved in size. We'd get a whole bunch of possibilities opening up to us automatically, such as a host using a standardized set of actions by pointing to URLs hosted by someone else (such as a standards org or whatever).

But what if you want to put all your action descriptions into a single document? Then you'd need some system of IDs either internally to the document, or exposed in the URL. If it's exposed in the URL, then the resource set description could contain only URLs; if not exposed, it would need that additional piece of information.

Note: The PUT examples below are now suspect, since we're thinking of completely redoing how actions are handled.

PUT /host/photoz.com/actions/view
Content-Type: application/json
...

{
        "action":
            {
            "id" : "view",
            "name": "View",
            "icon_uri": "http://www.example.com/icons/reading-glasses"
        }
}

PUT /host/com.photoz/user/ABCD001/action/print
Content-Type: application/json
...

{
        "action":
            {
            "name": "Print",
            "icon_uri": "http://www.example.com/icons/printer"
        }
}

When Alice indicates she wants to protect her puppy photo, Photoz prepares the following resource set description, which is specific to Alice and her photo. The "name" parameter value is intended to be used by Alice in mapping authorization constraints to specific resource sets and actions when she visits CopMonkey, such that Alice would see the string "Steve the puppy!", likely accompanied by the referenced icon, when she visits there. The possible actions on this resource set are indicated with references to the identifiers of the action descriptions, as defined just above.

{
        "resource_set":
            {
            "name": "Steve the puppy!",
            "icon_uri": "http://www.example.com/icons/flower",
            "actions": ["view", "print"]
        }
}

Should these references to "view" and "print" IDs be full URLs instead, particularly if the host registered these by simply pointing the AM to the place where the URLs are defined in the first place? The Flickr API, for example (http://www.flickr.com/services/api/), does have web pages for each of the actions it allows for specific resource types, such as http://www.flickr.com/services/api/flickr.galleries.addPhoto.html; perhaps such pages could contain microformats or similar that provide machine-readable information of the sort an UMA authorization manager needs. In fact, the host no longer needs to pre-register anything about actions if it can provide full URLs at the time of registering resource sets.

It's true that Flickr demonstrates a case of having dozens and dozens of possible API calls, which could be confusing to users if they got exposed to all of them in the AM's interface. Presumably these are rolled up into action "bundles", such that related methods are accessible to a client that has gotten permission to use the upper-level action/scope. FlickrAuth seems to use the "perms" (permissions) construct, and the scope is indicated only inside the token (read/write only? the "frob" construct seems to be the temporary token).

Photoz uses the "create resource set description" method of CopMonkey's resource registration API, presenting its Alice-specific host access token there, to register and assign an identifier to the resource set description. The "00001" path component assigns an identifier that does not reveal any of Alice's personal information to an outsider but allows Photoz to know that it is the "Steve the puppy!" photo being referred to. @@show token being used etc. in the method?

PUT /host/com.photoz/user/ABCD001/resource/00001
Content-Type: application/json
...

{
        "resource_set":
            {
            "name": "Steve the puppy!",
            "icon_uri": "http://www.example.com/icons/flower",
            "actions": ["view", "print"]
        }
}

Once these descriptions have been successfully registered, Photoz is responsible for responding to requesters' attempts to access this photo in the manner described in UMA [draft‑uma‑core], achieving protection of the resource by "outsourcing" this task to CopMonkey.

Photoz can choose to redirect Alice to CopMonkey for further authorization constraint mapping, access auditing, and other AM-related tasks (user experience only).
Over time, as Alice uploads other photos and creates and organizes photo albums, and as Photoz makes new action functionality available, Photoz can use additional methods of the resource registration API to ensure that CopMonkey's understanding of Alice's protected resources matches its own.



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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://kantarainitiative.org/pipermail/wg-uma/attachments/20110104/a9686afc/attachment-0001.html 


More information about the WG-UMA mailing list