OAuth 2.0 Authorization Server Metadata
draft-ietf-oauth-discovery-07

[Ballot comment]
A couple broad comments before getting into the section-by-section
details:

I'm a little unclear on the value gained by having RELTYPE=REFID and
RELTYPE=CONCEPT.  If the semantics were just supposed to be "is a member
of the indicated group", then why do we need a relation type to say so.
But if there's some other semantics associated, where do we define those
semantics?

There are a number of places (e.g., §1.4) where this document uses the
term "collection" in a context that suggests that it should be a defined
term of iCalendar, corresponding roughly to a "site" or administrative
domain, but I didn't find any usage in RFC 5545 that would correspond to
what's being described here.  Can we say more about what level of grouping
this is intended to refer to?

Section 1.1

   The iCalendar [RFC5545] RELATED-TO property has no support for
   temporal relationships as used by standard project management tools.

I am admittedly not really the target audience of this specification, but
I have no idea what the "standard project management tools" are that are
being referred to.  Would (informative) references to a handful be
appropriate?

Section 1.2

   REFID is used to identify a key allowing the association of
   components that are related to the same object and retrieval of a
   component based on this key.  [...]

This says "related to the same *object*" (emphasis mine), but the rest of
the section just talks about an unstructured grouping.  It seems like we
could give some hint of the nature of the "object" to which all the
elements of the group are related, prior to the RELTYPE=REFID definition
in §5.

Section 1.3

   The current [RFC5545] CATEGORY property is used as a free form
   'tagging' field.  [...]

In light of the discussion in the previous section about grouping without
semantics, we might consider mentioning here that this is "tagging with
semantics", just vaguely defined ones, as opposed to the REFID-type
"tagging without semantics".

Section 1.4

   server-side management and stripping of inline data.  Clients may
   choose to handle attachments differently from the LINK property as
   they are often an integral part of the message - for example, the
   agenda.

(See the NITS entries as well, but) is it particularly noteworthy that
clients might handle LINKs different from ATTACHments?  They are different
properties after all -- why would someone assume equivalent treatment?

Section 1.5

   To facilitate offline display the link type may identify important
   pieces of data which should be downloaded in advance.

   In general, the calendar entity should be self explanatory without
   the need to download referenced meta-data such as a web page.

I'm not sure how to relate these two statements.  It sounds like a "
may happen, but in general don't do " scenario, in which case it might
flow better to give the general advice first, followed by the specific
scenario in which there is an exception to the general guidance.

Section 2

   The actual reference value can take three forms specified by the type
   parameter

Is this list fixed for eternity or do we want to give some guidance that
implementations need to prepare for future extensibility?

   REFERENCE:  In an XML environment it may be necessary to refer to a

This qualification in the description ("XML environment") suggests that
perhaps the name being used for these semantics is an overly generic name.

Section 4

We do have some text here about the GAP parameter that specifies the lead
or lag time here, but then we go on to describe the various RELTYPE values
in language like "cannot start until", "can only be completed after",
etc., that is very absolute and does not acknowledge the potential for a
GAP.  I think it would be helpful to reframe as that we are making a
comparison between the indicated pair of events, and that the relationship
between when the events occur is affected by the GAP interval.
(Also, the text in this section on the GAP parameter doesn't give a great
sense that the lead time would be a negative gap.)

Section 5

   RELTYPE=FIRST:  Indicates that the referenced calendar component is
      the first in a series the referenced calendar component is part
      of.

I wonder if we want to explicitly contrast this with PARENT and provide an
example of them being different.

Section 6.1

      In addition to the values defined here any value defined in
      [RFC8288] may be used.  However these uses SHOULD be documented in
      an RFC updating both [RFC5545] and [RFC8288]

In some sense this feels a little like saying "the current document SHOULD
have documented this stuff, but we didn't".  Is there anything useful to
say about why this documenting can't be done now?  (Oh, I guess there are
rather more values in the registry than I remembered, though the number of
them actually defined in RFC 8288 Jones, et al.            Expires March 11, 2018                [Page 17]
Internet-Draft   OAuth 2.0 Authorization Server Metadata  September 2017

7.3.  Well-Known URI Registry

   This specification registers the well-known URI defined in Section 3
   in the IANA "Well-Known URIs" registry [IANA.well-known] established
   by RFC 5785 [RFC5785].

