DATE 2 March 2019 - version -21

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up.

Changes are expected over time. This version is dated 24 February 2012.

(1) Is should be a Proposed Standard and that is reflected in the
meta information.

(2) The IESG approval announcement includes a Document Announcement
Write-Up. Please provide such a Document Announcement Write-Up. Recent
examples can be found in the "Action" announcements for approved
documents. The approval announcement contains the following sections:

Technical Summary

  This document describes a framework for the use of OAuth 2.0
  in a constrained environment.  The document is mainly targeted
  at the protocols defined for CoAP, but other protocols can
  be used as well.  The framework defines the fields and
  symmantics needed for doing authorization and authenticiation
  of a client. 

Working Group Summary

  The concesus on the document wa generally very solid.  There
  were some issues that arose between the ACE and OAuth working
  groups over a couple of issues.  These issues appear to have
  been resolved.

Document Quality

  There have been at least four different groups who have
  announced an implementation at some level of the specification.
  While two of those implementations share a certain amount of
  common code, there are two implementations which have done
  interop tests at various times which do not share any code
  based on this document.

  The scope and issues of trying to deal with some of the
  OAuth 2.0 documents can be challenging at times.  While
  it is believed that a good job has been done, there are
  some potential areas where different people might end up
  doing new things.

Personnel

  Jim Schaad is the Document Shepherd.  Ben Kaduk is the
  responsible AD.

(3) I have done a detailed read a number of times during the WGLC
process and while shepherding to make sure all WGLC comments were
addressed.  Additionally, I have done an implementation of the document
during development.

(4) Between the implentations of the framework that we have and the
healthy discussions during the WGLC, I am confident that there has
been quite broad review of the document.

(5) No broader review should be needed.  During the process there has
been significant review from the OAuth working group.

(6) I have no issues with this specific document.  I do have a problem
with how the registries have been setup in OAuth, but that is not
germane to this document.

(7) All authors have indicated that they do no know of any additional IPR
that needs to be disclosed.
Ludwig  2/25/19
Goren  2/25/19
Erdtman 2/25/19
Hannes  2/27/19

(8) There is an IPR disclosure on this document.  During the shepards review, I specifically requested if there were any concerns about this IPR and none were raised. 

(9) The set of people that have contributed probably represent about a dozen
individuals in the WG.

(10) There has been no extreme discontent expressed during the discussions.

(11) No ID nits are called out.

(12)  The only formal review needed is for a new media type.
The media type request for application/ace+cbor was mailed 23 Feb 2019.

(13) All references are tagged and reasonable.

(14) All of the normative documents which are in process are at the
same stage of development and thus should not cause any issues.

(15) There are no downward normative references.

(16) This document represents the first iteration.  It profiles and extends
some of the OAuth documents, but this is not done by modifications of the
documents themselves.

(17) It was somewhat painful.  I looked at all items that were defined
and should be registered to make sure that they existed in the IANA
considerations.  I compared the registrations of items with the required
templates or columns in the IANA registries.  A detailed walk of the
new registries along with reasonable behavior was examined.

(18) The following new IANA registries are created:

ACE Authorization Server Request Creation Hints -
Contains a set of attributes to be returned from a resource server
that can be used by a client when building the request to the
authorization server.  There is not currently an equivalent registry
for OAuth so it is not clear that an OAuth person is going to be
extremely useful.  Some implementation experience would probably
be useful, but is definitely not required.

OAuth Error Code CBOR Mappings -
Contains a mapping of errors that can be returned in OAuth.  No
special expertise should be required for the experts.

OAuth Grant Type CBOR Mappings -
Contains a mapping of grant types from the OAuth registry to a
CBOR integer.  No special expertise should be required for the
experts.

OAuth Access Token Type CBOR Mapping -
Contains a mapping of token types from the OAuth registry to
a CBOR integer.  No special expertise should be required for
the experts.

ACE Profile -
Contains the set of ACE profiles that use the framework.
The experts should have a solid working knowledge of the framework
as they need to be able to evaluate any new profile against the
framework to make sure that all of the conditions outlined are
fulfilled.

OAuth Parameters CBOR Mapping -
Contains the set of mappings from OAuth parameters to integer
values.  No special expertise should be required for the
experts.

OAuth Token Introspection Response CBOR Mappings -
Contains the mapping of response parameters from the OAuth
registry to a CBOR integer and type.  No special expertise should
be required for the experts.

