The whole point of the original issue was that the UMA spec had too little information for RS implementors, and adding more implementation details in the elided example is exactly what I think needs to happen here to resolve this. This is non-normative text, it's not adding more requirements on developers or further limiting UMA in any way. Instead, it's pointing out something that's already there: UMA already /requires /the context be there by implicit assumptions in UMA's design, and we should at the very least say that. Your revision doesn't really say that strongly enough, nor does it give an API developer a hint as to what that context might consist of. It also takes things a step too far, in my opinion, in telling the RS implementor to make their API RO-specific in some way. I think that's the kind of implementation detail (deeply structural, non-syntactic) that does not belong in the spec. In my view, a spec like UMA should assume that the API that it's protecting is fully formed and unchanging. Entertaining the idea that an API would "become able" to accept inputs at all is vastly overestimating the draw of UMA. I *like* UMA, and understand it, and even then if I had an API that didn't match UMA's model I'd more likely not use UMA as opposed to change the API to accommodate UMA. You're absolutely right that this is implementation guidance, but I think we disagree on the appropriate place to put such guidance. I believe we need to be very up front about the assumed mental model in the specification itself. The implementor's guide can go into great detail of that model, and it should, but that in no way means that the spec itself should be silent on the topic. The underlying problem of resource mapping is something that I hope and believe we can fix in 2.0, FWIW. -- Justin On 8/22/2015 9:58 PM, Eve Maler wrote:

Yes, you’re right that this is a piece of context that the client has to present, which means the API has to be able (or become able) to ingest it. (So what is the material cost of choosing a query parameter over providing the context in the request header or body, given that it creates whole new resources?)

As regards implementation detail in the wording, we’ve gone from a little (original, which was inaccurate) to less (my revision) to a heck of a lot (your revision). The protocol spec really doesn’t seem like the place for this, whereas this is exactly what the UIG is for.

Eve

...

On 22 Aug 2015, at 5:45 PM, Justin Richer mailto:jricher@mit.edu> wrote:

If the client provides an additional parameter as a query parameter, then that's a different URI and therefore a different resource. (Remember, the URI is the scheme, host, port, path, parameters -- all of that together, not just the "root" URI.) That provides enough context to make a decision and it's pretty much vanilla UMA there. The client could also send a specialized header or body or something like that -- that's also guiding context. However: all of these need to be built into the API, and APIs that are built like that are fine as per the UMA 1.0 spec.

What you describe as "the small cost of inventing a" necessitates change to the API structure, which is precisely what the original issue was getting at. I really think we ought to tell API developers that if they want to use UMA, then their API needs to behave in a certain way for it to work.

As such, I suggest this wording:

Note: When a client attempts access to a presumptively protected resource without an access token, the resource server needs to ascertain the authorization server and resource set identifier associated with that resource based on the context of the client's request. As this context does not include the access token, which can be used to identify the resource owner and authorization server, this effectively means that the API needs to be structured in such a way that the client's unauthenticated request can uniquely identify the resource set. In practice, this information is likely passed through the URI, headers, or body of the request.

-- Justin

On 8/22/2015 8:31 PM, Eve Maler wrote:

...

When we discussed this on the last call, we gained consensus around wording as follows (emphasis added — hopefully the formatting will make it through):

"Note: When a client attempts access to a presumptively protected resource without an access token, the resource server needs to ascertain the authorization server and resource set identifier associated with that resource *without any context to guide it*. In practice, this likely means that *the URI reference used by the client* needs to be unique per resource set.”

In the previous week’s discussion, I’d had a high-level suggestion for a strategy for providing RO context, which we discussed briefly and concluded didn’t satisfy the goal to let existing APIs stay as they are, but thinking about it again, I’m not sure why that is. Let me run through it in detail.

If the RS has an API that is completely generic per RO, such as a singular endpoint that normally depends entirely on an OAuth token to convey the user context, it would similarly register that singular resource set over and over for each of its many users (each using a different PAT) at an AS, getting a unique resource set ID for each in turn.

It does indeed have to be prepared to associate some attribute with a resource set that can later be matched up with the PAT, and then what remains is for a client to provide that attribute somehow when attempting access with no token. Depending on the nature of the API, the context could be in a query parameter, or something in the request body. So “*without any context to guide it*” in our wording isn’t strictly true.

The approach I mentioned on the call was what appeared in our wireframes as an “authorization code” that the AS would send in an email notification to the RqP, which the client would use in attempting access. That probably wasn’t quite the right way of envisioning the UX, but I think Justin was saying that this requires propagating changed URI structure all the way through. I don’t believe this is needed.

Here are several ways to complete the PAT-to-client-context chain for a resource set given our same example, using the “uri” location property of the resource set description, which is optional and the only part of a resource set description that isn’t entirely abstract:

