Authentication and Authorization for Constrained Environments Using the OAuth 2.0 Framework (ACE-OAuth)
draft-ietf-ace-oauth-authz-46

[[ comments ]]

[ section 5.10.3 ]

* It seems to me that making the described expired token list behaviour
  a MUST may be overspecifying things.  Is there some reason it can't be
  downgraded to SHOULD?

  Also: does this described algorithm rely upon all exi values being
  essentially the same?  I was thinking about expires_in values varying
  wildly (for whatever reason) and I wasn't sure how this sequence number
  tracking would work in that case.

[ section 6.6 ]

* I presume another alternative is for the RS to delay (or postpone with
  some error code?) request handling until time synchronization (NTP, NITZ,
  ...) has completed (even if only the time is sync'd/stepped and no other
  parameters are coordinated).


[[ nits ]]

[ section 5.8.1 ]

* "in order allow" -> "in order to allow"

* ", specifically" > probably two separate sentences reads more clearly.
  ". Specifically"

* "}W" -> "}"?

* "can only use to" -> "can only be used to"?

[ section 6.6 ]

* "loose" -> "lose"

Thanks for addressing my DISCUSS (discussion archived at https://mailarchive.ietf.org/arch/msg/ace/mrVrwJGreSSE2yNJK1uPW0P7p0o/ ) 

I keep the original ballot below for the leftover non-blocking points 1, 9,  18,  19,  32, 37.

Francesca

========== Original Ballot - 2021-03-24 ==============

Thank you for this document. I think this is an important document which should move forward, but I would like to discuss some points before it does so. These might result in simple clarifications, or might require more discussion, but I do hope they help improve the document.

General comments:

I found confusing to understand how optional or mandatory is the use of CBOR for profiles of this specification compared to the transport used. I understand the need for flexibility, but maybe it should be clarified the implication of using CoAP (is CBOR mandatory then?) vs HTTP (is CBOR always permitted? How is the encoding in that case? Is the same media type application/ace+cbor used in that case?). Note also that while requests include the content type to use, both in case HTTP or CoAP+CBOR are used, the response don't seem to include this information. 

I would like it to be clarified what requirements (or even just recommendations) are there to use CoAP vs HTTP for different legs of the exchange - not necessarily remove the flexibility but to clarify for implementers what can be done and what would be the reasoning to do that: for example if both endpoints support HTTP with the AS, most likely you can have HTTP between C and RS, so does it really make sense to run this instead of OAuth 2.0? Right now all is permitted, but does it all make sense? I feel like this type of considerations are missing. As a note - I am not sure what allowing a different encoding than CBOR for any leg of the exchange adds to the specification - it makes things more confusing, and if needed it could be specified in another document.

While going through and thinking about encodings (assuming we keep the doc as is with regards to allowing more than just CBOR), I wondered if it would be better to define a new media type to use when the ACE framework is used with HTTP, to differentiate from OAuth 2.0, since some of the endpoints used are the same (/token and /introspect at the AS). I am interested to hear more from my co-AD as well if this would be an OK use of a new media type - I am thinking of the case where AS is supporting both OAuth 2.0 and the Ace framework - or if it is unnecessary, since the encodings are the same, and the parameters are registered in OAuth 2.0 registry. 

More detailed comments below.
Francesca


Detailed comments:

1. -----

   sufficiently compact.  CBOR is a binary encoding designed for small
   code and message size, which may be used for encoding of self
   contained tokens, and also for encoding payloads transferred in
   protocol messages.

FP: "may be used" make it seem as if CBOR is always optional (even when CoAP is used). See points 11. and 13. for examples of text that seem to imply that CBOR is mandatory in some cases.

2. -----

      Refresh tokens are issued to the client by the authorization
      server and are used to obtain a new access token when the current
      access token becomes invalid or expires, or to obtain additional

FP: token validity - it is not clear what it means for a token to become invalid (vs expiring). As this is the first time it is mentioned, it should be explained here or referenced.

3. -----

         An asymmetric key pair is generated on the token's recipient
         and the public key is sent to the AS (if it does not already
 
          inside the token and sent back to the requesting party.  The
         consumer of the token can identify the public key from the
 

 FP: "token's recipient" and "consumer of the token" - why not talk about client and resource server here? It would fit better with the terminology used in the rest of the document.

 4. -----

    This framework RECOMMENDS the use of CoAP as replacement for HTTP for
   use in constrained environments.  For communication security this

FP: This was already stated in the introduction in the following sentence:

   of processing capabilities, available memory, etc.  For web
   applications on constrained nodes, this specification RECOMMENDS the
   use of the Constrained Application Protocol (CoAP) [RFC7252] as
   replacement for HTTP.

Not sure repeating is useful.

5. -----

   OAuth 2.0 (such as [RFC7521] and [RFC8628]).  What grant types works
   best depends on the usage scenario and [RFC7744] describes many
   different IoT use cases but there are two preferred grant types,
   namely the Authorization Code Grant (described in Section 4.1 of

FP: nit: s/works/work . I think "preferred" is probably not the right term here, and should be rephrased or clarified - preferred respect to?

6. -----

      In addition to the response parameters defined by OAuth 2.0 and
      the PoP access token extension, this framework defines parameters
      that can be used to inform the client about capabilities of the
      RS, e.g. the profiles the RS supports.  More information about

FP: I believe this is a leftover from a previous version of the document, but should be "profile" and not "profiles" as the AS is only allowed to communicate one profile to the client and RS - see for example the following sentences:

      The Client and the RS mutually authenticate using the security
      protocol specified in the profile (see step B) and the keys

      The AS informs the client of the selected profile using the
      "ace_profile" parameter in the token response.

7. -----

         (1) the client sends the access token containing, or
         referencing, the authorization information to the RS, that may
         be used for subsequent resource requests by the client, and

FP: s/may/will

8. -----

      While the structure and encoding of the access token varies
      throughout deployments, a standardized format has been defined
      with the JSON Web Token (JWT) [RFC7519] where claims are encoded
      as a JSON object.  In [RFC8392], an equivalent format using CBOR
      encoding (CWT) has been defined.

FP: Would it make sense to RECOMMEND the use of JWT when HTTP is used? Or is CWT always RECOMMENDED?

9. -----

   parameters.  When profiles of this framework use CoAP instead, it is
   REQUIRED to use of the following alternative instead of Uri-query
   parameters: The sender (client or RS) encodes the parameters of its
   request as a CBOR map and submits that map as the payload of the POST
   request.

FP: I think it should be better defined (or at least hinted in this paragraph) the mapping between the CBOR encoded parameters and the Uri-query parameters: are they all encoded as CBOR text strings? 

10. -----

   Applications that use this media type: The type is used by
   authorization servers, clients and resource servers that support the
   ACE framework as specified in [this document].

FP: I suggest adding "that support the ACE framework with CBOR encoding, as specified ..."

11. -----

   The OAuth 2.0 AS uses a JSON structure in the payload of its
   responses both to client and RS.  If CoAP is used, it is REQUIRED to
   use CBOR [RFC8949] instead of JSON.  Depending on the profile, the
   CBOR payload MAY be enclosed in a non-CBOR cryptographic wrapper.

FP: This sentence seems to add a requirement (when CoAP is used, then CBOR must be used) only for communication from AS to C or RS. I could not find in the rest of the specification the same type of requirement for the other legs of communication (C to AS, RS to AS, C to RS). Please let me know if I missed it.

12. -----

   the AS authorization is not in scope for this document.  C may, e.g.,
   ask it's owner if this AS is authorized for this RS.  C may also use
   a mechanism that addresses both problems at once.

FP: nit - s/it's/its . Also "C may also use ... at once" such as? I think it would be good to give an example here.

13. -----

   valid access token.  The AS Request Creation Hints message is a CBOR
   map, with an OPTIONAL element "AS" specifying an absolute URI (see

FP: another case where CBOR seem mandatory.. Is this the case, even if HTTP or other protocol is used?

14. -----

      MUST discard the access token.  If this was an interaction with
      the authz-info endpoint the RS MUST also respond with an error
      message using a response code equivalent to the CoAP code 4.01
      (Unauthorized).

FP: This seems to imply that another endpoint could be used to receive an access token. Is that the case, and if so where is this defined?

15. -----

Section 5.8:

  If HTTPS is used, JSON or CBOR payloads may be supported.  If JSON
   payloads are used, the semantics of Section 4 of the OAuth 2.0
   specification MUST be followed (with additions as described below).

FP: I suggest to point to the specific subsection in OAuth - namely 4.1.3 and 4.1.4

16. -----

   If CBOR is used then these parameters MUST be provided as a CBOR map.

FP: s/as/in . I suggest to reference Figure 12.

17. -----

   the HTTP request entity-body, as defined in section 3.2 of [RFC6749].

FP: Section 3.2 of OAuth 2.0 specifies:

   The endpoint URI MAY include an "application/x-www-form-urlencoded"
   formatted (per Appendix B) query component ([RFC3986] Section 3.4),
   which MUST be retained when adding additional query parameters.  The
   endpoint URI MUST NOT include a fragment component.

which explicitly specifies that the parameters are transported as query components. I either suggest to change this reference to Appendix B of RFC6749.

18. -----

         "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8'

FP: noted here since this is the first time it appears, but same comment for the rest of the document. I think it would make more sense to show examples where CBOR byte strings are used instead of Base64.

19. -----

   Figure 8 summarizes the parameters that can currently be part of the
   Access Information.  Future extensions may define additional
   parameters.

FP: This is useful! Why not having the same type of figure listing all acceptable parameters for the request (section 5.8.1)?

20. -----

   Header: Created (Code=2.01)
   Content-Format: "application/ace+cbor"
   Payload:
   {
     "access_token" : b64'SlAV32hkKG ...
      (remainder of CWT omitted for brevity;
      CWT contains COSE_Key in the "cnf" claim)',
     "ace_profile" : "coap_dtls",
     "expires_in" : "3600",
     "cnf" : {
       "COSE_Key" : {
         "kty" : "Symmetric",
         "kid" : b64'39Gqlw',
         "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh'
       }
     }
   }

       Figure 9: Example AS response with an access token bound to a
                              symmetric key.

FP: Section 3.1 states:

      Symmetric PoP key:
         The AS generates a random symmetric PoP key.  The key is either
         stored to be returned on introspection calls or encrypted and
         included in the token.  The PoP key is also encrypted for the
         token recipient and sent to the recipient together with the
         token.

But in the example the key is not encrypted.

21. -----

   o  When using CBOR the raw payload before being processed by the
      communication security protocol MUST be encoded as a CBOR map.


FP: I don't understand "before being processed by the communication security protocol"

22. -----

   o  The Content-Format (for CoAP-based interactions) or media type
      (for HTTP-based interactions) "application/ace+cbor" MUST be used
      for the error response.

FP: Does this mean that CBOR is always used for errors? However in the same section:

   o  The parameters "error", "error_description" and "error_uri" MUST
      be abbreviated using the codes specified in Figure 12, when a CBOR
      encoding is used.

"when a CBOR encoding is used" so not always?

23. -----

Sections 5.8.2, 5.8.3, 5.9.1, 5.9.2, 5.9.3, 5.10.1

FP: I found useful that Section 5.8.1 spelled out the encoding when HTTP is used (See sentence below). I think it would be as useful to have the same type of phrasing in these and following sections (wherever it is missing now). I think in general it is very clear in the document what format the message has when CBOR is used, and it seems that CBOR can be used with HTTP according to this specification (but not sure it is actually recommended, what are the pros and cons). In some sections (5.8.2, 5.8.3, etc) it is left to implicit references to OAuth 2.0 for the implementers to figure out what the encoding is (and what media type is used), although modifications are added to it.

   When HTTP is used as a transport then the client makes a request to
   the token endpoint by sending the parameters using the "application/
   x-www-form-urlencoded" format with a character encoding of UTF-8 in
   the HTTP request entity-body, as defined in section 3.2 of [RFC6749].

24. -----

      including the error code "unsupported_pop_key" defined in
      Figure 10.

      including the error code "incompatible_ace_profiles" defined in
      Figure 10.

FP: nit - these error codes are not "defined" in figure 10.

25. -----

   In this framework the "pop" value for the "token_type" parameter is
   the default.  The AS may, however, provide a different value.

FP: I would change the sentence to:

   In this framework the "pop" value for the "token_type" parameter is
   the default.  The AS may, however, provide a different value from those registered in [IANA registry].

26. -----

   Clients that want the AS to provide them with the "ace_profile"
   parameter in the access token response can indicate that by sending a
   ace_profile parameter with a null value (for CBOR-based interactions)
   or an empty string (for JSON based interactions) in the access token
   request.

      Hints Section 5.3.  The parameter is encoded as a byte string for
   CBOR-based interactions, and as a string (Base64 encoded binary) for
   JSON-based interactions. 

FP: OAuth 2.0 section 4.1.3 says that JSON is not used, the parameters are encoded using "application/x-www-form-urlencoded"
 format in the request entity-body.

27. -----

   The figures of this section uses CBOR diagnostic notation without the

FP: Nit - s/use

28. -----

   A client using this method MUST make a POST request to the authz-info
   endpoint at the RS with the access token in the payload.  The RS

FP: The formatting of the request is unclear - could you clarify that it depends on the access token used, and the media type (or content format) needs to reflect that? I.e. if CWT is used, the media type MUST be application/cwt.

29. -----

   o  If token or claim verification fails, the RS MUST discard the
      token and, if this was an interaction with authz-info, return an
      error message with a response code equivalent to the CoAP code

FP: Same comment as before, "if this was an interaction with authz-info" - the alternative needs to be clarified.

30. -----

   Errors may happen during this initial processing stage:

   o  If token or claim verification fails, the RS MUST discard the
      token and, if this was an interaction with authz-info, return an
      error message with a response code equivalent to the CoAP code
      4.01 (Unauthorized).

      ...

   Next, the RS MUST verify claims, if present, contained in the access
   token.  Errors are returned when claim checks fail, in the order of
   priority of this list:

FP: It seems weird to read first about errors due to claim verification, and then "Next" discuss claim verification - unless this is two different claim verifications, in which case I think this needs to be clarified. Also in each claim:

      the RS MUST discard the token.  If this was an interaction with
      authz-info, the RS MUST also respond with a response code
      equivalent to the CoAP code 4.01 (Unauthorized).

Seems like a repeat of the sentence above.

31. -----

   on the authz-info endpoint and on it's children (if any).

FP: nit - s/it's/its

32. -----

   The POST method SHOULD NOT be allowed on children of the authz-info
   endpoint.

FP: What children? They do not seem to be defined, so I do not understand this sentence.

33. -----

         +  When creating the token, the AS MUST add a 'cti' claim ( or
            'jti' for JWTs) to the access token.  The value of this

FP: Since the use of CWT and JWT are only recommended, it might be good to rephrase this as to allow for other access token's encodings too.

34. -----

         +  When creating the token, the AS MUST add a 'cti' claim ( or
            'jti' for JWTs) to the access token.  The value of this
            claim MUST be created as the binary representation of the
            concatenation of the identifier of the RS with a sequence
            number counting the tokens containing an 'exi' claim, issued
            by this AS for the RS.

         +  The RS MUST store the highest sequence number of an expired
            token containing the "exi" claim that it has seen, and treat
            tokens with lower sequence numbers as expired.

FP: A question rather than a comment - I am not sure I understand this. An "exi" value might be higher for a different token (with a lower sequence number), so how does the counter of the tokens help? Wouldn't that make the RS discard a valid token just because it has a lower sequence number?

35. -----

   RS.  Therefore, C must not communicate with an AS if it cannot
   determine that this AS has the authority to issue access tokens for
   this RS.  Otherwise, a compromised RS may use this to perform a

FP: How is C supposed to determine that? Doesn't this sentence make the whole AS Creation Hints response useless - either the client already knows, or it doesn't and it must not communicate with it regardless of RS says?

36. -----

   compromised.  In order to prevent this, an RS may use the nonce-based
   mechanism defined in Section 5.3 to ensure freshness of an Access

FP: please mention "cnonce" to make it easier to find.

37. -----

   There may be use cases were different profiles of this framework are
   combined.  For example, an MQTT-TLS profile is used between the
   client and the RS in combination with a CoAP-DTLS profile for
   interactions between the client and the AS.  The security of a
   profile MUST NOT depend on the assumption that the profile is used
   for all the different types of interactions in this framework.

FP: This seems strange - maybe I just don't understand how this is supposed to work, but each profile defines exactly at least C - RS communication and security, if several are combined, it seems that at least the C-RS would conflict.

I share Eric V's concern about the apparently stale nature of the shepherd writeup.  It seems to be a common oversight lately.

I also agree with Eric about Section 3.  Nicely done.

Since I'm getting to this document last in our queue this week, I find I have little to contribute here that my colleagues didn't already include in their positions, save this one gem:

Section 8.2 should probably say explicitly that the registration should refer to this document, since that is a column of the registry to which you are adding an entry.

Thanks for working on this document. I found the overview section very helpful to setup the knowledge required to absorb the rest of the document. 

I have following observations and/or nits, hopefully this will improve this document -

* Section 1: 
     For web
     applications on constrained nodes, this specification RECOMMENDS the
     use of the Constrained Application Protocol (CoAP) [RFC7252] as
     replacement for HTTP.

  I can't parse the normative text "RECOMMENDS " :-). I believe if normative text is used here then "RECOMMEND" or "RECOMMENDED" should be used. By the way, there are more occurrence of "RECOMMENDS " in this document. The same comment applied for those occurrences .


* Section 2 : I would suggest to drop "we use" from the beginning of last two paragraphs in this section and write those paraphaphs in passive form to harmonize with rest of the section.

* Section 3.1 : 
      Introspection is a method for a resource server to query the
      authorization server for the active state and content of a
      received access token.  This is particularly useful in those cases
      where the authorization decisions are very dynamic and/or where
      the received access token itself is an opaque reference rather
      than a self-contained token.  More information about introspection
      in OAuth 2.0 can be found in [RFC7662].

   I got gradually introduced in this document that potentially the client can also use the method to query for more information (Section 5.9) via RS. I think it will be helpful if this is described early that RS and client both can use the introspection offered by AS.

* Section 4 : Figure 1
  
  The use of (optional) here is a bit confusing. The (optional) tag in (B) means it is optional to include refresh token. For (D) and (E) the meaning of (optional) is completely different. The response to the Introspection Request is not optional, is it?.. but that interaction between AS and RS is optional. It might be good to separate the use of "optional" in this figure / or amend the figure in a different way to avoid such confusion.


* Section 5.2 : 

      The request has been received on an unprotected channel.

  The definition of "unprotected" would be appropriated here. does this refer to secure communication channel?

* Section 5.10.1. :
   Typo : s/Section Section / Section

Thank you for the work put into this document. I have really appreciated the informative and concise section 3 "overview". The flow and the explanations are really superb: if only all published RFC could have this level of quality ;-)

While I appreciate that the document shepherd was the past Jim Schaad, I find it weird to read a shepherd's review is for the -21 revision while the balloted revision is -38 as I usually rely on those write-ups to get an idea about the WG consensus...
Anyway I am trusting the responsible AD for this I-D.

Side note: due to lack of time, I have skipped the security and IANA considerations sections as I trust the responsible AD.

Please find below some non-blocking COMMENT points (but replies would be appreciated), and some nits.

Last very minor/cosmetic comment about this document as well to the oAuth terminology: using "refresh tokens" sounds weird to me, I would have preferred "permanent tokens" or "long-term tokens", but, I am afraid that the train has left the station for many years ;-) And the same applies for "introspection" that usually is done internally and does not require a third party as in oAuth (but this is another train, which has also left the station...).

I hope that this helps to improve the document,

Regards,

-éric

== COMMENTS ==

-- Section 3 --
Should references/expansions be added for "HTTP/2, MQTT, BLE and QUIC" ?

-- Section 3.1 --
Suggest to review the order of the definitions, notably popping up "introspection" as it is used by most of the other terms.

-- Section 4 --
Mostly cosmetic, any reason why figure 1 is so far away from its mention in §1 ?

In "ensure that its content cannot be modified, and if needed, that the content is confidentiality protected", I wonder why the confidentiality is only optional ? As far as I understand it, the possession of an access token grants access to a ressource, so, it should be protected against sniffing. What did I miss ?

In "If the AS successfully processes the request from the client" may look ambiguous because processing correctly (per protocol) an invalid credential is also "successfully processed". Suggest to mention something about "positive authentication" ;)

-- Section 5 --
As a non-English native speaker, I cannot see the verb in the second proposition in "For IoT, it cannot be assumed that the client and RS are part of a common key infrastructure, so the AS provisions credentials or associated information to allow mutual authentication.". While I obviously understand the meaning, could it be rephrased ?

-- Section 5.1.1 --
Could the word "unprotected" be better defined in "received on an unprotected channel" ? E.g., is it only about TLS ? Else, I like the implicit lack of trust.

-- Section 5.1.2 --
I must admit that I have failed to understand the semantic of "audience"... Can you either explain its meaning or provide a reference ?

-- Section 5.5 --
In "Since it requires the use of a user agent (i.e., browser)" is it "i.e." or "e.g." ?

-- Section 5.6 --
s/the semantics described below MUST be/the semantics described in this section MUST be/ ?

In "The default name of this endpoint in an url-path is '/token'" should "SHOULD" normative language be used ?

-- Section 5.6.4.1 --
In figure 11, would you mind adding the section ID in addition to RFC 6749 ? I failed to spot them in RFC 6749.

-- Section 5.7.2 --
It is a little unclear to me which profile must be used as 'profile' is optionnial? Should a default or any profile be used ?

-- Section 5.8.1 --
Suggest to use the BCP14 "SHOULD" in the text "The default name of this endpoint in an url-path is '/authz-info'"

-- Section 10.2 --
Is RFC 7049 really an informative reference as CBOR appears as the default encoding ?
      
== NITS ==

s/application layer protocol/application-layer protocol/ ?

Should multi-words message names (e.g.,  AS Request Creation Hints) be enclosed by quotes ?

-- Section 2 --
Please introduce "authz-info" before first use.

-- Section 3.1 --
"PoP" is expanded twice in this section ;-)