List any new IANA registries that require Expert Review for future
allocations. Provide any public guidance that the IESG would find
useful in selecting the IANA Experts for these new registries.

(19) No automated checks were done.

DATE 2 March 2019 - version -21

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up.

Changes are expected over time. This version is dated 24 February 2012.

(1) Is should be a Proposed Standard and that is reflected in the
meta information.

(2) The IESG approval announcement includes a Document Announcement
Write-Up. Please provide such a Document Announcement Write-Up. Recent
examples can be found in the "Action" announcements for approved
documents. The approval announcement contains the following sections:

Technical Summary

  This document describes a framework for the use of OAuth 2.0
  in a constrained environment.  The document is mainly targeted
  at the protocols defined for CoAP, but other protocols can
  be used as well.  The framework defines the fields and
  symmantics needed for doing authorization and authenticiation
  of a client. 

Working Group Summary

  The concesus on the document wa generally very solid.  There
  were some issues that arose between the ACE and OAuth working
  groups over a couple of issues.  These issues appear to have
  been resolved.

Document Quality

  There have been at least four different groups who have
  announced an implementation at some level of the specification.
  While two of those implementations share a certain amount of
  common code, there are two implementations which have done
  interop tests at various times which do not share any code
  based on this document.

  The scope and issues of trying to deal with some of the
  OAuth 2.0 documents can be challenging at times.  While
  it is believed that a good job has been done, there are
  some potential areas where different people might end up
  doing new things.

Personnel

  Jim Schaad is the Document Shepherd.  Ben Kaduk is the
  responsible AD.

(3) I have done a detailed read a number of times during the WGLC
process and while shepherding to make sure all WGLC comments were
addressed.  Additionally, I have done an implementation of the document
during development.

(4) Between the implentations of the framework that we have and the
healthy discussions during the WGLC, I am confident that there has
been quite broad review of the document.

(5) No broader review should be needed.  During the process there has
been significant review from the OAuth working group.

(6) I have no issues with this specific document.  I do have a problem
with how the registries have been setup in OAuth, but that is not
germane to this document.

(7) All authors have indicated that they do no know of any additional IPR
that needs to be disclosed.
Ludwig  2/25/19
Goren  2/25/19
Erdtman 2/25/19
Hannes  2/27/19

(8) There is an IPR disclosure on this document.  During the shepards review, I specifically requested if there were any concerns about this IPR and none were raised. 

(9) The set of people that have contributed probably represent about a dozen
individuals in the WG.

(10) There has been no extreme discontent expressed during the discussions.

(11) No ID nits are called out.

(12)  The only formal review needed is for a new media type.
The media type request for application/ace+cbor was mailed 23 Feb 2019.

(13) All references are tagged and reasonable.

(14) All of the normative documents which are in process are at the
same stage of development and thus should not cause any issues.

(15) There are no downward normative references.

(16) This document represents the first iteration.  It profiles and extends
some of the OAuth documents, but this is not done by modifications of the
documents themselves.

(17) It was somewhat painful.  I looked at all items that were defined
and should be registered to make sure that they existed in the IANA
considerations.  I compared the registrations of items with the required
templates or columns in the IANA registries.  A detailed walk of the
new registries along with reasonable behavior was examined.

(18) The following new IANA registries are created:

ACE Authorization Server Request Creation Hints -
Contains a set of attributes to be returned from a resource server
that can be used by a client when building the request to the
authorization server.  There is not currently an equivalent registry
for OAuth so it is not clear that an OAuth person is going to be
extremely useful.  Some implementation experience would probably
be useful, but is definitely not required.

OAuth Error Code CBOR Mappings -
Contains a mapping of errors that can be returned in OAuth.  No
special expertise should be required for the experts.

OAuth Grant Type CBOR Mappings -
Contains a mapping of grant types from the OAuth registry to a
CBOR integer.  No special expertise should be required for the
experts.

OAuth Access Token Type CBOR Mapping -
Contains a mapping of token types from the OAuth registry to
a CBOR integer.  No special expertise should be required for
the experts.

ACE Profile -
Contains the set of ACE profiles that use the framework.
The experts should have a solid working knowledge of the framework
as they need to be able to evaluate any new profile against the
framework to make sure that all of the conditions outlined are
fulfilled.

OAuth Parameters CBOR Mapping -
Contains the set of mappings from OAuth parameters to integer
values.  No special expertise should be required for the
experts.

OAuth Token Introspection Response CBOR Mappings -
Contains the mapping of response parameters from the OAuth
registry to a CBOR integer and type.  No special expertise should
be required for the experts.

