Re: [auth48] AUTH48: RFC-to-be 9560 <draft-ietf-regext-rdap-openid-27> for your review

[[e-mail]]

Authors,

While reviewing this document during AUTH48, please resolve (as necessary) the following questions, which are also in the XML file.

1) <!-- [rfced] To improve readability, would you like these sentences to be
formatted more like a list?

Original:
   This document uses the terms "client" and "server" as defined by RDAP
   [RFC7480].

   This document uses the terms "Access Token", "Authorization Code",
   "Authorization Endpoint", "Authorization Grant", "Client
   Authentication", "Client Identifier", "Protected Resource", "Refresh
   Token", "Resource Owner", "Resource Server", 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)
   [RFC7519]; the terms "ID Token" and "UserInfo Endpoint" defined by
   OpenID Connect Core 1.0 [OIDCC]; and the term "JWT Access Token"
   defined by RFC 9068 [RFC9068]. 

Perhaps:
   This document uses the following terminology.

   Terms defined by [RFC7480]:

     *  client
     *  server
 
   Terms defined by [RFC6749]:

     *  Access Token
     *  Authorization Code
     *  Authorization Endpoint
     *  Authorization Grant
     *  Client Authentication
     *  Client Identifier
     *  Protected Resource
     *  Refresh Token
     *  Resource Owner
     *  Resource Server
     *  Token Endpoint

   Terms defined by [RFC7519]:

     *  Claim Name
     *  Claim Value
     *  JSON Web Token (JWT)

   Terms defined by [OIDCC]:

     *  ID Token
     *  UserInfo Endpoint
 
   Term defined by [RFC9068]:

     *  JWT Access Token
-->


2) <!--[rfced] As "capabilities" is plural, should "type" also be made plural?
Note that this sentence occurs twice in Section 3.1.3.

Original:
   An RDAP client sends an RDAP "help" query to an RDAP server to
   determine the type and capabilities of the OpenID Providers that
   are used by the RDAP server.

Perhaps:
   An RDAP client sends an RDAP "help" query to an RDAP server to
   determine the types and capabilities of the OpenID Providers that
   are used by the RDAP server.
-->   


3) <!-- [rfced] We suggest updating Sections 4.1 and 5.1.1 to use definition
lists <dl> instead of ordered lists <ol> because each item is in the form
of term and definition. Please let us know if this is acceptable.
-->


4) <!-- [rfced] Please review each artwork element in the xml file. Specifically,
should any artwork element be tagged as sourcecode or another element?

Additionally, please review the "type" attribute for the sourcecode elements
in the XML file and let us know if any further changes are needed. If the
current list of preferred values for "type" (https://www.rfc-editor.org/materials/sourcecode-types.txt) does not contain
an applicable type, then feel free to suggest a new one.  Also, it is acceptable to leave the "type" attribute not set.
-->


5) <!-- [rfced] FYI - In Section 5.1, we updated the following paragraph to a definition list, which matches the definition list in Section 4.2. Please
let us know if there are any objections.

Original:
   This specification describes two new data structures that are used to
   return information to a session-oriented client: a "farv1_session"
   data structure that contains information that describes an
   established session, and a "farv1_deviceInfo" data structure that
   contains information that describes an active attempt to establish a
   session on a UI-constrained device.

Current:
   This specification describes two new data structures that are used to
   return information to a session-oriented client:

   "farv1_session":  A data structure that contains information that
      describes an established session.
   "farv1_deviceInfo":  A data structure that contains information that
      describes an active attempt to establish a session on a UI-
      constrained device.
-->


6) <!-- [rfced] FYI - In Sections 5.2.1, 5.2.2, 5.2.4.1, and 5.2.4.2, we moved
the instances of "NOTE:" regarding line wrapping into the artwork to match
RFC 8792.
-->


7) <!-- [rfced] Should the following lines also appear within the <artwork>
element to match the examples in Sections 5.2.1 and 5.2.2?