* If the RS registered the endpoint with some kind of query parameter on it identifying the RO, discoverability would be possible, at (what I believe is) the small cost of inventing a “new URL” just for the purpose of user discoverability but not real URI namespace management. Thinking about Twitter’s API, it would be possible to look up “Alice in Twitter”, “Bob in Twitter”, etc. in the directory and attempt access to their protected Twitter endpoints without inventing new API structure. * If the RS and AS had the opportunity to extend the resource set description JSON structure for extra discoverability features, the RS could add a property for RO identity, enabling an out-of-band means for the requesting side to discover and convey RO identity in, say, a request body. * If the RS registered only the generic endpoint, indeed discoverability wouldn’t be possible without a totally out-of-band RO hint provided somehow.

If this thinking is correct, I think it would be a good idea to revise our wording because we were trying to signal something about the nature of the RS API, but backed off of it and — while making a /potentially/ true statement about the client API call — overstated the case by getting into implementation detail (“*the URI reference used by the client*"). I suggest making the following revision:

"Note: When a client attempts access to a presumptively protected resource without an access token, the resource server needs to ascertain the authorization server and resource set identifier associated with that resource. *If the interface presented by the resource server is not resource owner-specific, the client needs to supply sufficient additional context as part of the resource request. See the [UMA-Impl] for advice on ways to accomplish this.*”

…and then, obviously, adding something like the analysis above to the UIG. (Note that I call it “interface” and not “API” because we do that elsewhere in the spec; we don’t presume it has an API in the classic sense.)

Thoughts?

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

It’s often fine to make simplifying assumptions, and I’m not asking for justification of the original decision to make simplifying assumptions, I’m just asking that those assumptions be spelled out in the spec itself here in the patch release so that it doesn’t surprise anyone. I’m not “holding back” anything on purpose here. Apologies if it seems that way, I’ll try to be more blunt and forthcoming about things in the future. ;) — Justin

On Aug 23, 2015, at 11:40 AM, Eve Maler wrote:

The WG’s work has been helped immensely by your sharing thoughts on future possible avenues of improvement as a hint to what we can do now (the “prefiguring” approach we’ve been talking about, or even, in some cases, actual improvements that positively impact other open issues), so I suggest not holding out on us any further. :-) Keep in mind we’re trying to close the patch version imminently.

In any case, when we made this “simplifying assumption”, fwiw, we were just trying to get the pieces to fit together in a basic design (and frankly, pretty much no one else in the world was taking us seriously…). There were a lot of things that needed figuring out. I’ve located the original discussions in case you’re curious (search for “simplifying assumption”):

[WG-UMA] Notes from 21 Mar 2011 ad hoc call https://groups.google.com/forum/#!searchin/kantara-initiative-uma-wg/21$20ma... [WG-UMA] Notes from 13 Apr 2011 ad hoc meeting https://groups.google.com/forum/#!searchin/kantara-initiative-uma-wg/13$20ap... [WG-UMA] Draft minutes of UMA telecon 2011-04-28 (no call next week!) https://groups.google.com/forum/#!searchin/kantara-initiative-uma-wg/2011-04...

Eve

...

On 23 Aug 2015, at 3:23 AM, Justin Richer mailto:jricher@mit.edu> wrote:

The whole point of the original issue was that the UMA spec had too little information for RS implementors, and adding more implementation details in the elided example is exactly what I think needs to happen here to resolve this. This is non-normative text, it's not adding more requirements on developers or further limiting UMA in any way. Instead, it's pointing out something that's already there: UMA already requires the context be there by implicit assumptions in UMA's design, and we should at the very least say that. Your revision doesn't really say that strongly enough, nor does it give an API developer a hint as to what that context might consist of. It also takes things a step too far, in my opinion, in telling the RS implementor to make their API RO-specific in some way. I think that's the kind of implementation detail (deeply structural, non-syntactic) that does not belong in the spec.

In my view, a spec like UMA should assume that the API that it's protecting is fully formed and unchanging. Entertaining the idea that an API would "become able" to accept inputs at all is vastly overestimating the draw of UMA. I *like* UMA, and understand it, and even then if I had an API that didn't match UMA's model I'd more likely not use UMA as opposed to change the API to accommodate UMA.

You're absolutely right that this is implementation guidance, but I think we disagree on the appropriate place to put such guidance. I believe we need to be very up front about the assumed mental model in the specification itself. The implementor's guide can go into great detail of that model, and it should, but that in no way means that the spec itself should be silent on the topic.

The underlying problem of resource mapping is something that I hope and believe we can fix in 2.0, FWIW.

-- Justin

On 8/22/2015 9:58 PM, Eve Maler wrote:

...

Yes, you’re right that this is a piece of context that the client has to present, which means the API has to be able (or become able) to ingest it. (So what is the material cost of choosing a query parameter over providing the context in the request header or body, given that it creates whole new resources?)

