Re: [GNAP] generic HTTP resource type

[Justin Richer <[e-mail]>]

Hi Jamey,

Thanks for this thorough writeup, this is a fascinating idea, and as an individual I think it has some merit and warrants discussion. Now the question is what to do with that idea, and I can think of a handful of immediate options, detailed below. There are probably others.

But first, a note: the “type” element serves an important namespace function. In particular, a general-purpose “type” value would want to be something that’s collision-resistant, like a URI. Which URI gets used here depends a lot on where this definition would go. The documentation that defines the “type” element also defines the structure and contents of the object that contains the “type” element, so the language about what goes in “locations”, “datatypes”, and “actions” would all be defined with the “type” value. Of course, it’s entirely up to an AS/RS to map a given “type” value to a given definition set, but that’s the nature of protecting general APIs with a common security protocol — we can’t dictate that people interpret things a particular way.

These are the options for this type definition I can think of right now:

1) Defined as an appendix in GNAP Core. We can also use it in some examples. It remains optional to interpret or support for a given AS/RS.
2) Defined in a separate GNAP document.
3) Defined by a different WG. Perhaps HTTP-API would want to look at this?
4) Defined on a webpage on the internet, without a standards body behind it. The URL would be the URL of the document.

All of these have equal functionality inside of GNAP because of the supremacy of the AS/RS in this decision. And even better, anything defined for this part of GNAP is immediately usable in OAuth 2 RAR as well.

I’d like to hear what people think about this proposal — is it a good one, is it worth writing down, and if so, where?

 — Justin

> On Jul 26, 2021, at 9:04 PM, Jamey Sharp <[e-mail]> wrote:
> 
> 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
> 
> -- 
> TXAuth mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/txauth