Subject: Re: [GNAP] generic HTTP resource type

From: Jamey Sharp <[email-masked]>
Date: Sun, 1 Aug 2021 15:08:25 -0700

Hi Justin and Fabien! Thanks for your kind responses. You both provided 
helpful information about the process and requirements, but I'm less 
clear on what my next steps should be. In the interests of trying 
something, here's some text that I propose as a starting point for an 
appendix in the core draft. I welcome edits or complete rewrites.

Many resources have simple access policies which map well onto standard 
HTTP semantics. For example, authorization for WebDAV can generally be 
defined in terms of a WebDAV collection and a set of HTTP methods which 
the client instance is permitted to apply to members of that collection. 
(NB: I haven't touched WebDAV in years, I have no idea if this is a good 
example)

This resource type supports such generic HTTP access policies. HTTP user 
agents which implement RFC7235 MAY support GNAP with this resource type 
as an alternative to other generic authentication schemes such as Basic 
(RFC7617) or Digest (RFC7616).

type (string): "urn:ietf:gnap:http"

locations (array of strings): URL prefixes to which the client instance 
MAY issue requests using this access token without first sending a 
preflight RS-first AS discovery request. This array MUST NOT be absent 
or empty. Each URL in this array MUST use a scheme of "http" or "https", 
MUST be an absolute URI, and MUST have a non-empty path component.

actions (array of strings): HTTP methods which the client instance MAY 
use at the RS. Per RFC7230, the request method is case-sensitive. If 
this array is absent or empty, this access object permits all methods.

If an access object permits a request, that is not a guarantee that 
issuing that request to the RS will succeed. However, if an access 
object does not permit a request, then the client instance MUST NOT 
issue that request using that access token without first performing an 
RS-first AS discovery.

A client instance without any prior knowledge of the resource types in 
use at an RS MAY attempt to use this generic HTTP resource type during 
GNAP requests to the AS. An AS MUST NOT implement a resource type with 
the same value of "type" as given here but with different semantics.

A client instance which performs RS-first AS discovery SHOULD be 
prepared to accept an access policy from the AS which uses this generic 
HTTP resource type.

An RS which uses this resource type SHOULD respond to RS-first AS 
discovery with an `access` parameter which the AS is configured to 
expand to an access object of this type. If it does so, the AS SHOULD 
return an access list containing both the resource reference given in 
the `access` parameter as well as the full access object of this type.

Returning the full access object enables the client instance to avoid 
issuing preflight RS-first AS discovery requests for any request that 
the access object permits.

If the client later performs RS-first AS discovery again and recieves 
the same `as_url` parameter in response, then returning the resource 
reference in the access list enables the client instance to discover 
that it has a valid access token for that resource reference, so it 
doesn't need to query the AS again.

I kind of want to add something like this as well, but started confusing 
myself about what the client can and can't do with it:

datatypes (array of strings): Media types or ranges which the client 
instance MAY send in request bodies. The syntax for each string is given 
by the "media-range" EBNF production in RFC7231. If this array is absent 
or empty, this access object does not permit request bodies. To allow 
any request body, use a media range of "*/*".

Note that if an access object permits the "POST" method for resources 
which are expected to be the target of HTML form submissions, then that 
object likely needs to list "multipart/form-data" and/or 
"application/x-www-form-urlencoded" as permitted datatypes.

Thoughts and feedback?
Thanks,
Jamey

---

From: Justin Richer <[email-masked]>
Date: Tue, 10 Aug 2021 13:19:47 -0400

Hi Jamey,

The editors discussed this and if you can, we would like to see a PR that incorporates this idea as an appendix to the core document. We filed an issue to track this here:

https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/303 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/303>

While this work could eventually end up as a separate document (and there are some good arguments for that already), the editors think it makes sense to at least get this written down as an appendix to start the discussion in context of where it would be used. 

Would you be willing/able to create a PR to add this text in? Alternatively, if you think it should be separate, could you submit an I-D with this proposal?

Also, I’m copying the co-editors of the OAuth 2 RAR specification, since anything like this defined for GNAP is also immediately usable in OAuth 2 RAR. This is another argument for this work being its own document, but wherever it lands, we think this is worth talking about more.

 — Justin (on behalf of the GNAP editors)

> On Aug 1, 2021, at 6:08 PM, Jamey Sharp <[email-masked]> wrote:
> 
> Hi Justin and Fabien! Thanks for your kind responses. You both provided helpful information about the process and requirements, but I'm less clear on what my next steps should be. In the interests of trying something, here's some text that I propose as a starting point for an appendix in the core draft. I welcome edits or complete rewrites.
> 
> 
> Many resources have simple access policies which map well onto standard HTTP semantics. For example, authorization for WebDAV can generally be defined in terms of a WebDAV collection and a set of HTTP methods which the client instance is permitted to apply to members of that collection. (NB: I haven't touched WebDAV in years, I have no idea if this is a good example)
> 
> This resource type supports such generic HTTP access policies. HTTP user agents which implement RFC7235 MAY support GNAP with this resource type as an alternative to other generic authentication schemes such as Basic (RFC7617) or Digest (RFC7616).
> 
> locations (array of strings): URL prefixes to which the client instance MAY issue requests using this access token without first sending a preflight RS-first AS discovery request. This array MUST NOT be absent or empty. Each URL in this array MUST use a scheme of "http" or "https", MUST be an absolute URI, and MUST have a non-empty path component.
> 
> actions (array of strings): HTTP methods which the client instance MAY use at the RS. Per RFC7230, the request method is case-sensitive. If this array is absent or empty, this access object permits all methods.
> 
> If an access object permits a request, that is not a guarantee that issuing that request to the RS will succeed. However, if an access object does not permit a request, then the client instance MUST NOT issue that request using that access token without first performing an RS-first AS discovery.
> 
> A client instance without any prior knowledge of the resource types in use at an RS MAY attempt to use this generic HTTP resource type during GNAP requests to the AS. An AS MUST NOT implement a resource type with the same value of "type" as given here but with different semantics.
> 
> A client instance which performs RS-first AS discovery SHOULD be prepared to accept an access policy from the AS which uses this generic HTTP resource type.
> 
> An RS which uses this resource type SHOULD respond to RS-first AS discovery with an `access` parameter which the AS is configured to expand to an access object of this type. If it does so, the AS SHOULD return an access list containing both the resource reference given in the `access` parameter as well as the full access object of this type.
> 
> Returning the full access object enables the client instance to avoid issuing preflight RS-first AS discovery requests for any request that the access object permits.
> 
> If the client later performs RS-first AS discovery again and recieves the same `as_url` parameter in response, then returning the resource reference in the access list enables the client instance to discover that it has a valid access token for that resource reference, so it doesn't need to query the AS again.
> 
> 
> I kind of want to add something like this as well, but started confusing myself about what the client can and can't do with it:
> 
> datatypes (array of strings): Media types or ranges which the client instance MAY send in request bodies. The syntax for each string is given by the "media-range" EBNF production in RFC7231. If this array is absent or empty, this access object does not permit request bodies. To allow any request body, use a media range of "*/*".
> 
> Note that if an access object permits the "POST" method for resources which are expected to be the target of HTML form submissions, then that object likely needs to list "multipart/form-data" and/or "application/x-www-form-urlencoded" as permitted datatypes.
> 
> 
> Thoughts and feedback?
> Thanks,
> Jamey