"CBOR encoding (CWT) " the "CWT" acronym does not match the expansion :-)

-- Section 4 --

Sometimes "Client" is used and sometimes "client" is used...

s/reference to a specific credential/reference to a specific access credential/ ?

-- Section 5.1.2 --
Can you introduce to "kid" acronym ? It too me a while to understand that it is (probably) key-id... :-)

Unsure whether "nonce: h'e0a156bb3f'," is the usual IETF way to introduce an hexadecimal number.

typo in "5.8.4.  Key Expriation" :-)

Section 1, paragraph 3, comment:
>    of processing capabilities, available memory, etc.  For web
>    applications on constrained nodes, this specification RECOMMENDS the
>    use of the Constrained Application Protocol (CoAP) [RFC7252] as
>    replacement for HTTP.

Since the rest of this section is pretty careful in explaining that there is a
capability spectrum for IoT devices, I was surprised about this broad
recommendation against HTTP (which is also repeated elsewhere in the text.)

-------------------------------------------------------------------------------
All comments below are very minor change suggestions that you may choose to
incorporate in some way (or ignore), as you see fit. There is no need to let me
know what you did with these suggestions.

Stewart Bryant's Gen-ART review
(https://mailarchive.ietf.org/arch/msg/gen-art/04lPOKG404s-LNfVm40ZE8s-Wig/)
contained some nits that I wanted to make sure you were aware of.

"Table of Contents", paragraph 1, nit:
> Table of Contents

Some sections don't use title case.

Section 4, paragraph 9, nit:
-    In Bluetooth Low Energy, for example, advertisements are broadcasted
-                                                                      --
+    In Bluetooth Low Energy, for example, advertisements are broadcast

Section 5.3, paragraph 15, nit:
-    freshness nevetheless, the RS has included a "cnonce" parameter (see
+    freshness nevertheless, the RS has included a "cnonce" parameter (see
+                  +

"Appendix E.", paragraph 33, nit:
-       as playload the Access Information, including the access token and
-           -
+       as payload the Access Information, including the access token and

One minor comment:  I found it a slight leap in the introduction in the final paragraph ("More detailed, ...") that talks about interoperable specifications (implying that specification is not interoperable) and profiles (where it isn't clear where these have come from).  So, an extra sentence to bridge the concepts might be helpful in the introduction.  As a nit, the paragraph is also missing a comma in "interoperate while".