Last Call Review of draft-ietf-oauth-v2-bearer-

Request Review of draft-ietf-oauth-v2-bearer
Requested rev. no specific revision (document currently at 23)
Type Last Call Review
Team General Area Review Team (Gen-ART) (genart)
Deadline 2012-02-07
Requested 2012-01-25
Other Reviews Genart Telechat review of - by Alexey Melnikov (diff)
Genart Last Call review of - by Alexey Melnikov (diff)
Review State Completed
Reviewer Alexey Melnikov
Review review-ietf-oauth-v2-bearer-genart-lc-melnikov-2012-01-29
Posted at
Draft last updated 2012-01-29
Review completed: 2012-01-29


I am the assigned Gen-ART reviewer for this draft. For background on 

Gen-ART, please see the FAQ at 


Please resolve these comments along with any other Last Call comments 

you may receive.

Document: draft-ietf-oauth-v2-bearer-15.txt
Reviewer: Alexey Melnikov
Review Date: 29 Jan 2012
IETF LC End Date: 7 Feb 2012
IESG Telechat date: (if known) -

Summary: Mostly ready, with a couple of things that should be addressed.

Major Issues:

I have 2 issues in section 3:

3.  The WWW-Authenticate Response Header Field

   If the protected resource request does not include authentication
   credentials or does not contain an access token that enables access
   to the protected resource, the resource server MUST include the HTTP
   "WWW-Authenticate" response header field; it MAY include it in
   response to other conditions as well.  The "WWW-Authenticate" header
   field uses the framework defined by HTTP/1.1, Part 7
   [I-D.ietf-httpbis-p7-auth] as follows:

   challenge       = "Bearer" [ 1*SP 1#param ]

   param           = realm / scope /
                     error / error-desc / error-uri /

   scope           = "scope" "=" quoted-string
   error           = "error" "=" quoted-string
   error-desc      = "error_description" "=" quoted-string
   error-uri       = "error_uri" "=" quoted-string

1). I am agreeing with Julian about redefinition of ABNF from HTTPBis 

documents. I believe there is a proposal to fix that but the new draft 

hasn't been posted yet.

2). My 2nd major issue is about the following paragraph:

   The "scope" attribute is a space-delimited list of scope values
   indicating the required scope of the access token for accessing the
   requested resource.  In some cases, the "scope" value will be used
   when requesting a new access token with sufficient scope of access to
   utilize the protected resource.  The "scope" attribute MUST NOT
   appear more than once.  The "scope" value is intended for
   programmatic use and is not meant to be displayed to end users.

I don't think this provide enough information about what this is,

how it is to be used and which values are allowed. As this is not meant 

to be displayed to end users, then you need to say what values are 

allowed and which entity can allocate them. Is there a registry for 

these tokens, e.g. an IANA registry?

Minor Issues:

2.2.  Form-Encoded Body Parameter

   When sending the access token in the HTTP request entity-body, the
   client adds the access token to the request body using the
   "access_token" parameter.  The client MUST NOT use this method unless
   all of the following conditions are met:

   o  The HTTP request entity-body is single-part.

   o  The entity-body follows the encoding requirements of the
      "application/x-www-form-urlencoded" content-type as defined by
      HTML 4.01 [W3C.REC-html401-19991224].

   o  The HTTP request entity-header includes the "Content-Type" header
      field set to "application/x-www-form-urlencoded".

I would combine the first and the third bullet into a single statement,
because they seem to be a bit confusing while being read separately.

(I.e., is it possible to have Content-Type of 

"application/x-www-form-urlencoded" with something which is multipart?)

Section "3.1.  Error Codes"

I recommend creating an IANA registry for these or explain why one is 

not needed.

4.2.  Threat Mitigation

   To protect against token disclosure, confidentiality protection MUST
   be applied using TLS [RFC5246] with a ciphersuite that provides
   confidentiality and integrity protection.  This requires that the
   communication interaction between the client and the authorization
   server, as well as the interaction between the client and the
   resource server, utilize confidentiality and integrity protection.
   Since TLS is mandatory to implement and to use with this
   specification, it is the preferred approach for preventing token
   disclosure via the communication channel.  For those cases where the
   client is prevented from observing the contents of the token, token
   encryption MUST be applied in addition to the usage of TLS
   protection.  As a further defense against token disclosure, the
   client MUST validate the TLS certificate chain when making requests
   to protected resources.


   To deal with token capture and replay, the following recommendations
   are made: First, the lifetime of the token MUST be limited; one means
   of achieving this is by putting a validity time field inside the
   protected part of the token.  Note that using short-lived (one hour
   or less) tokens reduces the impact of them being leaked.  Second,
   confidentiality protection of the exchanges between the client and
   the authorization server and between the client and the resource
   server MUST be applied.  As a consequence, no eavesdropper along the
   communication path is able to observe the token exchange.
   Consequently, such an on-path adversary cannot replay the token.
   Furthermore, when presenting the token to a resource server, the
   client MUST verify the identity of that resource server, as per
   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)

Firstly, I would move the RFC 6125 reference to the first paragraph 

quoted above (but see below). Secondly, you should either normatively 

reference RFC 2818 (HTTP over TLS) instead of RFC 6125, or you need to 

provide more information about how RFC 6125 is to be used, because it 

has several options which need to be described (use of SRV-IDs, URI-IDs, 

DNS-IDs, use of wildcards). I suspect you should just reference RFC 2818.


2.2.  Form-Encoded Body Parameter

   o  The content to be encoded in the entity-body MUST consist entirely
      of ASCII characters.

ASCII needs a reference.

ID-nits reports:

  == The document seems to lack the recommended RFC 2119 boilerplate, 

even if

     it appears to use RFC 2119 keywords -- however, there's a 

paragraph with

     a matching beginning. Boilerplate error?

     (The document does seem to have the reference to RFC 2119 which the
     ID-Checklist requires).

  == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 


     or 'RECOMMENDED' is not an accepted usage according to RFC 2119. 


     use uppercase 'NOT' together with RFC 2119 keywords (if that is 

what you



     Found 'MUST not' in this paragraph:

     o  Stated that bearer tokens MUST not be stored in cookies that can
     be sent in the clear in the Threat Mitigation section.