Subject: [OAUTH-WG] Editorial comments for draft-ietf-oauth-v2-bearer-09

From: Hannes Tschofenig <[email-masked]>
Date: Tue, 18 Oct 2011 17:21:56 -0700

Hi Mike, 

based on our discussion I suggest to make the following minor editorial changes to the specification. Let me provide specific text proposals. 

I recommend to extend the abstract a little bit. The current text does not tell the reader a lot and the RFC editor will require more text (because it is too short)

FROM: 

"
Abstract

   This specification describes how to use bearer tokens in HTTP
   requests to access OAuth 2.0 protected resources.
"

TO:

"
Abstract

   This specification describes how to use bearer tokens in HTTP
   requests to access OAuth 2.0 protected resources.  A bearer token has the 
   property that any party in possession of it (a "bearer") can use it to get 
   access to a resource granted (without demonstrating  
   possession of a cryptographic key).  To prevent misuse, the bearer token 
   has to be protected in storage and in transport. 
"

To make the introduction of Section 2 more readable I suggest the following modified text (that replaces the existing text). 

-----

  2. Authenticated Requests

   To access a protected resource the client needs to present the bearer token 
   to the resource server. This document defines three ways to encode the token 
   into a request, namely 
   
   1) Authorization Request Headers (described in Section 2.1)
   2) Form-Encoded Body Parameter (described in Section 2.2)  
   3) URI Query Parameter (described in Section 2.3)
   
   The usage of the authorization request headers is the preferred mechanism. 
   Resource servers MUST implement the authorization request header mechanism 
   and MAY implement other methods.

   Form-Encoded Body Parameter and URI Query Parameter are fall-back solutions 
   for environments where authorization request headers cannot be used. They 
   are therefore NOT RECOMMENDED for usage due to security deficiencies, as 
   documented in Section 4. They are nevertheless included in this specification 
   to describe existing deployments.
   
   Clients MUST NOT use more than one method to transmit the token in a single 
   request.

------ 

I also suggest to Section 2.4 into Section 3. The security consideration section then becomes Section 4. 

Ciao
Hannes