[WG-UMA] A newcomer's affairs with UMA, the specs.

Jacek Szpot maligree at gmail.com
Fri Jul 15 09:21:55 EDT 2011

Hello, list.

Since I've spent a considerable amount of time reading through the
specification (as preparation for the Python host/requester implementation
and framew.. library, actually), we decided it would be best if I could
gather up all the notes I scribbled all over my dead-tree form of the
specification and present them here, so everyone can get a refreshing idea
of what the spec looks like to a newbie.

These comments mainly pertain to the structure, wording and, well, topic
coverage. Some vagueness may, of course, stem from the language and wording
used, sentence structure, perhaps even my initial misconceptions about the
internal workings of the protocol. Some misunderstandings may arise from the
lack of knowledge of UMA history. While researching some topics (e.g.
tickets) I actually had to reach into some old telecon minutes -- but
obviously, I couldn't get through it all. Bear this in mind, treat this as a
rookie-developer-meets-UMA story. A developer with understanding of how UMA
is supposed to work and its goals. Confident with OAuth 2.0.

I regret I’m not able to contribute anything more technical/design oriented
at this time. But let’s give my mind some time - for UMA to fully sink in.
Then we’ll see.

So lets go:

x00 [ 3.2, paragraphs 3-5 ] - I felt there’s just too much information
packed into one paragraph. After two paragraphs that simply restate what has
been told a few pages earlier, I was presented with a mysterious block of
text formatted mainly through the use of semicolons. These 5 lines and three
words mention two issues that ought to be presented clearly - concerning
token uniqueness and the binding of a token to permissions. Understanding
how many tokens are actually in play during the whole UMA flow is
fundamental. This, IMHO, should be expanded and provided with examples.
Right now, paragraph 3 has a very careless and rushed feeling to it.

x01 [ 3.5, paragraph 2 ] - for the third time, the construction of the
host-meta URI is explained. How a URI is glued together is, I think, a
pretty simple thing and I’d prefer to have it explained thoroughly in one
place and then referenced (e.g. “host-meta URI is constructed as described
in X.Y”) instead of having it repeated all over the spec.

x02 [ 2.4.1, paragraph 8 ] - “Web accessible”; when describing scope
definitions. Accessible by? Everyone? Any access prerequisites?

x03 [ 2.4.1-2 ] - the two scope examples that appear here - this is great,
but after reading on and stumbling upon yet another mention of scopes (this
time in their dedicated section, 2.4.2), I was a bit puzzled as to why such
a trivial structure would get so much coverage. This caused me to go back
those few pages and re-read a few paragraphs thinking I must have missed

x04 [ 2.4.4(.2) ] - in what real-world case would the GET method be used (in
other words, who wants to read the resource set description?). I don’t
recall reading any mention of how access to this endpoint is restricted.

x05 [ 2.4.1, antepenultimate paragraph ] - “Photoz is responsible for
responding __correctly__” (emphasis mine) - what does correctly mean in this

x06 [ 2.4.3 ] - in _id description: “insofar”, “by virtue”. A very
contrived, five-line-long sentence. I had to think twice, I strongly
recommend simplifying this - the reader may not be an ace when it comes to

x07 [ 2.4.4, paragraph 3 ] - “individual resource set descriptions are
managed at URIs with this structure”. I have trouble judging - is this a
requirement? MUST, SHOULD?

x08 [ page 20, line 1 ] - “as indicated in the HTTP header” - we’re on the
subject of caching and an HTTP header is mentioned. So, sure, it’s
resolvable. But explicit is better than implicit. Hence: which header?

x09 [ 3.1.1, 3.1.5 ] - sections 3.1.2-4 explicitly state what HTTP code MUST
or SHOULD be returned - 3.1.1 & 3.1.5 do not - they illustrate it in the
examples provided, but the paragraphs lack RFC2119 style wording.

Other comments, questions, not necessarily bound to any particular section
of the specification. Some out of curiosity:

x0a: Permissions - on many fronts: host “judges” on permissions? Host
registers permissions for the requester? Who is the host, PEP or PDP? I’m
also skeptical about the use of the phrase “in the host’s judgement” itself
- this has a very heuristic feel to it.

x0b: Spec seems to make sure (by repetitively describing specific processes)
I understand basic stuff like URI construction, but mentions token
uniqueness only once, in a really crude paragraph. Tickets are just as
mysterious, but on those in a second.

x0c: What is the lifespan of a token? Is it different for a host access
token, is it different for a requester access token? Is it persistent (e.g.
Facebook-always-access) or does it use a refresh token (Google-style)?

x0d: How many tokens are there, per entity? Per different entities? One for
each requesting party at a requester? Is a requesting party tied to a
specific token when accessing a specific resource at a specific host? Can
there be multiple? What is a token linked to? Resource, user, requester,
requesting party? And so on.

x0e: In overall, tokens appear as an enigmatic driving force.

x0f: Also, tickets appear out of nowhere in a take-this-there-and-don't-ask
way. What are they, what's their purpose? I like to ask.

That should be it, for now, hopefully less literature-oriented and more
workings-related comments will follow in the near future.

I appreciate any comments, answers, links to well-hidden (or not well
exposed, hey) resources, discussions, anything at all.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://kantarainitiative.org/pipermail/wg-uma/attachments/20110715/83d4e5eb/attachment.html 

More information about the WG-UMA mailing list