[OAUTH-WG] Re: Opsdir last call review of draft-ietf-oauth-resource-metadata-08

[Michael Jones <[e-mail]>]

Thanks for your review, Bo.  My replies are inline below, prefixed by "Mike>".

-----Original Message-----
From: Bo Wu via Datatracker <[e-mail]> 
Sent: Thursday, August 29, 2024 5:53 AM
To: [e-mail]
Cc: [e-mail]; [e-mail]; [e-mail]
Subject: Opsdir last call review of draft-ietf-oauth-resource-metadata-08

Reviewer: Bo Wu
Review result: Has Nits

Hi,

I'm the assigned Ops reviewer. I think this document is ready with nits.

Here are some nits and questions:

nits:

1)
The Figure 1 Sequence Diagram does not seem to match the text in the steps.
For example, step 5 in the diagram corresponds to step 5 and the first half of step 6 in the text description, and there is no "user agent" (step 8) in the diagram. Therefore, it is recommended that sequence numbers be added to the diagram.

Mike> I'll plan to work with Aaron Parecki to add numbers to the diagram, if possible.  (It may be tricky, because there are both SVG https://drafts.oauth.net/draft-ietf-oauth-resource-metadata/draft-ietf-oauth-resource-metadata.html#name-sequence-diagram and ASCII ART https://www.ietf.org/archive/id/draft-ietf-oauth-resource-metadata-08.txt versions of the diagram.)  This issue is tracked at https://github.com/oauth-wg/draft-ietf-oauth-resource-metadata/issues/49.

2)
s/The resource value returned/The "resource" value returned

Mike> In both cases, the word "resource" is in a fixed-width font as a result of denoting it as <spanx style="verb">resource</spanx> in the XML source (which will be transformed to <tt>resource</tt> in the XML2RFC v3 source) to mark it as being a protocol element.  In xml2rfc v1 this would have resulted a fixed width font in the HTML output and "resource" in the .txt output, but the newer tooling omits the double quotes in the .txt output for some reason.  I'm prone to go with the choices made by the IETF's tooling and not manually add the double quotes.

3)
s/specific member names such as resource/specific member names such as "resource"

Mike> Same situation.  "resource" here is already in a fixed-width font because its source is <spanx style="verb">resource</spanx>.

Some questions:

1)

Section 1 Introduction

 The metadata for a protected resource is retrieved from a well-known
   location as a JSON [RFC8259] document, which declares information
   about its capabilities and optionally, its relationships to other
   services.

Do other services refer to authorization servers? If yes, then it is recommended to use authorization servers directly.

Mike> Yes, the metadata for Authorization Servers is also retrieved from a well-known URL, as described at https://www.rfc-editor.org/rfc/rfc8414.html#section-3.  This specification follows that pattern.  The "authorization_servers" value is a set of AS issuer identifiers, as defined in RFC 8414.  That enables retrieving their metadata in that way.

2)
Section 1 Introduction

The means by which the client obtains the location of the protected resource is out of scope. In some cases, the location may be manually configured into the client.

In Section 5.3, there is also text：

   This specification is intended to be deployed in scenarios where the
   client has no prior knowledge about the resource server,

It seems that text in Introduction means that the resource server is prior knowledge of the client if I understand correctly. Am I correct?

Mike> Actually, the client may learn about the resource server at runtime as a result of user interface actions by the person using the client.  The client might be, for instance, an e-mail reader and the resource might be an e-mail server.  The client can be pointed at any of thousands of e-mail servers worldwide, which would be the resources.

Aaron Parecki did a good job explaining that motivating use case several IETFs ago.  I'll try to dig that up and we'll consider describing it in the draft.

3)

 Section 1.2. Terminology

 Resource Identifier:

The Protected resource's resource identifier, which is a URL that uses the https scheme and has no query or fragment components.
Protected resource metadata is published at a .well-known location [RFC8615] derived from this resource identifier, as described in Section 3.

resource
REQUIRED. The protected resource's resource identifier, which is a URL that uses the https scheme and has no query or fragment components. Using these well-known resources is described in Section 3.

The two descriptions look almost same. Perhaps the reference of the definition can be used, for example:

 Resource Identifier:
The Protected resource's resource identifier, which is a URL (see Section 2).

Mike> I agree that adding the reference makes sense.

4)

Section 5.3 Client Identifier and Client Authentication

There are some existing methods by which an unrecognized client can make use of an authorization server, such as using Dynamic Client Registration [RFC7591] to register the client prior to initiating the authorization flow. Future extensions might define alternatives, such as using URLs to identify clients.

On “Future extensions",does this mean the extensions of RFC 7591?

Mike> Good point.  We mean future extensions to OAuth.  I'll clarify in the draft.

Thanks,
Bo Wu

Thanks again for your useful review!

				-- Mike