List any new IANA registries that require Expert Review for future
allocations. Provide any public guidance that the IESG would find
useful in selecting the IANA Experts for these new registries.

(19) No automated checks were done.

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up.

Changes are expected over time. This version is dated 24 February 2012.

(1)
What type of RFC is being requested (BCP, Proposed Standard,
Internet Standard, Informational, Experimental, or Historic)?  Why
is this the proper type of RFC?  Is this type of RFC indicated in the
title page header?

(2) The IESG approval announcement includes a Document Announcement
Write-Up. Please provide such a Document Announcement Write-Up. Recent
examples can be found in the "Action" announcements for approved
documents. The approval announcement contains the following sections:

Technical Summary

  Relevant content can frequently be found in the abstract
  and/or introduction of the document. If not, this may be
  an indication that there are deficiencies in the abstract
  or introduction.

Working Group Summary

  Was there anything in WG process that is worth noting? For
  example, was there controversy about particular points or
  were there decisions where the consensus was particularly
  rough?

Document Quality

  Are there existing implementations of the protocol? Have a
  significant number of vendors indicated their plan to
  implement the specification? Are there any reviewers that
  merit special mention as having done a thorough review,
  e.g., one that resulted in important changes or a
  conclusion that the document had no substantive issues? If
  there was a MIB Doctor, Media Type or other expert review,
  what was its course (briefly)? In the case of a Media Type
  review, on what date was the request posted?

Personnel

  Who is the Document Shepherd? Who is the Responsible Area
  Director?

(3)
Briefly describe the review of this document that was performed by
the Document Shepherd.  If this version of the document is not ready
for publication, please explain why the document is being forwarded to
the IESG.

(4)
Does the document Shepherd have any concerns about the depth or
breadth of the reviews that have been performed?

(5)
Do portions of the document need review from a particular or from
broader perspective, e.g., security, operational complexity, AAA, DNS,
DHCP, XML, or internationalization? If so, describe the review that
took place.

(6)
Describe any specific concerns or issues that the Document Shepherd
has with this document that the Responsible Area Director and/or the
IESG should be aware of? For example, perhaps he or she is uncomfortable
with certain parts of the document, or has concerns whether there really
is a need for it. In any event, if the WG has discussed those issues and
has indicated that it still wishes to advance the document, detail those
concerns here.

(7)
Has each author confirmed that any and all appropriate IPR
disclosures required for full conformance with the provisions of BCP 78
and BCP 79 have already been filed. If not, explain why.

(8)
Has an IPR disclosure been filed that references this document?
If so, summarize any WG discussion and conclusion regarding the IPR
disclosures.

(9)
How solid is the WG consensus behind this document? Does it
represent the strong concurrence of a few individuals, with others
being silent, or does the WG as a whole understand and agree with it? 

(10)
Has anyone threatened an appeal or otherwise indicated extreme
discontent? If so, please summarise the areas of conflict in separate
email messages to the Responsible Area Director. (It should be in a
separate email because this questionnaire is publicly available.)

(11)
Identify any ID nits the Document Shepherd has found in this
document. (See https://www.ietf.org/tools/idnits/ and the Internet-Drafts
Checklist). Boilerplate checks are not enough; this check needs to be
thorough.

(12)
Describe how the document meets any required formal review
criteria, such as the MIB Doctor, media type, and URI type reviews.

(13)
Have all references within this document been identified as
either normative or informative?

(14)
Are there normative references to documents that are not ready for
advancement or are otherwise in an unclear state? If such normative
references exist, what is the plan for their completion?

(15)
Are there downward normative references references (see RFC 3967)?
If so, list these downward references to support the Area Director in
the Last Call procedure.

(16)
Will publication of this document change the status of any
existing RFCs? Are those RFCs listed on the title page header, listed
in the abstract, and discussed in the introduction? If the RFCs are not
listed in the Abstract and Introduction, explain why, and point to the
part of the document where the relationship of this document to the
other RFCs is discussed. If this information is not in the document,
explain why the WG considers it unnecessary.

(17)
Describe the Document Shepherd's review of the IANA considerations
section, especially with regard to its consistency with the body of the
document. Confirm that all protocol extensions that the document makes
are associated with the appropriate reservations in IANA registries.
Confirm that any referenced IANA registries have been clearly
identified. Confirm that newly created IANA registries include a
detailed specification of the initial contents for the registry, that
allocations procedures for future registrations are defined, and a
reasonable name for the new registry has been suggested (see RFC 5226).

