Re: [GNAP] generic HTTP resource type

Justin Richer <> Tue, 10 August 2021 17:20 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 911563A1540 for <>; Tue, 10 Aug 2021 10:20:08 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -1.497
X-Spam-Status: No, score=-1.497 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, HTML_MESSAGE=0.001, KHOP_HELO_FCRDNS=0.399, SPF_HELO_NONE=0.001, SPF_NONE=0.001, URIBL_BLOCKED=0.001] autolearn=no autolearn_force=no
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id j2YCBiHTDODd for <>; Tue, 10 Aug 2021 10:20:03 -0700 (PDT)
Received: from ( []) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by (Postfix) with ESMTPS id B4DAA3A153E for <>; Tue, 10 Aug 2021 10:19:51 -0700 (PDT)
Received: from himiko.fios-router.home ( []) (authenticated bits=0) (User authenticated as jricher@ATHENA.MIT.EDU) by (8.14.7/8.12.4) with ESMTP id 17AHJljC002002 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Tue, 10 Aug 2021 13:19:48 -0400
From: Justin Richer <>
Message-Id: <>
Content-Type: multipart/alternative; boundary="Apple-Mail=_9A42DBDA-7055-40FD-8941-87B463C5DDD8"
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.\))
Date: Tue, 10 Aug 2021 13:19:47 -0400
In-Reply-To: <YQcbWVgc0TKSynQ2@eh>
Cc: Fabien Imbault <>, GNAP Mailing List <>, Torsten Lodderstedt <>, Brian Campbell <>
To: Jamey Sharp <>
References: <YQcbWVgc0TKSynQ2@eh>
X-Mailer: Apple Mail (2.3608.
Archived-At: <>
Subject: Re: [GNAP] generic HTTP resource type
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: GNAP <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Tue, 10 Aug 2021 17:20:09 -0000

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: <>

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 <> 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).
> 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