[WG-UMA] A newcomer's affairs with UMA, the specs.
eve at xmlgrrl.com
Fri Jul 15 17:30:01 EDT 2011
Jacek-- You are the perfect audience to test the spec for comprehensibility etc., so getting your comments is GREAT. Probably most of the $5 words and long sentences in the spec are my fault, though I see you're a kindred spirit, since you use "antepenultimate" non-ironically!
A few thoughts, then I'm hoping Thomas will weigh in with further thoughts. See below.
On 15 Jul 2011, at 6:21 AM, Jacek Szpot wrote:
> 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.
Link to 3.2
The repetition is because the reader may enter this section without having read through the sibling subsections to get to it. This makes the subsections more "modular". But maybe we can factor out the similar text to an upper section.
Semicolons are sometimes used instead of commas when the items are long and window (and might themselves contain commas). But we could use commas here. Indeed the paragraph was rushed!
Perhaps we should add an Example subsection at the beginning, similar to the resource set registration section?
> 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.
Link to 3.5
Perhaps we can factor this out. What section should that go in? A new top-level section after the Intro?
> x02 [ 2.4.1, paragraph 8 ] - “Web accessible”; when describing scope definitions. Accessible by? Everyone? Any access prerequisites?
Link to 2.4.1
This means "publicly accessible", but maybe there's no reason to totally disallow protection mechanisms over scope information. However, I'd expect "horizontal" or Web-scale AMs to need public access so that the whole thing will work dynamically. Thoughts?
> 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 something.
Link to 2.4.1
In OAuth-land, scopes are simple strings, often URIs but not always, and their handling and expression are completely understandized. There were several big fights about this. In inventing "scope metadata/documentation" that's machine-readable, we're taking a big leap. Some folks may push back on us because the resource set ID (the "primary axis" of the data structure) doesn't exist in OAuth, but we have broader use cases than OAuth does.
We have invented something we think is simple, and amenable to standardization for those who create standard APIs, but also flexible enough to handle totally proprietary scopes. I think it warrants this much attention for a certain OAuth-friendly audience, at least.
> 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.
Link to 2.4.4
We discussed the possibility of the AM's understanding somehow getting out of sync with the host's, but I don't know how realistic that is.
> x05 [ 2.4.1, antepenultimate paragraph ] - “Photoz is responsible for responding __correctly__” (emphasis mine) - what does correctly mean in this case?
Link to 2.4.1
This is a subjective wording for what should be an objective calculation. The host will observe the requester's attempt at access, classify it as requiring one of a finite set of permissions, get the token status, then do a comparison to see if one or more of the required permissions are on the list. However, since the host does quite a lot of this "internally", unless we add new feature to keep it honest (e.g. make it tell the AM what types of permissions would make the grade, so this can be recorded by a party that the user has a separate trust relationship with), conformance with the objective version can't be stated in a testable fashion in the web protocol.
However, we should add "non-repudiation" as an issue to the list, since we've discussed it in the past and since we could nicely optimize this message interaction anyway by doing so.
> 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 language.
Link to 2.4.3
Definitely my fault! Christian S. got me to stop saying "wield" instead of "present" when it comes to tokens, but you still need to beat all those other big words out of me...
> 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?
Link to 2.4.4
The relevant MUST is in the 2.4 introduction: "Once the host has received a host access token, for any of the user's sets of resources that are to be protected by this AM, it MUST register these resource sets at the AM's registration endpoint." I didn't want to repeat instances of MUSTs in case it confused anybody, but perhaps we need a system of cross-references here. (There may even be another MUST or two that means the same thing elsewhere.)
> 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?
Link to 3.5
This was a function of my not knowing the right language, but wanting to say something before we hit Rev 00. :-) My notes from the convo with Paul B. collected the rest of the detail we really need.
> 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.
Link to 3.1
Very true. We should make these normative.
> 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.
I discussed this a bit above. It's possible for us to make this more objective, but to be meaningful as protocol language, we'll have to extend and tighten the host-AM interactions a bit.
Whatever we conclude, we can capture the concepts in the new intro section proposed above too.
> 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.
The new intro section can hopefully help. E.g., the host access token is plain OAuth, but the requester access token is pretty different, so we should call that out.
> 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)?
Let's include that in the discussion that leads to the new intro section above. We do have some ideas for guidelines and best practices that are worth putting together. We'll just want to be careful not to "infect" the spec (vs. some auxiliary doc) with too much in the way of implementation detail.
> 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.
Love it. :-) I think we can definitely improve on demystifying them, at least partially, pretty quickly.
> 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.
Easily done -- ran out of time!
> 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.
Seriously, this review was brilliant -- thank you for doing it! Please do more!
Eve Maler http://www.xmlgrrl.com/blog
+1 425 345 6756 http://www.twitter.com/xmlgrrl
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the WG-UMA