(18) The following new IANA registries are created:

ACE Authorization Server Information -

OAuth Error Code CBOR Mappings -

OAuth Grant Type CBOR Mappings -

Token Type CBOR Mappings -

ACE Profile -

Token Endpoint CBOR Mappings -

Introspection Endpoint CBOR Mappings -

List any new IANA registries that require Expert Review for future
allocations. Provide any public guidance that the IESG would find
useful in selecting the IANA Experts for these new registries.

(19)
Describe reviews and automated checks performed by the Document
Shepherd to validate sections of the document written in a formal
language, such as XML code, BNF rules, MIB definitions, etc.

**************************************************************************

**DONE** Stefanie Gerdes

Ben Kaduk

>
> On 22/10/2018 21:09, Jim Schaad wrote:
> > * Section 5.8.2 - If the RS is going to do introspection, can it send some
> > type of "Server Busy - try again in xxx" while it does the introspection
> > rather than just doing an ack of the request and possibly waiting a long
> > time?
>
> This is probably transport protocol specific, and we were asked not to
> link the framework to a specific protocol, thus I don't know if we can
> provide guidance here.

I think it would be okay to say something like "some transport protocols
may provide a way to indicate that the server is busy and the client should
retry after an interval; this type of status update would be appropriate
while the server is waiting for an introspection response".  Which does
provide guidance, but in a non-normative fashion that does not require or
prohibit any given transport protocol.

Mike Jones:

**IGNORE** IT CAN'T BE A COINCIDENCE:  There's clearly a relationship between many of the CBOR numeric values used in this this specification and corresponding CBOR Web Token (CWT) claim identifiers, but oddly, the relationship is currently unspecified and the goals behind it are undefined.  The spec should be augmented to make the nature and goals of this relationship explicit.  I infer that there's such a relationship because the Mapping Parameters to CBOR in Section 5.6.5 apparently carefully do not overlap with the values registered in the IANA CWT Claims registry at https://www.iana.org/assignments/cwt/cwt.xhtml.  The Introspection mappings in Section 5.7.4 apparently carefully use the same values as CWT for the same things, but then adds additional values.  And some of these values are the same as values proposed for the CWT Claims registry in 8.13.  This has to be more than a coincidence but the spec doesn't currently say why.

Per my earlier reviews of the ace-authz spec, I believe that the ACE OAuth parameters should all be registered in the CWT Claims registry because of the possibility of them being used in signed requests in a manner analogous to https://tools.ietf.org/html/draft-ietf-oauth-jwsreq-17.  The parameters need to be registered to avoid future claim number conflicts.  While conflicts have clearly been carefully avoided to date, they will inevitably occur in the future unless the values are actually registered.  Please do so.

DON'T SQUAT ON NUMERIC REGISTRY VALUES:  Please change all instances of numbers to be assigned by designated experts in existing registries from specific values to "TBD".  For instance, all the values for the CWT Claims Registry in Section 8.13 (currently 12, 16, and 17) should be changed to TBD.  Our chair, Jim Schaad has been a vigorous advocate of not squatting in my past interactions with him as a Designated Expert and I believe would support this request.  Likewise, the "19" in the CoAP Content-Format Registration in Section 8.15 should become TBD.

**DONE** req_aud: Several examples use the "req_aud" parameter without defining it.  Doesn't this duplicate the "resource" parameter defined by https://tools.ietf.org/html/draft-ietf-oauth-resource-indicators-01?  If so, please delete this parameter and use "resource".  If not, say how it is different and why the differences are necessary.

**DONE** rs_cnf:  There isn't a clear normative definition of this parameter.  It's mentioned obliquely but its purpose, syntax, and semantics should be plainly stated (as with each other newly defined parameter).

The proposed numbers in Figures 12 and 16 contain mismatches.  For instance, token_type is "14" in Figure 12 in Section 5.6.5 and "13" in Figure 16 in Section 5.7.4.  There's too much alignment for it to be a coincidence but if you intend alignment, please say so explicitly and fix the alignment.  The proposed ongoing alignment should also be described in the registration instructions for the Designated Experts.

-- Mike

P.S.  Per my earlier reviews of this specification, in my view as a Designated Expert for the CWT Claims registry, I believe that it's not appropriate to use up rare single-byte identifiers for most of the OAuth parameter encodings specified in 5.6.5.  I could be persuaded that "scope" merits one of these rare numbers, but "profile", "error", "grant_type", "access_token", and "token_type" probably do not, as they are application-specific and not of general applicability.  I also believe that some of the other Designated Experts for this registry agree with me.

