Subject: [OAUTH-WG] question about the b64token syntax in draft-ietf-oauth-v2-bearer

From: Brian Campbell <[email-masked]>
Date: Mon, 5 Mar 2012 14:40:21 -0800

On casual reading of "The OAuth 2.0 Authorization Protocol: Bearer
Tokens"* I've encountered several people (including myself) who have
made the assumption that the name b64token implies that some kind of
base64 encoding/decoding on the access token is taking place between
the client and RS.

Digging a bit deeper in to "HTTP/1.1, part 7: Authentication"**,
however, I see that b64token is just an ABNF syntax definition
allowing for characters typically used in base64, base64url, etc.. So
the b64token doesn't define any encoding or decoding but rather just
defines what characters can be used in the part of the Authorization
header that will contain the access token.

Do I read this correctly?

If so, I feel like some additional clarifying text in the Bearer
Tokens draft might help avoid what is (based on my small sample) a
common point of misunderstanding.

Also, does the use of b64token implicitly limit the allowed characters
that an AS can use to construct a bearer access token?

Thanks,
Brian

* http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-17#section-2.1
** http://tools.ietf.org/html/draft-ietf-httpbis-p7-auth-18#section-2.1

---

From: "Manger, James H" <[email-masked]>
Date: Tue, 6 Mar 2012 10:32:54 +1100

Brian,

> Do I read this correctly?

Yes.

> common point of misunderstanding.

Changing the example bearer token should be a simple way to avoid some confusion by showing that it does not have to be base64 encoding. How about changing:
  Authorization: Bearer vF9dft4qmT
to
  Authorization: Bearer vF9.dft4.qmT

The Bearer spec has lots of (unnecessary) text about OAuth, but doesn't quite manage to be precise about how OAuth and Bearer connect. It could explicitly state that the string value of the "access_token" member of an access token response is the bearer token. The "access_token" string value (after unescaping any JSON-escapes) MUST match the b64token ABNF so it can be used with the Bearer HTTP scheme. Such text could be put in §5.1.1 where the "Bearer" OAuth access token type is defined.

> that an AS can use to construct a bearer access token?

Yes.

--
James Manger

---

From: Mike Jones <[email-masked]>
Date: Tue, 6 Mar 2012 01:32:58 +0000

I'm fine with changing the example to make it clearer that b64token allows a wider range of characters than just those legal for base64 and base64url encodings of data values.

I'll add it to my to-do list for any additional edits for the Bearer spec.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Manger, James H
Sent: Monday, March 05, 2012 3:33 PM
To: Brian Campbell; oauth
Subject: Re: [OAUTH-WG] question about the b64token syntax in draft-ietf-oauth-v2-bearer

Brian,

Yes.

Yes.

> ** 
> http://tools.ietf.org/html/draft-ietf-httpbis-p7-auth-18#section-2.1

--
James Manger
_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: Brian Campbell <[email-masked]>
Date: Tue, 6 Mar 2012 08:23:24 -0800

Thanks Mike, I think changing the example would be helpful.

However I think that including some text along the lines of what James
suggested would also be very valuable. I agree that the connection
between OAuth and Bearer could and should be made more explicit. And
that the implications of the b64token syntax, particularly on what AS
can use to construct ATs, could/should be made more clear.

