Thanks again for the detailed review, Atul! I’ve updated the PR accordingly.
Responses are inline below…
From: OAuth <oauth-boun...@ietf.org> On Behalf Of Atul Tulshibagwale
Sent: Friday, March 29, 2024 6:31 PM
To: Rifaat Shekh-Yusef <rifaat.s.i...@gmail.com>; oauth <oauth@ietf.org>
Subject: Re: [OAUTH-WG] WGLC for OAuth 2.0 Protected Resource Metadata
Continuing my review notes from section 3.2:
1. Section 3.2 paragraph 2 says "Claims that return multiple values are
represented as JSON arrays." should this be "MUST be represented as JSON
arrays"? "Are" is probably OK because it is a statement of fact, but since this
spec will be used by implementers, "MUST be" is more prescriptive
An IETF veteran explained to me a long time ago that declarative English
sentences are just as normative as those using RFC 2119 terms such as MUST. In
fact, it’s possible to write an RFC using none of them!
And this is language also present in RFC 8414.
1. Section 3.2: Is there any ordering condition to multi-valued claims? I.e.
A client MUST / SHOULD try to use the smallest indexed value of a multi-valued
claim and if that is unsuccessful, then use the next smallest indexed value? I
don't know if this matters. If not, should we clarify that clients MAY use any
subset of values?
The semantics of metadata values are specific to the metadata parameter
definition. We would be overreaching to intrude into the semantics defined for
the parameters.
1. Section 3.2 example: Not having "scopes_supported" in the example is a
miss I think, although it does not affect the correctness of the document
I’ve added scopes_supported to the example. Thanks for the suggestion.
1. Section 4 protected_resources: "would not be used" is ambiguous. Can we
say "MUST NOT be present in the Authorization Server Metadata"?
I’ve updated the language to “will not be present”.
1. Section 5. Step 4 should read "The resource server responds with..."
Corrected
1. Section 5.1: Does this introduce any IANA consideration? How would we
know if some other spec is not using "resource_metadata" in some other way in
the WWW-Authenticate response header? (Unlikely, but if there is a way to
reserve it, we should)
The IANA registrations will occur once the spec has completed WGLC and
publication is requested. That said, I’m not aware of a registry for
WWW-Authenticate values. (If anyone is aware of such a registry, please let me
know and I’ll add a registration.)
1. Section 5.2: "...it is expected retrieve..." has a typo, should be
"expected to retrieve". The language can also be more normative: "...The client
SHOULD retrieve..."
Updated
1. Section 5.3: Do we need this section? The spec doesn't use "Client
Identifier" anywhere, so the section may not be needed in this spec.
It’s a fair question. But as I see it, this section goes to the heart of the
use cases that Aaron brought to the table – where client has no prior knowledge
about the resource server. Unless you believe that it’s incorrect in some way,
it seems prudent to retain it.
-- Review completed.
Atul
Thanks so much again,
-- Mike
On Wed, Mar 27, 2024 at 12:00 PM Atul Tulshibagwale
<a...@sgnl.ai<mailto:a...@sgnl.ai>> wrote:
Hi all,
I'd committed to reviewing the draft at IETF 119, so here is my feedback up to
section 3.1:
1. Section 1: The sentence "Each protected resource publishing metadata
about itself makes its own metadata document available at a well-known location
rooted at the protect resource's URL, even when the resource server implements
multiple protected resources." has two issues:
* Typo: "protected resource's URL" instead of "protect resource's URL"
* This contradicts the statement in section 3, which states the
"well-known" should be inserted between the host and path components
1. Section 1: The sentence "The means by which the client obtains the
location of the protected resource metadata document is out of scope" conflicts
with Section 3, which says "Protected resources MUST make ... (it) available at
a path ...".
2. Section 2, "authorization_servers": since this is normative language,
instead of saying "Protected resources MAY choose not to advertise some
supported authorization servers even when this parameter is used.", should we
say "the list of OAuth authorization servers MAY be a subset of the
authorization servers supported by the protected resource."
3. Section 3, paragraph 1: The last sentence, i.e. "The well-known URI path
suffix used MUST be registered in the IANA "Well-Known URIs" registry" is a bit
confusing. Should it say something like "If not using the default well-known
URI, such URI path suffix MUST be registered..." This last sentence of
paragraph 1 can actually be dropped, and the first sentence in the 2nd
paragraph can be updated to refer to the IANA well-known registry.
4. Section 3, paragraph 2: The first sentence should capitalize "MAY" in
"...application-specific ways may define and register..."
5. Section 3, paragraph 2: The first sentence can drop the word "used" here:
"...URI path suffixes used to publish..." The sentence will make more sense
with that word dropped.
6. Section 3, paragraph 2: The last sentence is additional non-normative
language, and could be removed, or could be moved to the "IANA Considerations"
section
7. Section 3, paragraph 3: "...specify what well-known URI string..." should
be changed to "...specify what well-known URI path-suffix..."
8. Section 3, paragraph 3: Instead of saying "...publish its metadata at
multiple well-known locations'', should we say "...publish its metadata using
multiple well-known path-suffixes''?
9. Section 3.1, last paragraph: The sentence "This is required in some
multi-tenant hosting configurations" may be removed as it is not the only
situation in which a host may have multiple OPRM documents.
I will continue the review but I wanted to update the WG on my review so far.
Atul
On Wed, Mar 27, 2024 at 5:54 AM Rifaat Shekh-Yusef
<rifaat.s.i...@gmail.com<mailto:rifaat.s.i...@gmail.com>> wrote:
All,
This is a WG Last Call for the OAuth 2.0 Protected Resource Metadata document.
https://www.ietf.org/archive/id/draft-ietf-oauth-resource-metadata-03.html
Please, review this document and reply on the mailing list if you have any
comments or concerns, by April 12.
Regards,
Rifaat & Hannes
_______________________________________________
OAuth mailing list
OAuth@ietf.org<mailto:OAuth@ietf.org>
https://www.ietf.org/mailman/listinfo/oauth
_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth
