[GNAP] generic HTTP resource type

[Jamey Sharp <[e-mail]>]

In today's meeting, I asked about applying GNAP as the HTTP 
authentication method for arbitrary HTTP resources, such as static 
files, in the same way that Basic and Digest auth can be used today. 
Justin asked me to share the question here.

Because the current draft includes RS-first AS discovery using the 
standard WWW-Authenticate response header, it might work for this use 
case as-is, but I think it can be improved.

First: Am I correct in thinking that two access tokens retrieved from 
the same AS, by the same end user, with the same "access" list, should 
be indistinguishable to the client? Specifically, if a client receives 
two `WWW-Authenticate: GNAP` headers with the same "as_url" and "access" 
parameters, can it reuse the access token it got for the first request 
on the second request, without consulting the AS again?

If so, I think the WWW-Authenticate "access" parameter is equivalent to 
the "realm" parameter defined in RFC7235 and used in RFC7617 Basic auth. 
(Perhaps for consistency with HTTP auth, it should in fact be called 
"realm" when used in that header? RFC7235 even uses "scope" terminilogy 
to describe it.)

Without additional provisions, which I'm pretty sure are not currently 
in GNAP, checking for matching realm/access parameters still requires an 
extra unauthenticated request any time the client needs to access a URL 
it hasn't visited before, even if the response turns out to indicate 
that an earlier access token can be reused.

RFC7617 defines somewhat magic rules for when a client can proactively 
provide Basic-scheme credentials to a URL where it hasn't previously 
seen a WWW-Authenticate header, in order to avoid a round-trip in the 
common case where the same credentials are accepted at similar URLs. In 
theory, GNAP could specify something similar to make RS-first AS 
discovery more efficient, but that level of magic seems dangerous to me.

The Digest auth scheme in RFC7616 instead allows the server (in this 
context, the RS) to give an explicit list of URL prefixes which accept 
the same credentials, in the WWW-Authenticate "domain" parameter. I 
think that's a closer fit for GNAP, but rather than making it a header 
parameter, I think it's best to fold it into the token's access rights.

I propose standardizing a definition of a "type" value for the rights 
request that describes HTTP access rights generically, rather than 
describing actions appropriate to a specific API. I think that would 
make GNAP usable anywhere that Basic or Digest auth are currently used. 
It might also enable a wide variety of RESTful APIs and HTTP-based 
standards to use GNAP without needing to define custom rights types.

Here is a concrete suggestion as a starting point for discussion:

"access": [{
   "type": "http",
   "locations": ["https://example.com/protected/"],
   "datatypes": ["text/html", "image/*"],
   "actions": ["GET", "PUT", "DELETE"]
}]

A resource request must match all fields to be allowed. If "datatypes" 
or "actions" are empty or absent, then all are permitted. (Permitting 
nothing is the same as not granting any rights at all.) The "locations" 
field is required to be present and non-empty though, and might work 
like the "domain" parameter in Digest: "The client can use this list to 
determine the set of URIs for which the same authentication information 
may be sent: any URI that has a URI in this list as a prefix [...] MAY 
be assumed to be in the same protection space."

This allows a client to request a limited set of methods or access to a 
limited portion of the protection space. It also allows the AS to inform 
the client of exactly which requests it may use the access token on, 
which may be different than what the client requested.

If I'm reading the current draft correctly, if a client sends an opaque 
resource reference like `"access": "WallyWorld"`, then the AS may choose 
to send back a non-opaque description of the rights granted by the 
returned access token, such as the above example for the hypothetical 
"http" rights type. Is that right?

I suppose the downside of the AS transforming an opaque reference into a 
full rights description is that the client can't indicate which rights 
types it understands. If a CMS supports a proprietary API for editing 
blog posts, but also supports WebDAV for file attachments, it might not 
be clear which rights type to use, yeah?

So here's an additional proposal: a client wishing to use this generic 
HTTP rights type should (must?) explicitly request it in the "access" 
rights request (and may also include the resource reference given in the 
"access" parameter of the WWW-Authenticate header, if any). It must 
specify the exact request URL in the "locations" field, and may also 
specify the method it tried to use in "actions". As usual, the AS may 
return a token granting rights to a wider range of locations or methods 
and is recommended to return the actual granted rights.

I hope that's reasonably clear and would love to discuss this further.

Jamey