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