On Apr 10, 2025, at 2:58 PM, rfc-edi...@rfc-editor.org wrote:
Authors, While reviewing this document during AUTH48, please resolve (as necessary) the following questions, which are also in the XML file. 1) <!-- [rfced] Please insert any keywords (beyond those that appear in the title) for use on https://www.rfc-editor.org/search. --> 2) <!--[rfced] We changed this paragraph into smaller sentences for easier reading and arranged the list of items in alphabetical order. Please let us know of any objections. Original: Terminology specific to GNAP is defined in the terminology section of the core specification [GNAP], and provides definitions for the protocol roles: authorization server (AS), client, resource server (RS), resource owner (RO), end user; as well as the protocol elements: attribute, access token, grant, privilege, protected resource, right, subject, subject information. The same definitions are used in this document. Current: Terminology specific to GNAP is defined in the terminology section of the core specification [GNAP]. The following protocol roles are defined: authorization server (AS), client, end user, resource owner (RO), and resource server (RS). The following protocol elements are defined: access token, attribute, grant, privilege, protected resource, right, subject, and subject information. The same definitions are used in this document. --> This change is fine. 3) <!--[rfced] To avoid the "[JWT]" citation being used as an adjective, may we update "[JWT] formatted token" to "JSON-formatted token [JWT]" or "JSON Web Token [JWT]" or otherwise? Note that there are 9 instances in the document. Original: In a [JWT] formatted token or a token introspection response, this corresponds to the iss claim. Perhaps: In a JSON-formatted token [JWT] or a token introspection response, this corresponds to the iss claim. Or: In a JSON Web Token [JWT] or a token introspection response, this corresponds to the iss claim. --> Let’s go with: In the payload of a JSON Web Token [JWT] or a token introspection response, this corresponds to the iss claim. 4) <!--[rfced] FYI, we updated the following text for clarity and to make the second sentence a complete sentence. Please review whether the updates are accurate. Original: GNAP access tokens can have multiple data flags associated with them that indicate special processing or considerations for the token. For example, whether the token is a bearer token, or should be expected to be durable across grant updates. Current: GNAP access tokens can have multiple associated data flags that indicate special processing or considerations for a token. For example, the data flags can indicate whether a token is a bearer token or should be expected to be durable across grant updates. --> The change is fine. 5) <!--[rfced] We updated "RS's" to "one or more RSs" in the following text. We also updated "from others usable at" to "from other access tokens used at" in the first paragraph for consistency with the second paragraph. Please let us know if any of these changes are not correct. In addition, please review the remaining instances of "RS's" and "AS's" (singular possessive) throughout the document and let us know if any occurrences are intended to be plural. We have updated a few instances, e.g., "targeted to different RS's" -> "targeted to different RSs". Original: When an access token is used for the grant continuation API defined in Section 5 of [GNAP] (the continuation access token) the token management API defined in Section 6 of [GNAP] (the token management access token), or the RS-facing API defined in Section 3 (the resource server management access token), the AS MUST separate these access tokens from others usable at RS's. [...] For continuation access tokens and token management access tokens, a client instance MUST take steps to differentiate these special- purpose access tokens from access tokens used at RS's. Current: When an access token is used for the grant continuation API defined in Section 5 of [GNAP] (the continuation access token), the token management API defined in Section 6 of [GNAP] (the token management access token), or the RS-facing API defined in Section 3 (the resource server management access token), the AS MUST separate these access tokens from other access tokens used at one or more RSs. [...] For continuation access tokens and token management access tokens, a client instance MUST take steps to differentiate these special- purpose access tokens from access tokens used at one or more RSs. --> These changes are fine. 6) <!-- [rfced] [GNAP] does not contain Section 3.1.2. Please let us know which section was intended (perhaps Section 3.2.1 ("Single Access Token"). Original: The client instance is given token management access tokens only as part of the manage field of the grant response in Section 3.1.2 of [GNAP]. --> Yes, the reference was intended to be section 3.2.1 as this defines the “manage” field that is referenced here. 7) <!--[rfced] In the lists in Sections 3.1 and 3.5, we note that the key words (REQUIRED, OPTIONAL, etc.) are included at the end of the descriptions whereas the key words are included at the beginning of the descriptions in all other relevant sections. Would you like to make these consistent by updating Sections 3.1 and 3.5 as shown in the example below? One example Current: token_formats_supported (array of strings): A list of token formats supported by this AS. The values in this list MUST be registered in the "GNAP Token Format Registry Formats" registry in Section 5.3. OPTIONAL. Perhaps: token_formats_supported (array of strings): OPTIONAL. A list of token formats supported by this AS. The values in this list MUST be registered in the "GNAP Token Format Registry Formats" registry per Section 5.3. --> In the companion specification, RFC9646, we seem to have usually put the keywords at the end on the lists, so I think we should instead update the lists in sections 3.3 (two lists) and 3.4 (two lists) to make them all consistent with the normative requirements at the end. 8) <!--[rfced] Please note the mismatch here between "array of strings" vs. "string". As both of these seem to be regarding the "GNAP Resource Set Registration Request Parameters" registry (as opposed to the "GNAP RS-Facing Discovery Document Fields" registry), should Section 3.4 be updated to "string" to match the registry? Section 3.4 token_formats_supported (array of strings): vs. Section 5.6.2: token_formats_supported | string | Section 3.4 --> Section 5.6.2 should be updated to be “array of strings” and the corresponding entry in the IANA registry will need to be updated as well (it currently is registered as “string” at https://www.iana.org/assignments/gnap/gnap.xhtml#gnap-resource-set-registration-request-parameters 9) <!--[rfced] We are having trouble parsing the following text (are some words missing?). Please let us know how we may update this sentence for clarity. Original: token_formats_supported (array of strings): OPTIONAL. The token formats the RS is able to process for accessing the resource. Perhaps: token_formats_supported (array of strings): OPTIONAL. The list of token formats the RS is able to process in order to access the resources. --> We can simplify to: token_formats_supported (array of strings): OPTIONAL. The list of token formats that the RS is able to process. 10) <!--[rfced] We note "HTTP 400 Bad Request error" vs. "HTTP (Bad Request) status code". Should this perhaps be updated as "HTTP 400 (Bad Request) error code" for consistency as shown below? Original: If the registration fails, the AS returns an HTTP 400 Bad Request error to the RS indicating that the registration was not successful. In the case of an error from the RS-facing API, the AS responds to the RS with an HTTP 400 (Bad Request) status code and a JSON object consisting of a single error field, which is either an object or a string. Perhaps: If the registration fails, the AS returns an HTTP 400 (Bad Request) error code to the RS indicating that the registration was not successful. In the case of an error from the RS-facing API, the AS responds to the RS with an HTTP 400 (Bad Request) error code and a JSON object consisting of a single error field, which is either an object or a string. --> From my understanding of the HTTP style guidelines, these instances should be: … returns HTTP status code 400 (Bad Request) to the RS ... … the RS with HTTP status code 400 (Bad Request) and a … 11) <!--[rfced] FYI, for the sourcecode element in Section 4, two spaces were removed from the left side of the access_token so that it fits the line-length restriction. Please let us know if you prefer otherwise. This line was previously too long: "existing_access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" --> I don’t actually see this change in the source or in the rendered text, but as long as it does not change the relative indentation/formatting of the JSON element in the HTTP request, that should be fine. We can also shave a few characters off of the access token value without affecting the utility of the example. If we do this, we should also change the value in section 3.3 — even though the examples are not directly connected to each other, it was intentional that they use a consistent value. 12) <!--[rfced] Regarding variations of "string/object" in the "GNAP Token Introspection Request" registry. a) In Table 2 (which corresponds to https://www.iana.org/assignments/gnap/gnap.xhtml#gnap-token-introspection-request) would you like to change this type from "object/string" to "string/object" to match the form of the subsequent item? If so, we will ask IANA to update the registry accordingly. Original: resource_server object/string Section 3.3 of RFC xxxx access array of strings/objects Section 3.3 of RFC xxxx Perhaps: resource_server string/object Section 3.3 of RFC 9767 access array of strings/objects Section 3.3 of RFC 9767 No, this should remain as written, “object/string” and “array of strings/objects”. b) Similarly, in Section 3.3, would you like to change "string or object" to "string/object"? (Note: If you decide not to change the original "object/string" above, then we will update "string or object" to "object/string" to match.) Original: resource_server (string or object): REQUIRED. ... access (array of strings/objects): OPTIONAL. ... Perhaps: resource_server (string/object): REQUIRED. ... access (array of strings/objects): OPTIONAL. ... --> This should be: resource_server (object/string): ... And the IANA registry should be updated. 13) <!--[rfced] Regarding variations of "string/object" in the "GNAP Token Introspection Response" and "GNAP Resource Set Registration Request Parameters" registries. a) In Table 3, would you like to change "object/string" to "string/object" to match usage in the preceding item? If so, we will ask IANA to update the registry (https://www.iana.org/assignments/gnap/gnap.xhtml#gnap-token-introspection-response) accordingly. Original: | access | array of strings/objects | Section 3.3 of RFC xxxx | | key | object/string | Section 3.3 of RFC xxxx | Perhaps: | access | array of strings/objects | Section 3.3 of RFC 9767 | | key | string/object | Section 3.3 of RFC 9767 | b) Similarly, in Section 3.3, would you like to change "object/string" to "string/object" to match usage in the preceding item? Original: key (object/string): REQUIRED if ... Perhaps: key (string/object): REQUIRED if ... No, these should remain “object/string” and “array of strings/objects” as written. c) With the same rationale, in Section 3.4 (and Table 4), would you like to change this as follows? If so, we will ask IANA to update the registry (https://www.iana.org/assignments/gnap/gnap.xhtml#gnap-resource-set-registration-request-parameters) accordingly. Original: resource_server (string or object) Perhaps: resource_server (string/object) --> This should be: resource_server (object/string) as above. The IANA registry should be updated accordingly. 14) <!--[rfced] May we update this sentence for clarity? Original: The contents of the access token model divulge to the RS information about the access token's context and rights. Perhaps: The contents of the access token model, which contains information about the access token's context and rights, are divulged to the RS. --> Perhaps instead: The contents of the access token model divulge information about the access token’s context and rights to the RS. 15) <!--[rfced] Would using "certain circumstances" in place of "limited circumstances" be better to avoid the redundancy of "limiting" and "limited" as shown below? Original: Furthermore, limiting the use of bearer tokens and AS-provided keys to only highly trusted AS's ASs and limited circumstances prevents the attacker from being able to willingly exfiltrate their token to an unsuspecting client instance. Perhaps: Furthermore, limiting the use of bearer tokens and AS-provided keys to only highly trusted ASs and certain circumstances prevents the attacker from being able to willingly exfiltrate their token to an unsuspecting client instance. --> I think instead we can say: Furthermore, limiting the use of bearer tokens and AS-provided keys to only highly trusted ASs in certain circumstances prevents the attacker from being able to willingly exfiltrate their token to an unsuspecting client instance. 16) <!-- [rfced] The URL <https://www.ndss-symposium.org/ndss2014/ ndss-2014-programme/macaroons-cookies-contextual-caveats- decentralized-authorization-cloud/> provides an open-access link to this symposium paper and is where the DOI for this paper directs. May we replace the original URL with this URL as shown below? Current: [MACAROON] Birgisson, A., Politz, J. G., Erlingsson, U., Taly, A., Vrable, M., and M. Lentczner, "Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud", NDSS Symposium 2014, DOI 10.14722/ndss.2014.23212, February 2014, <https://research.google/pubs/pub41892/>. Perhaps: [MACAROON] Birgisson, A., Politz, J. G., Erlingsson, U., Taly, A., Vrable, M., and M. Lentczner, "Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud", NDSS Symposium 2014, DOI 10.14722/ndss.2014.23212, February 2014, <https://www.ndss-symposium.org/ndss2014/ ndss-2014-programme/macaroons-cookies-contextual-caveats- decentralized-authorization-cloud/>. --> This change is fine - whatever the best URL is for the reference. I am not able to find another RFC that references the Macaroon format. 17) <!-- [rfced] FYI: To match other usage in the document, we updated the first artwork element in Section 3.2 to sourcecode and set the type to "http-message". Please let us know if we need to update otherwise. Additionally, please review the "type" attribute of each sourcecode element in the XML file to ensure correctness. If the current list of preferred values for "type" (https://www.rfc-editor.org/rpc/wiki/doku.php?id=sourcecode-types) does not contain an applicable type, then feel free to let us know. Also, it is acceptable to leave the "type" attribute not set. --> Yes, these look good. 18) <!-- [rfced] Please review usage of <tt> and <em> in this document and let us know if any updates are needed. In the HTML and PDF outputs, the text enclosed in <tt> is output in fixed-width font. In the TXT output, there are no changes to the font, and quotation marks are not generated. In the HTML and PDF outputs, the text enclosed in <em> is output in italics. In the TXT output, the text enclosed in <em> appears with an underscore before and after. This is used only in Section 2.1.1. --> Yes, these look good. 19) <!-- [rfced] Please review the "Inclusive Language" portion of the online Style Guide <https://www.rfc-editor.org/styleguide/part2/#inclusive_language> and let us know if any changes are needed. Updates of this nature typically result in more precise language, which is helpful for readers. Note that our script did not flag any words in particular, but this should still be reviewed as a best practice. --> I believe we have followed best practice for this language. Thank you. RFC Editor/kc/ar I believe with these changes implemented we should be ready to publish. — Justin On Apr 10, 2025, rfc-edi...@rfc-editor.org wrote: *****IMPORTANT***** Updated 2025/04/10 RFC Author(s): -------------- Instructions for Completing AUTH48 Your document has now entered AUTH48. Once it has been reviewed and approved by you and all coauthors, it will be published as an RFC. If an author is no longer available, there are several remedies available as listed in the FAQ (https://www.rfc-editor.org/faq/). You and you coauthors are responsible for engaging other parties (e.g., Contributors or Working Group) as necessary before providing your approval. Planning your review --------------------- Please review the following aspects of your document: * RFC Editor questions Please review and resolve any questions raised by the RFC Editor that have been included in the XML file as comments marked as follows: <!-- [rfced] ... --> These questions will also be sent in a subsequent email. * Changes submitted by coauthors Please ensure that you review any changes submitted by your coauthors. We assume that if you do not speak up that you agree to changes submitted by your coauthors. * Content Please review the full content of the document, as this cannot change once the RFC is published. Please pay particular attention to: - IANA considerations updates (if applicable) - contact information - references * Copyright notices and legends Please review the copyright notice and legends as defined in RFC 5378 and the Trust Legal Provisions (TLP – https://trustee.ietf.org/license-info). * Semantic markup Please review the markup in the XML file to ensure that elements of content are correctly tagged. For example, ensure that <sourcecode> and <artwork> are set correctly. See details at <https://authors.ietf.org/rfcxml-vocabulary>. * Formatted output Please review the PDF, HTML, and TXT files to ensure that the formatted output, as generated from the markup in the XML file, is reasonable. Please note that the TXT will have formatting limitations compared to the PDF and HTML. Submitting changes ------------------ To submit changes, please reply to this email using ‘REPLY ALL’ as all the parties CCed on this message need to see your changes. The parties include: * your coauthors * rfc-edi...@rfc-editor.org (the RPC team) * other document participants, depending on the stream (e.g., IETF Stream participants are your working group chairs, the responsible ADs, and the document shepherd). * auth48archive@rfc-editor.org, which is a new archival mailing list to preserve AUTH48 conversations; it is not an active discussion list: * More info: https://mailarchive.ietf.org/arch/msg/ietf-announce/yb6lpIGh-4Q9l2USxIAe6P8O4Zc * The archive itself: https://mailarchive.ietf.org/arch/browse/auth48archive/ * Note: If only absolutely necessary, you may temporarily opt out of the archiving of messages (e.g., to discuss a sensitive matter). If needed, please add a note at the top of the message that you have dropped the address. When the discussion is concluded, auth48archive@rfc-editor.org will be re-added to the CC list and its addition will be noted at the top of the message. You may submit your changes in one of two ways: An update to the provided XML file — OR — An explicit list of changes in this format Section # (or indicate Global) OLD: old text NEW: new text You do not need to reply with both an updated XML file and an explicit list of changes, as either form is sufficient. We will ask a stream manager to review and approve any changes that seem beyond editorial in nature, e.g., addition of new text, deletion of text, and technical changes. Information about stream managers can be found in the FAQ. Editorial changes do not require approval from a stream manager. Approving for publication -------------------------- To approve your RFC for publication, please reply to this email stating that you approve this RFC for publication. Please use ‘REPLY ALL’, as all the parties CCed on this message need to see your approval. Files ----- The files are available here: https://www.rfc-editor.org/authors/rfc9767.xml https://www.rfc-editor.org/authors/rfc9767.html https://www.rfc-editor.org/authors/rfc9767.pdf https://www.rfc-editor.org/authors/rfc9767.txt Diff file of the text: https://www.rfc-editor.org/authors/rfc9767-diff.html https://www.rfc-editor.org/authors/rfc9767-rfcdiff.html (side by side) Diff of the XML: https://www.rfc-editor.org/authors/rfc9767-xmldiff1.html Tracking progress ----------------- The details of the AUTH48 status of your document are here: https://www.rfc-editor.org/auth48/rfc9767 Please let us know if you have any questions. Thank you for your cooperation, RFC Editor -------------------------------------- RFC9767 (draft-ietf-gnap-resource-servers-09) Title : Grant Negotiation and Authorization Protocol Resource Server Connections Author(s) : J. Richer, Ed., F. Imbault WG Chair(s) : Yaron Sheffer, Leif Johansson Area Director(s) : Deb Cooley, Paul Wouters
-- auth48archive mailing list -- auth48archive@rfc-editor.org To unsubscribe send an email to auth48archive-le...@rfc-editor.org