Section 4.2.1:
   https://example.com/rdap/domain/example.com?farv1_qp=legalActions

Section 4.2.2
   https://example.com/rdap/domain/example.com?farv1_dnt=true

Section 5.2.1:
   https://example.com/rdap/farv1_session/login
   ...
   https://example.com/rdap/farv1_session/login

Section 5.3:
   https://example.com/rdap/farv1_session/status

Section 5.4:
   https://example.com/rdap/farv1_session/refresh

Section 5.5:
   https://example.com/rdap/farv1_session/logout
-->


8) <!-- [rfced] To match common usage, would you like to update "smart telephone"
to "smartphone"?

Original:
   This method requires an End-User to use a
   second device (such as a smart telephone) that has access to a web
   browser for entry of a code sequence that is presented on the UI-
   constrained device.
-->


9) <!--[rfced] Would using a list improve the readability of this text?

Original:
   The requests described in this document are typically performed in a
   specific sequence: "farv1_session/login" (or the related
   "farv1_session/device" and "farv1_session/devicepoll" requests) to
   start a session, "farv1_session/status" and/or "farv1_session/
   refresh" to manage a session, and "farv1_session/logout" to end a
   session.

Perhaps:
   The requests described in this document are typically performed in a
   specific sequence:

   1.  "farv1_session/login" (or the related "farv1_session/device" and
       "farv1_session/devicepoll" requests) to start a session,

   2. "farv1_session/status" and/or "farv1_session/refresh" to manage a
      session, and

   3. "farv1_session/logout" to end a session.
-->   


10) <!--[rfced] IANA Considerations

A) Since the Value and Description columns are defined in Section 9.3
for the "Registration Data Access Protocol (RDAP) Query Purpose Values"
registry, should a definition for the Reference column also be
included? And should "Reference: RFC 9560" be added to each entry to
match the registry?

B) To make the Description of domainNameControl more concise, may we 
update it as follows?

Original:
   Value: domainNameControl

   Description: Tasks within the scope of this purpose include
   creating and managing and monitoring a registrant's own domain
   name, including creating the domain name, updating information
   about the domain name, transferring the domain name, renewing the
   domain name, deleting the domain name, maintaining a domain name
   portfolio, and detecting fraudulent use of the Registrant's own
   contact information.

Perhaps:
   Value: domainNameControl

   Description: Tasks within the scope of this purpose include, for a
   registrant's own domain name, creating the domain name, updating
   information about the domain name, transferring the domain name,
   renewing the domain name, deleting the domain name, maintaining a
   domain name portfolio, and detecting fraudulent use of the
   registrant's own contact information.

C) To reflect the verbiage of other Descriptions in the "Registration Data Access Protocol (RDAP) Query Purpose Values" registry, may we update
the Description of regulatoryAndContractEnforcement as follows?

Original:
   Value: regulatoryAndContractEnforcement

   Description: Tasks within the scope of this purpose include tax
   authority investigation of businesses with online presence,
   Uniform Dispute Resolution Policy (UDRP) investigation,
   contractual compliance investigation, and registration data escrow
   audits.

Perhaps:
   Value: regulatoryAndContractEnforcement

   Description: Tasks within the scope of this purpose include
   investigating the tax authority of businesses with online presences,
   investigating Uniform Domain-Name Dispute-Resolution Policy (UDRP),
   investigating contractual compliance, and registering data escrow
   audits.
-->


11) <!--[rfced] Instead of using a link, may we update this sentence to use
a citation and add a reference entry to the Informative References 
section?

Original:
   The set of initial values used to populate the registry as described
   here are taken from the final report
   (https://www.icann.org/en/system/files/files/final-report-
   06jun14-en.pdf) produced by the Expert Working Group on gTLD
   Directory Services chartered by the Internet Corporation for Assigned
   Names and Numbers (ICANN).

