Subject: [OAUTH-WG] Comments on draft-ietf-oauth-v2-bearer-03

From: "Manger, James H" <[email-masked]>
Date: Thu, 3 Mar 2011 14:35:25 +1100

Comments on the bearer token spec:

1. There is a whole lot of text about OAuth2 get-a-token parts that isn't necessary in the bearer token spec.

A bit of context can be useful to a reader, but in this case it brings too much of the complexity of the get-a-token flows into what should be a quite simple spec. It is not as though it can replace reading OAuth2 core.

1a. Change the title from "The OAuth 2.0 Protocol: Bearer Tokens" to

 "The BEARER HTTP authentication scheme", or

"Using Bearer Tokens in HTTP requests".

2. The abstract should say this is a mechanism for HTTP requests. My suggestion:

  "This specification describes how to include a bearer token conveying authorization information in an HTTP request. It also describes how to recognize a bearer token delivered by an OAuth 2.0 delegation flow."

3. We shouldn't "treat" an access token as a bearer token. A particular token either "is" a bearer token, or not (in which case "treating" it as a bearer token is wrong). Perhaps change:

"treating an OAuth access token as a bearer token" to

"when an OAuth access token is a bearer token".

4. Drop most of the "Introduction" and all of the "Overview". These are all about OAuth2 core and aren't necessary for understanding how to use a bearer token in an HTTP request. Here is my suggestion:

"Introduction

"A bearer token is the simplest mechanism for a client to convey its authority when sending a request to a server. A server accepting a bearer token assumes the authority it represents applies to whom ever presented it. That is, there is no additional authentication of the client. Consequently, it is crucial that a bearer token is never exposed to any party that might misuse it. Using bearer tokens that only represents a limited amount of authority, in a specific context, for a short amount of time can reduce the risks of using bearer tokens.

"This document specifies the "BEARER" HTTP authentication scheme for conveying a bearer token in an HTTP request header. It also specifies two alternatives for situations where it is infeasible for clients to modify HTTP headers: a URI query parameter; and a parameter in the body of a POST that uses the application/x-www-form-urlencoded media type.

"For example:

  GET /resource HTTP/1.1

  Host: example.com

  Authorization: BEARER vF9dft4qmTG_fdf-qwAS

"One possible source of dynamically issued bearer tokens is an OAuth 2.0 flow for user delegation or credential exchange as specified in [OAUTH2]. Section X of this document describes how a bearer token is represented in an OAuth 2.0 token response."

5. Section 2 "Authenticated Requests" starts with "clients make authenticated token requests using...". It sounds like the client is requesting a token, as opposed to using it. The term "authenticated token" confuses me a bit. Perhaps this section could start with:

  "Clients make requests with a bearer token using...".

Section 2.1 similarly talks about "authenticated token requests".

6. The multiple "MAY support" statements about the different methods in section 2 "Authenticated Requests" awkwardly overlap: MAY support additional methods [other than Authorization header]; MAY attempt to use POST body; MAY support these alternatives (POST body and URI query param).

How about:

"Sections 2.1, 2.2 and 2.3 defines how a bearer token can be carried in an HTTP header, a POST body, and a URI respectively. A server MUST support the HTTP header approach, MAY support the POST body approach, and MAY support the URI approach."

7. The ABNF for the Authorization header <credentials> doesn't comply with the ABNF in draft-ietf-httpbis-p7-auth-12. HTTPbis has relaxed the ABNF from its original spec in RFC2617 to accommodate schemes that use a base64 blob, instead of comma-separated name=value pairs, but it doesn't allow a mix of both forms. Acceptably choices for this spec are (from my most preferred to least): 1) use "BEARER a=<token>"; 2) use "BEARER <token>" with no extensions possible; 3) get a change to HTTPbis.

8. The allowed characters in <access-token> is crazy. Using <quoted-char>, but not within quotes is not a good sign?!

Token issuers don't need 93 allowed chars, just allow the 66 web-safe ones and make it simpler for everyone.

9. Don't say oauth_token SHOULD be the last parameter. This "SHOULD" has no useful purpose for clients or servers. All it can do is: add more code to clients to make it the last param (as opposed to treating it like any param, perhaps held in a Map/dictionary/associative-arrray); encourage servers to make dangerous checks, such as looking for the last occurrence of "&oauth_token=" instead of properly parsing the string.

10. Instead of concentrating on when a "WWW-Authenticate: Bearer" response header MUST be returned, we should focus what it means when it is present in a response. Servers can return it when they need that meaning. This would makes it clearer that it can be included with, say, a 200 OK response to indicate that more would be available if a bearer token had been included.

