Authors,
While reviewing this document during AUTH48, please resolve (as necessary)
the following questions, which are also in the XML file.
1) <!-- [rfced] Section 1: This sentence does not parse. As it appears
that "then fetch" means "then the client fetches", may we update as
suggested below?
Original:
In other cases, it may be
dynamically discovered; for example, a user could enter their email
address into an email client, the client could perform WebFinger
[RFC7033] discovery (in a manner related to the description in
Section 2 of "OpenID Connect Discovery 1.0" [OpenID.Discovery]) to
find the resource server, then fetch the resource server metadata to
find the authorization server to use to obtain authorization to
access the user's email.
Suggested:
In
other cases, it may be dynamically discovered; for example, a user
could enter their email address into an email client, the client
could perform WebFinger discovery [RFC7033] (in a manner related to
the description in Section 2 of [OpenID.Discovery]) to find the
resource server, and the client could then fetch the resource server
metadata to find the authorization server to use to obtain
authorization to access the user's email. -->
2) <!-- [rfced] Section 1: We changed "Software Statement" to "software
statement" per the text of RFC 7591 and changed "Dynamic Client
Registration" to "dynamic client registration" per RFCs 7591, 9700,
and 9701. Please let us know any objections.
Original:
This is
analogous to the role that the Software Statement plays in OAuth
Dynamic Client Registration [RFC7591].
Currently:
This is
analogous to the role that the software statement plays in OAuth
dynamic client registration [RFC7591]. -->
3) <!-- [rfced] Section 1: We had trouble parsing this sentence. We
removed the comma before "but that" to clarify that "that" refers
to attacker-generated metadata and is not used as a noun. If this
update is incorrect, please clarify what "but that" refers to.
Original:
This prevents attackers from publishing metadata supposedly
describing the protected resource, but that is not actually
authoritative for the protected resource, as described in
Section 7.3.
Currently:
This prevents attackers from publishing metadata that supposedly
describes the protected resource but that is not actually
authoritative for the protected resource, as described in
Section 7.3. -->
4) <!-- [rfced] Sections 1 and subsequent: Please review and advise
regarding the usage of "<tt>" for certain values and parameters as
listed in the XML file for this document. For example, we see
2 instances of (OAuth 2.0) "<tt>scope</tt> values" and 1 instance of
"scope values". Should usage be consistent? Also, please review the
parameters listed in Sections 2 and 8.1.2; no <tt>s for parameters
listed in Section 2, but parameters listed in Section 8.1.2 (except
for "signed_metadata"; see below) are enclosed in <tt>s.
A few more examples:
"alg values": 2 instances with <tt>, 2 without
GET ("<tt>GET</tt> request" vs. "the GET")
<dt>Metadata Name:</dt><dd>signed_metadata</dd> (Section 8.1.2)
(All other parameter names in Section 8.1.2 that follow
"Metadata Name: " are enclosed in <tt>s.) -->
5) <!-- [rfced] Sections 1 and 2: We had trouble determining what
"for instance" refers to in these sentences. For example, in the
first sentence listed below, we do not see any mention of
"jwks_uri" in [FAPI.MessageSigning] (although we see "jwks_uri"
in Section 2 of this document as well as RFCs 7591, 7592, 8414,
8705, 8725, 9068, 9700, and 9701, but [FAPI.MessageSigning] does not
mention any of these published RFCs, except for one mention of
RFC 8705 ("This is outside of the scope of both [RFC8705] and the
FAPI standards")). Could these sentences be reworded to make them
clearer?
Original:
These values may be
used by other specifications, such as the jwks_uri used to publish
public keys the resource server uses to sign resource responses, for
instance, as described in [FAPI.MessageSigning].
...
JSON array containing a list of the JWS [JWS] signing
algorithms (alg values) [JWA] supported by the protected resource
for signing resource responses, for instance, as described in
[FAPI.MessageSigning].
Possibly:
These values may be
used by other specifications, such as the jwks_uri (see Section 2)
used to publish public keys the resource server uses to sign
resource responses, as described in [FAPI.MessageSigning].
...
JSON array containing a list of the JWS [JWS] signing
algorithms (alg values) [JWA] supported by the protected resource
for signing resource responses - for instance, as described in
[FAPI.MessageSigning]. -->
6) <!-- [rfced] Section 1.1: "uses of ... utilize", which also means
"uses of ... uses", read oddly. We changed "uses of" to
"applications of". Please let us know any objections.
Original:
All uses of JSON Web Signature (JWS) [JWS] and JSON Web Encryption
(JWE) [JWE] data structures in this specification utilize the JWS
Compact Serialization or the JWE Compact Serialization; the JWS JSON
Serialization and the JWE JSON Serialization are not used.
Currently:
All applications of JSON Web Signature (JWS) data structures [JWS]
and JSON Web Encryption (JWE) data structures [JWE] as discussed in
this specification utilize the JWS Compact Serialization or the JWE
Compact Serialization; the JWS JSON Serialization and the JWE JSON
Serialization are not used. -->
7) <!-- [rfced] Section 1.2: This text says "This specification uses
the terms ...", but except for a few terms (e.g., "Client
Authentication" (only used in the title of Section 5.3), "Claim
Name", "Authorization Code"), we could not find any instances of the
following terms anywhere in the text:
Authorization Endpoint, Authorization Grant, Client Secret, Grant
Type, Redirection URI, Refresh Token, Resource Owner, Response Type,
Token Endpoint, and Claim Value.
We see that this paragraph was taken from Section 1.2 of RFC 8414.
We also see similar paragraphs in several other post-6000 RFCs.
The following terms are lowercased in text everywhere else in this
document. Should we lowercase them in this list as well?
Access Token, Authorization Server, Client, Client Identifier,
Protected Resource, and Resource Server
We see that the terms listed as being from RFC 6749 are lowercased
in RFC 6749. Lowercase versus uppercase for the terms listed as
being in [JWT] (RFC 7519) is mixed.
If all of these terms are relevant to this document, should the text
be reworded to suggest that readers be familiar with them? If not,
could this paragraph be (1) updated to tailor it to this document, as
was done in RFCs 9470 and 9700 or (2) removed?
Original:
This specification uses the terms "Access Token", "Authorization
Code", "Authorization Endpoint", "Authorization Grant",
"Authorization Server", "Client", "Client Authentication", "Client
Identifier", "Client Secret", "Grant Type", "Protected Resource",
"Redirection URI", "Refresh Token", "Resource Owner", "Resource
Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0
[RFC6749], the terms "Claim Name", "Claim Value", and "JSON Web Token
(JWT)" defined by JSON Web Token (JWT) [JWT]. -->
8) <!-- [rfced] Sections 2 and 8.1.2: We changed "Bearer Token" to
"bearer token" per RFC 6750. Please let us know any objections.
If no objections, we will ask IANA to change "Bearer Token" to
"bearer token" in the "OAuth Protected Resource Metadata" registry
on <https://www.iana.org/assignments/oauth-parameters/> just prior to
publication.
Original:
JSON array containing a list of the supported methods
of sending an OAuth 2.0 Bearer Token [RFC6750] to the protected
resource.
...
* Metadata Description: JSON array containing a list of the OAuth
2.0 Bearer Token presentation methods that this protected resource
supports
Currently:
JSON array containing a list of the supported methods
of sending an OAuth 2.0 bearer token [RFC6750] to the protected
resource.
...
Metadata Description: JSON array containing a list of the OAuth 2.0
bearer token presentation methods that this protected resource
supports -->
9) <!-- [rfced] Section 2.2: For ease of the reader, we provided a
brief explanation of the term "MACed" per RFC 7591. Please let us
know any objections.
Original:
The signed metadata MUST be
digitally signed or MACed using JSON Web Signature (JWS) [JWS] and
MUST contain an iss (issuer) claim denoting the party attesting to
the claims in the signed metadata.
Currently:
The signed metadata MUST be
digitally signed or MACed (protected with a Message Authentication
Code) using a JSON Web Signature (JWS) [JWS] and MUST contain an iss
(issuer) claim denoting the party attesting to the claims in the
signed metadata. -->
10) <!-- [rfced] Please review the four sourcecode entries in this
document, and let us know if you would like to specify a type.
For example, should the first and second sourcecode items have the
type set to "http-message", and should the third and fourth
sourcecode items have the type set to "json"? Please review and
advise.
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, please let us know. Also, it is
acceptable to leave the "type" attribute unset. -->
11) <!-- [rfced] Section 4: Please confirm that "OAuth protected
resources for protected resources" is as intended.
Original:
protected_resources
OPTIONAL. JSON array containing a list of resource identifiers
for OAuth protected resources for protected resources that can be
used with this authorization server. -->
12) <!-- [rfced] Figure 1: We see that the bottom set of boxes for
"Client", "Resource Server", and "Authorization Server" appear in the
SVG but not the ASCII art. Please update so that the ASCII art and
the SVG match.
-->
13) <!-- [rfced] Section 5: The descriptive text regarding the steps
shown in Figure 1 doesn't seem to align with the steps shown in
Figure 1:
In Figure 1:
Step 5 is "Validate ..." and "... Build ..."
Step 6 is "Fetch ..."
In the text:
Step 5 is "... validates ..."
Step 6 is "... builds ..." and "... makes a request to fetch ..."
May we update the descriptive text as suggested below?
Original:
| 5. Validate RS Metadata | | |
| Build AS Metadata URL | | |
...
| 6. Fetch AS Metadata | |
...
5. The client validates the protected resource metadata, as
described in Section 3.3.
6. The client builds the authorization server metadata URL from an
issuer identifier in the resource metadata according to
[RFC8414] and makes a request to fetch the authorization server
metadata.
Suggested (easier to change the text than the figure):
5. The client validates the protected resource metadata, as
described in Section 3.3, and builds the authorization server
metadata URL from an issuer identifier in the resource metadata
according to [RFC8414].
6. The client makes a request to fetch the authorization server
metadata. -->
14) <!-- [rfced] Section 5.3: Does "scenarios where" also apply to the
text after "and", or is the text after "and" a separate thought? If
the former, may we update as suggested?
Original:
This specification is intended to be deployed in scenarios where the
client has no prior knowledge about the resource server, and the
resource server might or might not have prior knowledge about the
client.
Suggested:
This specification is intended to be deployed in scenarios where the
client has no prior knowledge about the resource server and where
the resource server might or might not have prior knowledge about
the client. -->
15) <!-- [rfced] Section 6: "such as resource" looked odd in the text
output, so we placed "resource" in quotes per 'The name requested
(e.g., "resource")' in Section 8.1.1. Please let us know any
objections.
Original:
For example, the member names in the
metadata response might be compared to specific member names such as
resource.
Currently:
For example, the member names in the
metadata response might be compared to specific member names such as
"resource". -->
16) <!-- [rfced] Section 7.6: We had trouble determining what "or which
could be published" refers to. If the suggested text is not correct,
please clarify.
Original:
For
instance, some protected resources are used with a fixed
authorization server or set of authorization servers, the locations
of which may be well known, or which could be published as metadata
values by the protected resource.
Suggested (guessing that the location information could be published):
For
instance, some protected resources are used with a fixed
authorization server or set of authorization servers, the locations
of which may be well known or could be published by the protected
resource as metadata values. -->
17) <!-- [rfced] Section 7.9: We see "PKIX" mentioned in RFC 9525 but
not standalone "PKI". Would you prefer to mention "PKIX" instead of
"PKI" here?
Original:
This means that its security is dependent upon
the Internet Public Key Infrastructure (PKI) [RFC9525].
Possibly:
This means that its security is dependent
upon the Internet Public Key Infrastructure using X.509 (PKIX)
[RFC9525]. -->
18) <!-- [rfced] Section 7.10: RFC 7234 has been obsoleted by RFC 9111.
Because we see "Cache-Control" and "max-age" discussed in RFC 9111 as
well, we updated the RFC number accordingly. Please let us know any
objections.
Original ("utlize" has been fixed):
Implementations should utlize HTTP
caching directives such as Cache-Control with max-age, as defined in
[RFC7234], to enable caching of retrieved metadata for appropriate
time periods.
...
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
RFC 7234, DOI 10.17487/RFC7234, June 2014,
<https://www.rfc-editor.org/info/rfc7234>.
Currently:
Implementations should utilize HTTP
caching directives such as Cache-Control with max-age, as defined in
[RFC9111], to enable caching of retrieved metadata for appropriate
time periods.
...
[RFC9111] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Caching", STD 98, RFC 9111,
DOI 10.17487/RFC9111, June 2022,
<https://www.rfc-editor.org/info/rfc9111>. -->
19) <!-- [rfced] We have removed this first paragraph, as it seems unnecessary.
Please review.
Original:
The following registration procedure is used for the registry
established by this specification.
-->
20) <!-- [rfced] To clarify the text, please consider the following
update. Currently, it is unclear whether mail sent to the list
initiates review or if it is where the expert sends the comments.
In addition, does the text need to mention Designated Experts,
because Expert Review is already part of Specification Required?
Original:
Values are registered on a Specification Required [RFC8126] basis
after a two-week review period on the oauth-ext-rev...@ietf.org
mailing list, on the advice of one or more Designated Experts.
Perhaps:
Values are registered per Specification Required [RFC8126].
Registration requests should be sent to <oauth-ext-rev...@ietf.org>
to initiate a two-week review period.
-->
21) <!-- [rfced] Note that we have updated the text as follows based on
discussion with IANA. Please let us know if you have concerns.
Original:
The IANA escalation process is followed when the designated experts
are not responsive within 14 days.
Current:
If the designated experts are not responsive, the registration requesters
should contact IANA to escalate the process.
-->
22) <!-- [rfced] For clarity, please consider whether "makes sense" should
be "is clear and fits the purpose of the registry"? In addition, we
suggest stating the criteria clearly (i.e., is the designated expert
supposed to approve or not approve proposals that duplicate functionality).
Original:
Criteria that should be applied by the Designated Experts includes
determining whether the proposed registration duplicates existing
functionality, whether it is likely to be of general
applicability or is useful only for a single application,
and whether the registration makes sense.
Perhaps:
Designated experts should apply the following criteria when reviewing
proposed registrations: they must be unique, that is, they should not
duplicate existing functionality; they are likely generally applicable,
as opposed to being used for a single application; and they are clear
and fit the purpose of the registry.
-->
23) <!-- [rfced] This sentence is tough to parse. Please consider the
following update for clarity.
Original:
The reason to allow the Designated Experts to allocate values prior
to publication as a final specification is to enable giving authors
of specifications proposing registrations the benefit of review by
the Designated Experts before the specification is completely done,
so that if problems are identified, the authors can iterate and fix
them before publication of the final specification.
Perhaps:
Designated experts may allocate values prior to publication of the
final specification. This allows authors to receive guidance from
the designated experts early, so any identified issues can be fixed
before the final specification is published.
-->
24) <!-- [rfced] [USA15] Do you want to specifically refer to the 2015 version
of the standard, or do you want to refer to the most current version?
Currently, we have updated this reference listing to primarily refer to the
2015 version, and we have included a second link to the curent version. Please
review.
Original:
[USA15] Davis, M. and K. Whistler, "Unicode Normalization Forms",
Unicode Standard Annex 15, 1 June 2015,
<https://www.unicode.org/reports/tr15/>.
Currently:
[USA15] Davis, M., Ed. and K. Whistler, Ed., "Unicode
Normalization Forms", Unicode Standard Annex #15, 1 June
2015, <https://www.unicode.org/reports/tr15/tr15-43.html>.
Latest version available at
<https://www.unicode.org/reports/tr15/>. -->
25) <!-- [rfced] Acknowledgements: We found that all names were listed
in alphabetical order by last name, except for Gabriel Corona. We
moved Gabriel's name so that it appears after Deb Cooley's name
instead of Roman Danyliw's name. Please let us know any objections.
Original:
We would would also like to thank Amanda
Baber, Mike Bishop, Ralph Bragg, Brian Campbell, Deb Cooley, Roman
Danyliw, Gabriel Corona, Vladimir Dzhuvinov, George Fletcher, Arnt
Gulbrandsen, Pieter Kasselman, Murray Kucherawy, David Mandelberg,
Tony Nadalin, Francesca Palombini, John Scudder, Rifaat Shekh-Yusef,
Filip Skokan, Orie Steele, Atul Tulshibagwale, Éric Vyncke, Paul
Wouters, and Bo Wu for their contributions to the specification.
Currently ("would would" has been fixed):
We would also like to thank Amanda Baber,
Mike Bishop, Ralph Bragg, Brian Campbell, Deb Cooley, Gabriel Corona,
Roman Danyliw, Vladimir Dzhuvinov, George Fletcher, Arnt Gulbrandsen,
Pieter Kasselman, Murray Kucherawy, David Mandelberg, Tony Nadalin,
Francesca Palombini, John Scudder, Rifaat Shekh-Yusef, Filip Skokan,
Orie Steele, Atul Tulshibagwale, Éric Vyncke, Paul Wouters, and Bo Wu
for their contributions to the specification. -->
26) <!-- [rfced] Please review the "Inclusive Language" portion of the
online Style Guide at
<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.
For example, please consider whether the following should be updated:
man-in-the-middle -->
27) <!-- [rfced] The following terms were used inconsistently in this
document. We chose to use the latter forms. Please let us know any
objections.
Protected resource (1 instance) ("The Protected resource's") /
protected resource (108 instances)
Resource Identifier (1 instance in text) ("The protected resource's
Resource Identifier") / resource identifier (19 instances in text)
("The protected resource's resource identifier") -->
Thank you.
RFC Editor
On Apr 9, 2025, at 3:52 PM, rfc-edi...@rfc-editor.org wrote:
*****IMPORTANT*****
Updated 2025/04/09
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/rfc9728.xml
https://www.rfc-editor.org/authors/rfc9728.html
https://www.rfc-editor.org/authors/rfc9728.pdf
https://www.rfc-editor.org/authors/rfc9728.txt
Diff file of the text:
https://www.rfc-editor.org/authors/rfc9728-diff.html
https://www.rfc-editor.org/authors/rfc9728-rfcdiff.html (side by side)
Diff of the XML:
https://www.rfc-editor.org/authors/rfc9728-xmldiff1.html
Tracking progress
-----------------
The details of the AUTH48 status of your document are here:
https://www.rfc-editor.org/auth48/rfc9728
Please let us know if you have any questions.
Thank you for your cooperation,
RFC Editor
--------------------------------------
RFC 9728 (draft-ietf-oauth-resource-metadata-13)
Title : OAuth 2.0 Protected Resource Metadata
Author(s) : M.B. Jones, P. Hunt, A. Parecki
WG Chair(s) : Hannes Tschofenig, Rifaat Shekh-Yusef
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