Perhaps:
   The set of initial values used to populate the registry as described
   below are taken from the final report produced by the Expert Working
   Group on gTLD Directory Services chartered by the Internet Corporation
   for Assigned Names and Numbers (ICANN) [gTLD].
   ...
   [gTLD]    Expert Working Group on gTLD Directory Services (EWG), "Final
             Report from the Expert Working Group on gTLD Directory Services:
	     A Next-Generation Registration Directory Service (RDS)", June
	     2014, <https://www.icann.org/en/system/files/files/final-report-
	     06jun14-en.pdf>.   
-->


12) <!-- [rfced] References

A) The following OpenID Connect references appear to have been
superseded by 2023 versions. As we were unable to find URLs to the
previous versions, we have updated them to reflect the most current
versions. 

Original:
   [OIDCC]    OpenID Foundation, "OpenID Connect Core incorporating
              errata set 1", November 2014,
              <https://openid.net/specs/openid-connect-core-1_0.html>.
	      
Current:
   [OIDCC]    Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
              C. Mortimore, "OpenID Connect Core 1.0 incorporating
              errata set 2", December 2023,
              <https://openid.net/specs/openid-connect-core-1_0.html>.
...
Original:
   [OIDCD]    OpenID Foundation, "OpenID Connect Discovery 1.0
              incorporating errata set 1", November 2014,
              <https://openid.net/specs/openid-connect-discovery-
              1_0.html>.

Current:
   [OIDCD]    Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
              Connect Discovery 1.0 incorporating errata set 2",
              December 2023, <https://openid.net/specs/openid-connect-
              discovery-1_0.html>.
...
Original:
   [OIDCR]    OpenID Foundation, "OpenID Connect Dynamic Client
              Registration 1.0 incorporating errata set 1", November
              2014, <https://openid.net/specs/openid-connect-
              registration-1_0.html>.

Current:
   [OIDCR]    Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect
              Dynamic Client Registration 1.0 incorporating errata set
              2", December 2023, <https://openid.net/specs/openid-
              connect-registration-1_0.html>.


B) As the "application/x-www-form-urlencoded" section is mentioned
within the body of the document when [HTMLURL] is cited, we have
updated the URL of this reference to link to the whole document
rather than the specific section.

Original:
   [HTMLURL]  Web Hypertext Application Technology Working Group
              (WHATWG), "URL (Living Standard)", September 2023,
              <https://url.spec.whatwg.org/#application/x-www-form-
              urlencoded>.

Current:

   [HTMLURL]  WHATWG, "URL (Living Standard)", March 2024,
              <https://url.spec.whatwg.org/>.
-->


13) <!-- [rfced] Throughout the text, when citing non-RFC section numbers,
the formats somewhat vary. For simplicity, would you like to update all
instances to the following format to match how RFCs are referenced? Note
that we haven't included every example below.

Current:
   the "application/x-www-form-urlencoded" section of 
   WHATWG URL Standard [HTMLURL]
   ...
   Section 5 of the OpenID Connect Core protocol [OIDCC]
   
Perhaps:
   Section "application/x-www-form-urlencoded" of 
   [HTMLURL]
   ...
   Section 5 of [OIDCC]
-->


14) <!-- [rfced] Terminology

A) The following terms are capitalized in the text but are lowercase in the
corresponding cited RFCs. Should these be made lowercase to match the
corresponding RFCs?

Lowercase in RFC 6749:
   Access Token
   Authorization Code
   Authorization Code Flow
   Authorization Endpoint
   Authorization Grant
   Token Endpoint
   Token Request
   Token Response

Lowercase in RFC 6750:
   "Bearer" authentication scheme

Lowercase in RFC 8628 and only hyphenated when in attributive position (i.e.,
when followed by a noun):
  End User

Lowercase in RFC 9068:
   JWT Access Token

Additionally, should "Authorization Request" also be made lowercase to 
parallel usage in other previously published RFCs?


