Re: [WG-UMA] Text affecting #163 (public info), #164 (error code returned) -- and even #168 (ticket in JSON)?

Yes, that’s the kind of “parallel” optionality I was thinking of. James mentioned an interesting observation on the call. Note that the spec says “It SHOULD respond with the HTTP 403 (Forbidden) status code, providing…” It doesn’t actually say MUST. Our intent with the SHOULD was to reinforce that 403 was preferred, but not to mandate it because all server responses are actually optional per the Sec 3 intro. If it would thus not technically be stretching, we could perhaps craft something closer to our eventual intention, like this: “In its response, the resource server SHOULD provide the authorization server's URI in an "as_uri" property in a WWW-Authenticate header with the authentication scheme “UMA", and the just-received permission ticket in a “ticket" property. If the resource server does not provide this header, the client has no way to know how to continue seeking access to the protected resource to which it just attempted access. For an HTTP 403 response, the RS MAY also respond with the ticket in the body in a JSON-encoded "ticket" property." A ticket property wasn’t mandated before (didn’t exist) and it’s not strictly mandated now (SHOULD), but it’s recommended, and we expect everybody to do it routinely if they’re responding at all. A ticket body wasn’t mandated before (SHOULD) and it’s not now (MAY), but its use will fall away because it’s redundant and inconvenient for non-JSON APIs. If it’s awkward to mention the body part at all, could we even drop it, since it was never strictly required? If we went this route, should we explain what the heck is up — in the spec and/or in the UIG? If it would be too ethically close to a breaking change, but we’re certain of our eventual intention, we could signal our later intent with a MAY phrase like yours instead of the “undefined but go look at the UIG” phrase that’s in there now. Yours in pretzel logic, Eve

On 20 Aug 2015, at 1:18 PM, Justin Richer wrote:

One option is something like:

The RS MUST respond with a WWW-Authenticate header in the UMA scheme, including the as_uri property. For an HTTP 403 response, the RS MUST respond with a JSON document with the ticket in the body. The RS MAY return the ticket in the header as the ticket property for a 403 response in addition to the body. For other responses, the RS MUST respond with the ticket in the header as the ticket property. The client then takes the ticket and sends it to the AS, blah blah...

This is a non-breaking change per the spec, but it specifies new behavior where before it was “undefined”. This fits a classical definition of a minor release: adding new functionality that might break some assumptions but not something specified. One could wedge it into a patch release but that seems a little bit of a stretch, to me.

Then in 2.0, we take away the special specification around 403 and make *everything* return the ticket in the header no matter the code. This closes a bunch of stuff all at once and wouldn’t break compliant server and client implementations, which could phase out support for the JSON body and always look in the header.

— Justin

...

On Aug 20, 2015, at 1:55 PM, Eve Maler mailto:eve@xmlgrrl.com> wrote:

In discussing how to implement our decision on issue #163 last week for how to add the WWW-Authenticate header to success responses in addition to error responses when the client presents no access token, we realized that:

1. The API correctly might want to return 300-class responses in addition to 200-class responses (that is, it’s entirely up to the API what “success” means for it).

2. As long as the response contains the WWW-Authenticate: UMA header and the relevant AS location and ticket info, we don’t much care what HTTP status code is used, because this is enough to tell the client what to do next.

3. If we broaden the text to allow any status code at all instead of 403, it’s sort of non-breaking (barring the “other responses by 403 are undefined” wording that’s in there now) — noting that this also allows a 401. (Hello, issue #164. :-) This resulted in the following wording:

https://github.com/KantaraInitiative/wg-uma/commit/b784e6c33e45c02b267ad6b21... https://github.com/KantaraInitiative/wg-uma/commit/b784e6c33e45c02b267ad6b21...

“It SHOULD respond to the client with a response that MUST include the "WWW-Authenticate" response header field with the authentication scheme "UMA", providing the authorization server's URI in an "as_uri" property in the header, along with the just-received permission ticket in the body in a JSON-encoded “ticket” property.”

- What do we think of this wording?

- If we like this wording or something similar...

4. Once we got to this point, I felt increasingly uncomfortable with leaving issue #168 to a later major version because of point no. 1. It’s crystal-clear that the API (which could just be a web app) might want to return a web page or a graphic or whatever. How do you return a JPEG along with a JSON body with a ticket in it? This issue seems not just “critical”, but “blocking”. The downside seems large, the upside seems large, and it seems like a low-impact change to the spec and implementations. The discussion in that issue seemed to be going in the direction of returning the ticket as part of the WWW-Authenticate header.

- Are we willing to choose a “breaking” solution along these lines in the patch release?

- If we’re not, would we be interested in a “non-breaking” solution along the following lines? “SHOULD provide the ticket in ticket=“ticket-value” in the header, or in the body in a JSON-encoded "ticket” property but the latter is deprecated”.

Eve Maler | cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl | Calendar: xmlgrrl@gmail.com

_______________________________________________ WG-UMA mailing list WG-UMA@kantarainitiative.org http://kantarainitiative.org/mailman/listinfo/wg-uma

Eve Maler | cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl | Calendar: xmlgrrl@gmail.com