Jim Schaad

* Section 3.1 - Refresh Token - I don't think that refresh tokens are going
to be strings because binary is more efficient.

**DONE** * Section 3.2 - we need to reference TLS 1.3 even if DTLS 1.3 is not yet
available.

* Description for Figure 6 -  Should the example somehow indicate in the
message that it is going to be an application/ace+cbor content.  Also, I
don't know that this is a good example in some ways because this is not a
currently documented profile anywhere.

**DONE** * Section 5.6.3 - Should the content type for an error response be
application/ace+cbor ?

**DONE** * Section 5.7.1 - Is the content format for a request application/ace+cbor?
I assume it is but that is not documented in this section.

**DONE** Section 5.8 - bytes arrays or byte strings?  I think CBOR uses the latter

**DONE** * Section 5.8.1 - What is the purpose of creating an identifier for a token?
Is this supposed to be used rather than the one from the AS for something
like shared secret TLS?  Note that this is an unprotected value.

* Section 5.8.1 - Given the change in the OSCORE profile, you might want to
make this an application/ace+cbor structure as well.

**DONE** * Section 5.8.1 - If the token is "not valid" is the RS required (i.e. MUST)
to try introspection before returning a response if the RS does
introspection?  The text currently says MAY.  If this is really MAY then the
text should say that the token is always successfully accepted by the RS.

* Section 5.8.2 - If the RS is going to do introspection, can it send some
type of "Server Busy - try again in xxx" while it does the introspection
rather than just doing an ack of the request and possibly waiting a long
time?

* Section 5.8.3 - third point - I think that the correct text would be "The
method does not provide timely expiration, but it makes sure that older
tokens will cease to be valid after newer issued tokens are registered with
the RS."  My problem is that just issuing tokens is not enough as they may
be going to a different RS for use.  This may also need to have some type of
rate limit to issued tokens or making the sequence number be on an
RS/audience basis.

* Section 6. - The recommendation not to use a shared secret for an audience
which is hosted by multiple servers is interesting.  This does require that
a multiple recipient COSE structure be used and it may be worth calling that
out.  Also the size of the CWT is going to grow for that.  You are also now
losing the low-level authentication and thus a signature wrapping is now
also needed.

**DONE** * Section 6 - "Developers MUST" para - May want to add that this can also be
mitigated to some extent by making sure that keys roll over more frequently.

* Section 6 - I am not sure that I agree with the SHOULD NOT in the last
paragraph.  Think multicast.

**DONE** * Section 6.4 - This also applies to sending back some type of identifier
from the RS->C when a token is registered.

**DONE** * Section 8.6.1 - Is pop still this document or is it Mike's document?

**DONE** * Section 8.9 - The description of reference is wrong.

**DONE** * Section 8.12 - some of these should move to the OAuth parameters document?

**DONE** * Section 8.13 - ditto

**DONE** * Appendix A -  para "CBOR, COSE, CWT"  - Is it really a requirement to use
CBOR or is that a recommended?  I thought this was part of what Hannes was
looking at.

**DONE** * Appendix A - para Client Credentials Grant  s/can the/can then/

* Registries -  I am wondering if we should think about re-writing a couple
of the registries.  As things stand it appears that the application/ace+cbor
content type is being used in 5 or 6 places.  It might make more sense to
have a registry for all of the CBOR abbreviations that are being used in a
single table and have multiple columns for each of the different places were
the content format is being used.  This would make it easier to keep
everything constant and can make re-use of integer values easier to see. 

* Comments on protection of CWT/Token:  I am wondering if there needs to be
any comments on how a CWT is going to be protected.  While it is ok to use
either a symmetric key or a direct key agreement operation for a single
recipient without forcing a signature operation to occur.  If the token is
going to be targeted a single audience hosted on multiple RSs then a
signature operation would be required for the purposes of authentication. 

**DONE** * I am not sure where this issue should be raised so I am putting it here.
Both of the profiles have as their last security consideration a statement
that the use of multiple access tokens is a bad idea.  Both of them also
devote a large section of text to how to deal with multiple access tokens as
does this document.  More methods of having multiple access tokens seem to
be coming down the path from the OAuth group.  This appears to be a distinct
contradiction within the set of documents that should be resolved.