B) The following terms appear to be used inconsistently throughout the
document. Should they be made lowercase for consistency and to match
the corresponding cited RFCs?

Lowercase in RFC 6749:
   Client Authentication vs. client authentication
   Client Identifier vs. client identifier
   Protected Resource vs. protected resource
   Refresh Token vs. refresh token
   Resource Owner vs. resource owner
   Resource Server vs. resource server

Lowercase in RFC 6750:
   "Authorization" header vs. authorization header
   
Not consistently capitalized in RFC 7519:
   Claim Value vs. claim value


C) Throughout the text, the following terminology appears to be used
inconsistently. May we update to the version on the right to match more
common usage?

   Identity Provider > identity provider
   issuer identifier > Issuer Identifier
   RDAP Client > RDAP client
   RDAP Server > RDAP server
   End-User Identifier > end-user identifier


D) Might it be helpful to the reader to clarify the slash in cases like
the following (i.e., does it stand for "and", "or", or "and/or")? Note that
this appears in several places; the following is just an example.

Original:
   An RDAP server/RP needs to be able to map an End-User's identifier to
   an OP.  

Perhaps:
   An RDAP server or RP needs to be able to map an End-User's identifier 
   to an OP.


E) We see "farv1" expanded two different ways. May we update both instances to
the following to be consistent?

Current:
   Federated Authentication for RDAP version 1
   ...
   version 1 of a federated authentication method for RDAP

Perhaps:
   federated authentication method for RDAP version 1 

F) FYI - To match the OpenID Connect Core 1.0 reference, we updated one
instance of "ID token" to "ID Token". Please let us know if there is any
objection.
-->


15) <!--[rfced] Acronyms

A) FYI - We have added expansions for abbreviations upon first use
per Section 3.6 of RFC 7322 ("RFC Style Guide"). Please review each
expansion in the document carefully to ensure correctness.

Representational State Transfer (RESTful)


B) For the term "OpenID Provider", may we update the first instance to be
"OpenID Provider (OP)" and all subsequent instance to "OP"?
-->


16) <!--[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.

Note that our script did not flag any words in particular, but this should 
still be reviewed as a best practice.
-->


Thank you.

RFC Editor/st/ap


On Apr 5, 2024, at 2:51 PM, [e-mail] wrote:

*****IMPORTANT*****

Updated 2024/04/05

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
   
   *  [e-mail] (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).
     
   *  [e-mail], 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, 
        [e-mail] 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/rfc9560.xml
   https://www.rfc-editor.org/authors/rfc9560.html
   https://www.rfc-editor.org/authors/rfc9560.pdf
   https://www.rfc-editor.org/authors/rfc9560.txt

Diff file of the text:
   https://www.rfc-editor.org/authors/rfc9560-diff.html
   https://www.rfc-editor.org/authors/rfc9560-rfcdiff.html (side by side)

Diff of the XML: 
   https://www.rfc-editor.org/authors/rfc9560-xmldiff1.html

The following files are provided to facilitate creation of your own 
diff files of the XML.  

Initial XMLv3 created using XMLv2 as input:
   https://www.rfc-editor.org/authors/rfc9560.original.v2v3.xml 

XMLv3 file that is a best effort to capture v3-related format updates 
only: 
   https://www.rfc-editor.org/authors/rfc9560.form.xml


Tracking progress
-----------------

The details of the AUTH48 status of your document are here:
   https://www.rfc-editor.org/auth48/rfc9560

Please let us know if you have any questions.  

Thank you for your cooperation,

RFC Editor

--------------------------------------
RFC9560 (draft-ietf-regext-rdap-openid-27)

Title            : Federated Authentication for the Registration Data Access Protocol (RDAP) using OpenID Connect
Author(s)        : S. Hollenbeck
WG Chair(s)      : James Galvin, Antoin Verschuren

Area Director(s) : Murray Kucherawy, Orie Steele