As regards implementation detail in the wording, we’ve gone from a little (original, which was inaccurate) to less (my revision) to a heck of a lot (your revision). The protocol spec really doesn’t seem like the place for this, whereas this is exactly what the UIG is for.

Eve

...

On 22 Aug 2015, at 5:45 PM, Justin Richer < mailto:jricher@mit.edujricher@mit.edu mailto:jricher@mit.edu> wrote:

If the client provides an additional parameter as a query parameter, then that's a different URI and therefore a different resource. (Remember, the URI is the scheme, host, port, path, parameters -- all of that together, not just the "root" URI.) That provides enough context to make a decision and it's pretty much vanilla UMA there. The client could also send a specialized header or body or something like that -- that's also guiding context. However: all of these need to be built into the API, and APIs that are built like that are fine as per the UMA 1.0 spec.

What you describe as "the small cost of inventing a" necessitates change to the API structure, which is precisely what the original issue was getting at. I really think we ought to tell API developers that if they want to use UMA, then their API needs to behave in a certain way for it to work.

As such, I suggest this wording:

Note: When a client attempts access to a presumptively protected resource without an access token, the resource server needs to ascertain the authorization server and resource set identifier associated with that resource based on the context of the client's request. As this context does not include the access token, which can be used to identify the resource owner and authorization server, this effectively means that the API needs to be structured in such a way that the client's unauthenticated request can uniquely identify the resource set. In practice, this information is likely passed through the URI, headers, or body of the request.

-- Justin

On 8/22/2015 8:31 PM, Eve Maler wrote:

...

When we discussed this on the last call, we gained consensus around wording as follows (emphasis added — hopefully the formatting will make it through):

"Note: When a client attempts access to a presumptively protected resource without an access token, the resource server needs to ascertain the authorization server and resource set identifier associated with that resource without any context to guide it. In practice, this likely means that the URI reference used by the client needs to be unique per resource set.”

In the previous week’s discussion, I’d had a high-level suggestion for a strategy for providing RO context, which we discussed briefly and concluded didn’t satisfy the goal to let existing APIs stay as they are, but thinking about it again, I’m not sure why that is. Let me run through it in detail.

If the RS has an API that is completely generic per RO, such as a singular endpoint that normally depends entirely on an OAuth token to convey the user context, it would similarly register that singular resource set over and over for each of its many users (each using a different PAT) at an AS, getting a unique resource set ID for each in turn.

It does indeed have to be prepared to associate some attribute with a resource set that can later be matched up with the PAT, and then what remains is for a client to provide that attribute somehow when attempting access with no token. Depending on the nature of the API, the context could be in a query parameter, or something in the request body. So “without any context to guide it” in our wording isn’t strictly true.

The approach I mentioned on the call was what appeared in our wireframes as an “authorization code” that the AS would send in an email notification to the RqP, which the client would use in attempting access. That probably wasn’t quite the right way of envisioning the UX, but I think Justin was saying that this requires propagating changed URI structure all the way through. I don’t believe this is needed.

Here are several ways to complete the PAT-to-client-context chain for a resource set given our same example, using the “uri” location property of the resource set description, which is optional and the only part of a resource set description that isn’t entirely abstract: If the RS registered the endpoint with some kind of query parameter on it identifying the RO, discoverability would be possible, at (what I believe is) the small cost of inventing a “new URL” just for the purpose of user discoverability but not real URI namespace management. Thinking about Twitter’s API, it would be possible to look up “Alice in Twitter”, “Bob in Twitter”, etc. in the directory and attempt access to their protected Twitter endpoints without inventing new API structure. If the RS and AS had the opportunity to extend the resource set description JSON structure for extra discoverability features, the RS could add a property for RO identity, enabling an out-of-band means for the requesting side to discover and convey RO identity in, say, a request body. If the RS registered only the generic endpoint, indeed discoverability wouldn’t be possible without a totally out-of-band RO hint provided somehow. If this thinking is correct, I think it would be a good idea to revise our wording because we were trying to signal something about the nature of the RS API, but backed off of it and — while making a potentially true statement about the client API call — overstated the case by getting into implementation detail (“the URI reference used by the client"). I suggest making the following revision:

"Note: When a client attempts access to a presumptively protected resource without an access token, the resource server needs to ascertain the authorization server and resource set identifier associated with that resource. If the interface presented by the resource server is not resource owner-specific, the client needs to supply sufficient additional context as part of the resource request. See the [UMA-Impl] for advice on ways to accomplish this.”

…and then, obviously, adding something like the analysis above to the UIG. (Note that I call it “interface” and not “API” because we do that elsewhere in the spec; we don’t presume it has an API in the classic sense.)

Thoughts?

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