7.3.1.  Registry Contents

   o  URI suffix: "oauth-authorization-server"
   o  Change controller: IESG
   o  Specification document: Section 3 of [[ this specification ]]
   o  Related information: (none)

8.  References

8.1.  Normative References

   [BCP195]   Sheffer, Y., Holz, R., and P. Saint-Andre,
              "Recommendations for Secure Use of Transport Layer
              Security (TLS) and Datagram Transport Layer Security
              (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
              2015, <http://www.rfc-editor.org/info/bcp195>.

   [IANA.OAuth.Parameters]
              IANA, "OAuth Parameters",
              <http://www.iana.org/assignments/oauth-parameters>.

   [JWE]      Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
              RFC 7516, DOI 10.17487/RFC7516, May 2015,
              <http://tools.ietf.org/html/rfc7516>.

   [JWK]      Jones, M., "JSON Web Key (JWK)", RFC 7517,
              DOI 10.17487/RFC7517, May 2015,
              <http://tools.ietf.org/html/rfc7517>.

   [JWS]      Jones, M., Bradley, J., and N. Sakimura, "JSON Web
              Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
              2015, <http://tools.ietf.org/html/rfc7515>.

   [JWT]      Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
              <http://tools.ietf.org/html/rfc7519>.

   [OAuth.Post]
              Jones, M. and B. Campbell, "OAuth 2.0 Form Post Response
              Mode", April 2015, <http://openid.net/specs/
              oauth-v2-form-post-response-mode-1_0.html>.

Jones, et al.            Expires March 11, 2018                [Page 18]
Internet-Draft   OAuth 2.0 Authorization Server Metadata  September 2017

   [OAuth.Responses]
              de Medeiros, B., Ed., Scurtescu, M., Tarjan, P., and M.
              Jones, "OAuth 2.0 Multiple Response Type Encoding
              Practices", February 2014, <http://openid.net/specs/
              oauth-v2-multiple-response-types-1_0.html>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", RFC 5226,
              DOI 10.17487/RFC5226, May 2008,
              <https://www.rfc-editor.org/info/rfc5226>.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246,
              DOI 10.17487/RFC5246, August 2008,
              <https://www.rfc-editor.org/info/rfc5246>.

   [RFC5646]  Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
              Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
              September 2009, <https://www.rfc-editor.org/info/rfc5646>.

   [RFC5785]  Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
              Uniform Resource Identifiers (URIs)", RFC 5785,
              DOI 10.17487/RFC5785, April 2010,
              <https://www.rfc-editor.org/info/rfc5785>.

   [RFC6125]  Saint-Andre, P. and J. Hodges, "Representation and
              Verification of Domain-Based Application Service Identity
              within Internet Public Key Infrastructure Using X.509
              (PKIX) Certificates in the Context of Transport Layer
              Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March
              2011, <https://www.rfc-editor.org/info/rfc6125>.

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,
              <https://www.rfc-editor.org/info/rfc6749>.

   [RFC7009]  Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth
              2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009,
              August 2013, <https://www.rfc-editor.org/info/rfc7009>.

   [RFC7033]  Jones, P., Salgueiro, G., Jones, M., and J. Smarr,
              "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September
              2013, <https://www.rfc-editor.org/info/rfc7033>.

Jones, et al.            Expires March 11, 2018                [Page 19]
Internet-Draft   OAuth 2.0 Authorization Server Metadata  September 2017

   [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <https://www.rfc-editor.org/info/rfc7159>.

   [RFC7591]  Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and
              P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
              RFC 7591, DOI 10.17487/RFC7591, July 2015,
              <https://www.rfc-editor.org/info/rfc7591>.

   [RFC7636]  Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key
              for Code Exchange by OAuth Public Clients", RFC 7636,
              DOI 10.17487/RFC7636, September 2015,
              <https://www.rfc-editor.org/info/rfc7636>.

   [RFC7662]  Richer, J., Ed., "OAuth 2.0 Token Introspection",
              RFC 7662, DOI 10.17487/RFC7662, October 2015,
              <https://www.rfc-editor.org/info/rfc7662>.

   [UNICODE]  The Unicode Consortium, "The Unicode Standard",
              <http://www.unicode.org/versions/latest/>.

   [USA15]    Davis, M. and K. Whistler, "Unicode Normalization Forms",
              Unicode Standard Annex 15, June 2015,
              <http://www.unicode.org/reports/tr15/>.

8.2.  Informative References

   [I-D.ietf-oauth-mix-up-mitigation]
              Jones, M., Bradley, J., and N. Sakimura, "OAuth 2.0 Mix-Up
              Mitigation", draft-ietf-oauth-mix-up-mitigation-01 (work
              in progress), July 2016.

   [IANA.well-known]
              IANA, "Well-Known URIs",
              <http://www.iana.org/assignments/well-known-uris>.

   [OpenID.Core]
              Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
              C. Mortimore, "OpenID Connect Core 1.0", November 2014,
              <http://openid.net/specs/openid-connect-core-1_0.html>.

   [OpenID.Discovery]
              Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
              Connect Discovery 1.0", November 2014,
              <http://openid.net/specs/
              openid-connect-discovery-1_0.html>.

Jones, et al.            Expires March 11, 2018                [Page 20]
Internet-Draft   OAuth 2.0 Authorization Server Metadata  September 2017

   [OpenID.Registration]
              Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect
              Dynamic Client Registration 1.0", November 2014,
              <http://openid.net/specs/
              openid-connect-registration-1_0.html>.

Appendix A.  Acknowledgements

   This specification is based on the OpenID Connect Discovery 1.0
   specification, which was produced by the OpenID Connect working group
   of the OpenID Foundation.

   The authors would like to thank the following people for their
   reviews of this specification: Brian Campbell, William Denniss,
   Vladimir Dzhuvinov, Samuel Erdtman, George Fletcher, Phil Hunt, Tony
   Nadalin, Eric Rescorla, Justin Richer, Hannes Tschofenig, and Hans
   Zandbelt.

Appendix B.  Document History

   [[ to be removed by the RFC Editor before publication as an RFC ]]

   -07

   o  Applied clarifications suggested by EKR.

   -06

   o  Incorporated resolutions to working group last call comments.

   -05

   o  Removed the "protected_resources" element and the reference to
      draft-jones-oauth-resource-metadata.

   -04

   o  Added the ability to list protected resources with the
      "protected_resources" element.

   o  Added ability to provide signed metadata with the
      "signed_metadata" element.

   o  Removed "Discovery" from the name, since this is now just about
      authorization server metadata.

   -03

Jones, et al.            Expires March 11, 2018                [Page 21]
Internet-Draft   OAuth 2.0 Authorization Server Metadata  September 2017

   o  Changed term "issuer URL" to "issuer identifier" for terminology
      consistency, paralleling the same terminology consistency change
      in the mix-up mitigation spec.

   -02

   o  Changed the title to OAuth 2.0 Authorization Server Discovery
      Metadata.

   o  Made "jwks_uri" and "registration_endpoint" OPTIONAL.

   o  Defined the well-known URI string "/.well-known/oauth-
      authorization-server".

   o  Added security considerations about publishing authorization
      server discovery metadata in a standard format.

   o  Added security considerations about protected resources.

   o  Added more information to the "grant_types_supported" and
      "response_types_supported" definitions.

   o  Referenced the working group Mix-Up Mitigation draft.

   o  Changed some example metadata values.

   o  Acknowledged individuals for their contributions to the
      specification.

   -01

   o  Removed WebFinger discovery.

   o  Clarified the relationship between the issuer identifier URL and
      the well-known URI path relative to it at which the discovery
      metadata document is located.

   -00

   o  Created the initial working group version based on draft-jones-
      oauth-discovery-01, with no normative changes.

Authors' Addresses

Jones, et al.            Expires March 11, 2018                [Page 22]
Internet-Draft   OAuth 2.0 Authorization Server Metadata  September 2017

   Michael B. Jones
   Microsoft

   Email: mbj@microsoft.com
   URI:   http://self-issued.info/

   Nat Sakimura
   Nomura Research Institute, Ltd.

   Email: n-sakimura@nri.co.jp
   URI:   http://nat.sakimura.org/

   John Bradley
   Ping Identity

   Email: ve7jtb@ve7jtb.com
   URI:   http://www.thread-safe.com/

Jones, et al.            Expires March 11, 2018                [Page 23]