I can propose some specific text (building on James') if others in the WG agree?

---

From: Paul Madsen <[email-masked]>
Date: Tue, 06 Mar 2012 11:29:40 -0500

as one of the unnamed 'confused colleagues', I'd welcome clarification

paul

On 3/6/12 11:23 AM, Brian Campbell wrote:
> On Mon, Mar 5, 2012 at 5:32 PM, Mike Jones<[email-masked]>  wrote:

---

From: Justin Richer <[email-masked]>
Date: Tue, 6 Mar 2012 11:32:04 -0500

I think clarification text makes sense here because we're importing a 
term from a foreign spec -- b64token -- that overlaps with a term 
meaning something quite different in our spec -- token. We can't really 
change either of these terms, so we need to separate them some other way.
  -- Justin

On 03/06/2012 11:29 AM, Paul Madsen wrote:
>>> From:[email-masked]  [mailto:[email-masked]] On Behalf Of Manger, James H
>>>> *http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-17#section-2.1
>>>> **

---

From: William Mills <[email-masked]>
Date: Tue, 6 Mar 2012 10:45:28 -0800 (PST)

Yeah, something as simple as, "Note that the name 'b64token' does not imply base64 encoding, see the definition in [[INSERT REFERENCE HERE]]." would do it.

 -bill

________________________________
 From: Brian Campbell <[email-masked]>
To: Mike Jones <[email-masked]> 
Cc: oauth <[email-masked]> 
Sent: Tuesday, March 6, 2012 8:23 AM
Subject: Re: [OAUTH-WG] question about the b64token syntax in draft-ietf-oauth-v2-bearer

---

From: Brian Campbell <[email-masked]>
Date: Wed, 7 Mar 2012 10:16:31 -0700

I'd like to propose the following changes and additions, derived
largely from Bill and James suggestions, to
draft-ietf-oauth-v2-bearer-17.  These changes have no normative impact
and only aim to add additional clarity and explanation the workings
and implications of the current spec.  I'm definitely open to changes
or improvements in the wording here (not my strong suit by any means)
but I think it's important that these general ideas be conveyed in the
draft.

==> Insert the following text at the beginning of §2:

To make a protected resource request, the client must be in possession
of a valid bearer token. Typically a bearer token is returned to the
client as part of an access token response as defined in OAuth 2.0
[I-D.ietf-oauth-v2]. When the "token_type" parameter of the access
token response is "Bearer", the string value of the "access_token"
parameter becomes the bearer access token used to make protected
resource requests.

==> Change the value of the token in the Authorization header example to this:

Authorization: Bearer vF_9.5dCf-t4.qbcmT_k1b

==> Insert the following text before the last paragraph of §2.1:

Note that the name b64token does not imply base64 encoding but rather
is the name for an ABNF syntax definition from HTTP/1.1, Part 7
[I-D.ietf-httpbis-p7-auth]. Because of its use, the "access_token"
string value from an access token response MUST match the b64token
ABNF so it can be used with the Bearer HTTP scheme.

Thanks,
Brian

On Tue, Mar 6, 2012 at 11:45 AM, William Mills <[email-masked]> wrote:
> Yeah, something as simple as, "Note that the name 'b64token' does not imply
> base64 encoding, see the definition in [[INSERT REFERENCE HERE]]." would do
> it.
>
> -bill
>
>> I'm fine with changing the example to make it clearer that b64token allows
>> a wider range of characters than just those legal for base64 and base64url
>> encodings of data values.
>>
>> Changing the example bearer token should be a simple way to avoid some
>> confusion by showing that it does not have to be base64 encoding. How about
>> changing:
>> The Bearer spec has lots of (unnecessary) text about OAuth, but doesn't
>> quite manage to be precise about how OAuth and Bearer connect. It could
>> explicitly state that the string value of the "access_token" member of an
>> access token response is the bearer token. The "access_token" string value
>> (after unescaping any JSON-escapes) MUST match the b64token ABNF so it can
>> be used with the Bearer HTTP scheme. Such text could be put in §5.1.1 where
>> the "Bearer" OAuth access token type is defined.
>>
>>

---

From: William Mills <[email-masked]>
Date: Wed, 7 Mar 2012 10:45:25 -0800 (PST)

works for me.

P.S. Please start using the http://twiki.corp.yahoo.com/view/Paranoidyahoos/SecurityRequest  for new requests like product and feature  reviews.

________________________________
 From: Brian Campbell <[email-masked]>
To: William Mills <[email-masked]> 
Cc: Mike Jones <[email-masked]>; oauth <[email-masked]> 
Sent: Wednesday, March 7, 2012 9:16 AM
Subject: Re: [OAUTH-WG] question about the b64token syntax in draft-ietf-oauth-v2-bearer

Thanks,
Brian

---

From: Justin Richer <[email-masked]>
Date: Wed, 7 Mar 2012 14:00:26 -0500

Makes sense to me, except that I think the token_type value is typically 
lowercase "bearer", though it's defined to be case insensitive in 
Oauth-v2-23 section 5.1. Come to think of it, I'm not sure that the 
value of this field for the Bearer token type ever got defined anywhere. 
Section 7.1 references the bearer spec as defining the value of the 
"token_type" parameter, and passes its example as if by reference. Would 
be worthwhile giving an example of a token endpoint response, such as 
what's found in OAuth-v2-23 section 5.1.

  -- Justin

On 03/07/2012 12:16 PM, Brian Campbell wrote:
> On Tue, Mar 6, 2012 at 11:45 AM, William Mills<[email-masked]>  wrote:
>> From: Brian Campbell<[email-masked]>
>> To: Mike Jones<[email-masked]>
>> Cc: oauth<[email-masked]>

---

From: Brian Campbell <[email-masked]>
Date: Wed, 7 Mar 2012 14:08:14 -0700

Yeah, it is case insensitive. I just went with the upper case B
because that's how it was written in §5.1.1 of
draft-ietf-oauth-v2-bearer-17* which is where I guess it's actually
defined. But I see draft-ietf-oauth-v2-23 uses a lower case b**.
Either one would be fine.

I agree that an example response from the token endpoint would be
worthwhile.  Something like the following might help tie together with
the Authorization header example (proposed earlier). It could maybe be
worked in near the top of §2?

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"vF_9.5dCf-t4.qbcmT_k1b",
       "token_type":"example",
       "expires_in":3600,
       "refresh_token":"stGzv3xOdkF0X35Qp2TlKWIA",
     }

It'd probably make sense to change the examples in the body §2.2***
and query §2.3**** to use the same access token value too.

* http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-17#section-5.1.1
** http://tools.ietf.org/html/draft-ietf-oauth-v2-23#section-7.1
*** http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-17#section-2.2
**** http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-17#section-2.3

On Wed, Mar 7, 2012 at 12:00 PM, Justin Richer <[email-masked]> wrote:
> Oauth-v2-23 section 5.1. Come to think of it, I'm not sure that the value of
> this field for the Bearer token type ever got defined anywhere. Section 7.1
> references the bearer spec as defining the value of the "token_type"
> parameter, and passes its example as if by reference. Would be worthwhile
> giving an example of a token endpoint response, such as what's found in
> OAuth-v2-23 section 5.1.
>
>  -- Justin
>
>
>>>> From: [email-masked] [mailto:[email-masked]] On Behalf
>>>> Of
>>>> Manger, James H

---

From: Paul Madsen <[email-masked]>
Date: Wed, 07 Mar 2012 16:34:06 -0500

+1

On 3/7/12 4:08 PM, Brian Campbell wrote:
> On Wed, Mar 7, 2012 at 12:00 PM, Justin Richer<[email-masked]>  wrote: