Text affecting #163 (public info), #164 (error code returned) -- and even #168 (ticket in JSON)?

Eve Maler

20 Aug 2015 20 Aug '15

1:55 p.m.

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... “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

Show replies by date

Justin Richer

20 Aug 20 Aug

4:18 p.m.

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 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...

“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

7:09 p.m.

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

Justin Richer

10:05 p.m.

New subject: Text affecting #163 (public info), #164 (error code returned) -- and even #168 (ticket in JSON)?

Is there a good reason for not making the response header a MUST in this case? "If the resource server knows where to send you (which is assumed from the text that we just added so go read that first), then it MUST tell the client where to go." I don't see a good reason for making it be a SHOULD. If it doesn't respond with the header, then the RS isn't doing UMA. If it is doing UMA, and it doesn't respond with the header, what does that even mean? -- Justin On 8/20/2015 7:09 PM, Eve Maler wrote:

...

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 mailto:jricher@mit.edu> 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...

“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 mailto:xmlgrrl@gmail.com

_______________________________________________ WG-UMA mailing list WG-UMA@kantarainitiative.org mailto: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 mailto:xmlgrrl@gmail.com

Eve Maler

10:12 p.m.

It says SHOULD now because, as noted below, a) 403 isn’t the only option (other responses aren’t precluded even if they’re not preferred) and b) a response isn’t strictly required at all. However, we could theoretically say that, if the RS responds at all, it MUST use the header. I don’t think anyone’s saying it’s a bad idea. Then the only question is whether that’s a breaking change. I think it technically is, only because we didn’t require it with non-403 responses previously. But I’m wondering if this counts as splitting hairs at this point (ymmv). Eve

...

On 20 Aug 2015, at 7:05 PM, Justin Richer wrote:

Is there a good reason for not making the response header a MUST in this case? "If the resource server knows where to send you (which is assumed from the text that we just added so go read that first), then it MUST tell the client where to go."

I don't see a good reason for making it be a SHOULD. If it doesn't respond with the header, then the RS isn't doing UMA. If it is doing UMA, and it doesn't respond with the header, what does that even mean?

-- Justin

On 8/20/2015 7:09 PM, Eve Maler wrote:

...
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 < mailto:jricher@mit.edujricher@mit.edu mailto:jricher@mit.edu> 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: mailto:xmlgrrl@gmail.comxmlgrrl@gmail.com mailto:xmlgrrl@gmail.com

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

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

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

Justin Richer

10:16 p.m.

New subject: Text affecting #163 (public info), #164 (error code returned) -- and even #168 (ticket in JSON)?

I think the best logic is "If ... MUST" here. Basically, tell the RS the conditions under which it needs to respond this way, then tell it exactly how to do it. Right now it's kinda "If ... SHOULD" which doesn't give client developers much that they can count on. My personal read is that it's a minor-level revision for the reasons I said earlier in the thread (add new stuff that doesn't invalidate stuff that was specified before but might break things that weren't specified), but since it's so under-specified in 1.0.0 I can see the argument for it being a patch. -- Justin On 8/20/2015 10:12 PM, Eve Maler wrote:

...

It says SHOULD now because, as noted below, a) 403 isn’t the only option (other responses aren’t precluded even if they’re not preferred) and b) a response isn’t strictly required at all. However, we could theoretically say that, /if/ the RS responds at all, it MUST use the header. I don’t think anyone’s saying it’s a bad idea.

Then the only question is whether that’s a breaking change. I think it /technically/ is, only because we didn’t require it with non-403 responses previously.

But I’m wondering if this counts as splitting hairs at this point (ymmv).

Eve

...
On 20 Aug 2015, at 7:05 PM, Justin Richer mailto:jricher@mit.edu> wrote:

Is there a good reason for not making the response header a MUST in this case? "If the resource server knows where to send you (which is assumed from the text that we just added so go read that first), then it MUST tell the client where to go."

I don't see a good reason for making it be a SHOULD. If it doesn't respond with the header, then the RS isn't doing UMA. If it is doing UMA, and it doesn't respond with the header, what does that even mean?

-- Justin

On 8/20/2015 7:09 PM, Eve Maler wrote:

...
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...

“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 mailto: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

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

Eve Maler

21 Aug 21 Aug

12:17 a.m.

So, if it responds, it MUST provide the header in all cases. I think we can treat that as the incumbent proposal. Let’s hear from anyone who dissents. Still open: What we should do this time around, if anything, with a totally new new ticket=“value” header property option and softening the ticket body requirement (from SHOULD, which was effectively sort of a MUST). Eve

...

On 20 Aug 2015, at 7:16 PM, Justin Richer wrote:

I think the best logic is "If ... MUST" here. Basically, tell the RS the conditions under which it needs to respond this way, then tell it exactly how to do it. Right now it's kinda "If ... SHOULD" which doesn't give client developers much that they can count on.

My personal read is that it's a minor-level revision for the reasons I said earlier in the thread (add new stuff that doesn't invalidate stuff that was specified before but might break things that weren't specified), but since it's so under-specified in 1.0.0 I can see the argument for it being a patch.

-- Justin

On 8/20/2015 10:12 PM, Eve Maler wrote:

...
It says SHOULD now because, as noted below, a) 403 isn’t the only option (other responses aren’t precluded even if they’re not preferred) and b) a response isn’t strictly required at all. However, we could theoretically say that, if the RS responds at all, it MUST use the header. I don’t think anyone’s saying it’s a bad idea.

Then the only question is whether that’s a breaking change. I think it technically is, only because we didn’t require it with non-403 responses previously.

But I’m wondering if this counts as splitting hairs at this point (ymmv).

Eve

...
On 20 Aug 2015, at 7:05 PM, Justin Richer < mailto:jricher@mit.edujricher@mit.edu mailto:jricher@mit.edu> wrote:

Is there a good reason for not making the response header a MUST in this case? "If the resource server knows where to send you (which is assumed from the text that we just added so go read that first), then it MUST tell the client where to go."

I don't see a good reason for making it be a SHOULD. If it doesn't respond with the header, then the RS isn't doing UMA. If it is doing UMA, and it doesn't respond with the header, what does that even mean?

-- Justin

On 8/20/2015 7:09 PM, Eve Maler wrote:

...
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

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

3317

Age (days ago)

3318

Last active (days ago)

List overview

Download

6 comments

2 participants

participants (2)

Eve Maler
Justin Richer