Re: [GNAP] generic HTTP resource type

[Jamey Sharp <[e-mail]>]

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