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.
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
_______________________________________________
WG-UMA mailing list
WG-UMA@kantarainitiative.org
http://kantarainitiative.org/mailman/listinfo/wg-uma