11. The "WWW-Authenticate: Bearer" response header would be a good place for the server to indicate whether or not it supports the URI & POST-body optional methods for conveying a bearer token. Perhaps a supports="body query" parameter?

12. A section explaining how a client can recognizes when a OAuth 2.0 token response contains a bearer token is needed. It would simply says that the token_type parameter SHALL have the value "bearer" when the token is intended to be used with the methods defined in this spec.

13. "Message Authentication Code (MAC)" is a better term than "keyed message digest" when describing how a token can be protected. Keyed message digests are only a subset of MACs, which can also be constructed from block ciphers for instance.

13. The threat mitigation (3.2) text about passing-by-reference is not quite right. Suggestion:

  "Alternatively, a bearer token can be a reference to authorization information, rather than encoding the information directly. Such references MUST be infeasible for an attacker to guess, for instance by being randomly chosen 128-bit values (22 base64url characters). Using a reference may require an extra interaction between a server and the token issuer to resolve the reference to the authorization information."

14. Drop "with OAuth" from the first recommendation in 3.3. It is true for any use of the BEARER scheme.

 "This is the primary security consideration when using bearer tokens with OAuth..."

15. "Don't pass bearer tokens in page URLs" is a rather strange recommendation given the spec defines a way to do just this. The recommendation goes on to say "pass browser tokens in message bodies", but elsewhere we recommend using the Authorization header in preference to the body. Plus I guess "browser token" should be "bearer token".

Perhaps this recommendation is not about a client making requests to a resource server, but a client caching items in a user's browser for whom it is acting. If this is the case, the advice should be moved out of this spec and into OAuth 2.0 core.

16. "Don't store bearer tokens in cookies" has a MUST NOT "as cookies are generally sent in the clear", which seems harsh given that a server can use HTTPS to set a cookie and include a "secure" attribute so it is only returned over HTTPS. How about just telling servers to do these two things?

17. "Issue short-lived bearer tokens" mentions "the User-Agent" flow, but I think that has changed names. Perhaps rephrase it generically: "Only short-lived bearer tokens should be issued to clients that run within a web browser".

--

James Manger

---

From: Mike Jones <[email-masked]>
Date: Thu, 31 Mar 2011 18:19:03 +0000

Responses to suggestions not adopted are inline below.  Thanks for your input.

                                                            -- Mike

From: [email-masked] [mailto:[email-masked]] On Behalf Of Manger, James H
Sent: Wednesday, March 02, 2011 7:35 PM
To: OAuth Mailing List
Subject: [OAUTH-WG] Comments on draft-ietf-oauth-v2-bearer-03

> A bit of context can be useful to a reader, but in this case it brings too much of the complexity of the get-a-token flows into what should be a quite simple spec. It is not as though it can replac…

I believe that the text you mention is important to set the context for the use of OAuth 2.0 bearer tokens so readers will understand the context and purpose of this specification.  I would, however, consider further clarifying this text in a future draft, should you provide specific proposed edits that retain this context.

> "Using Bearer Tokens in HTTP requests".

Given that this specification is about using OAuth 2.0 with bearer tokens, removing "OAuth 2.0" from the title would remove necessary context that frames the purpose of the specification.

>   "This specification describes how to include a bearer token conveying authorization information in an HTTP request. It also describes how to recognize a bearer token delivered by an OAuth 2.0 del…

As above, I believe that this proposed change over-generalizes the intended purpose and scope of the specification, making it less clear to implementers and adopters.

> "One possible source of dynamically issued bearer tokens is an OAuth 2.0 flow for user delegation or credential exchange as specified in [OAUTH2]. Section X of this document describes how a bearer…

I believe that the text you mention is important to set the context for the use of OAuth 2.0 bearer tokens so readers will understand the context and purpose of this specification.  I would, however, consider further clarifying this text in a future draft, should you provide specific proposed edits that retain this context.

> Token issuers don't need 93 allowed chars, just allow the 66 web-safe ones and make it simpler for everyone.

This is insufficient rationale to introduce a breaking change.  I would want to see a demonstration of working group consensus for this change before making it.

I would want to see demonstration of a working group consensus to expend the usage of this field in this manner before making this change.

> 11. The "WWW-Authenticate: Bearer" response header would be a good place for the server to indicate whether or not it supports the URI & POST-body optional methods for conveying a bearer token. Per…

I would want to see a specific proposal and a demonstration of a working group consensus to expend the usage of this field in this manner before making this change.

> 12. A section explaining how a client can recognizes when a OAuth 2.0 token response contains a bearer token is needed. It would simply says that the token_type parameter SHALL have the value "bear…

It's not clear to me that overloading the meaning of the token_type parameter in this manner would increase interoperability.  I would want to see demonstration of a working group consensus to overload the meaning of the token_type parameter in this fashion before making this change.