Subject: [OAUTH-WG] bearer token authorization header

From: Marius Scurtescu <[email-masked]>
Date: Mon, 9 May 2011 10:32:22 -0700

I am working through version 04 of the Bearer Token draft:
http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-04

Not sure how to interpret the authorization header grammar described
in section 2.1. The intent seems to be for something like:
Bearer dfgh76dfghdfg

After the scheme name, "Bearer", there is a required whitespace
followed by the actual token. The token is represented by a sequence
of printable characters, no escaping. No spaces or other elements are
allowed after the token. Is that correct?

RWS is not defined, I assume it is the "required whitespace" from
section 1.2.2 of:
http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-13

There is a reference to RFC2617, but not sure why. That seems to imply
that a list of values can be specified, which is not the case.

The fact that there is no escaping mechanism can potentially create
problems. The list of allowed characters is spelled out, but what if
some implementation uses other characters? Using a name value pair and
proper escaping is much safer IMO. For example:
Bearer token=dfgh76dfghdfg
or
Bearer token="dfgh76dfghdfg"

The value above can be either a token or a quoted string. HTTP header
parsers know how to parse tokens and quoted strings so an implementor
has a better chance of doing it right.

Mark Lentczner started a thread on this regard a few moths ago, James
Manger replied and suggested something similar:
http://www.ietf.org/mail-archive/web/oauth/current/msg04671.html

If it is too late to switch to a name/value pair, then I think we
should at least clean up the references.

Marius

---

From: Mike Jones <[email-masked]>
Date: Mon, 23 May 2011 19:10:20 +0000

Answers inline:

Not sure how to interpret the authorization header grammar described in section 2.1. The intent seems to be for something like:

Bearer dfgh76dfghdfg

After the scheme name, "Bearer", there is a required whitespace followed by the actual token. The token is represented by a sequence of printable characters, no escaping. No spaces or other elements are allowed after the token. Is that correct?
Yes

RWS is not defined, I assume it is the "required whitespace" from section 1.2.2 of:

http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-13
Correct.  If this isn't a standard by the time the bearer token spec, becomes an RFC I assume this definition will be pulled into the spec.

There is a reference to RFC2617, but not sure why. That seems to imply that a list of values can be specified, which is not the case.
Good catch.  I think this should have been 2616.

The fact that there is no escaping mechanism can potentially create problems. The list of allowed characters is spelled out, but what if some implementation uses other characters? Using a name value pair and proper escaping is much safer IMO. For example:

or

The value above can be either a token or a quoted string. HTTP header parsers know how to parse tokens and quoted strings so an implementor has a better chance of doing it right.

Mark Lentczner started a thread on this regard a few moths ago, James Manger replied and suggested something similar:

If it is too late to switch to a name/value pair, then I think we should at least clean up the references.
The definition allows the access token to be any string of one or more printable non-whitespace ASCII characters.  Thus, legal access token strings include ones like the ones you are asking for, such as:
               param="value"

                                                            -- Mike

-----Original Message-----
From: Marius Scurtescu [mailto:[email-masked]]
Sent: Monday, May 09, 2011 10:32 AM
To: OAuth WG; Mike Jones
Cc: Mark Lentczner; Manger, James H
Subject: bearer token authorization header

Not sure how to interpret the authorization header grammar described in section 2.1. The intent seems to be for something like:

Bearer dfgh76dfghdfg

After the scheme name, "Bearer", there is a required whitespace followed by the actual token. The token is represented by a sequence of printable characters, no escaping. No spaces or other elements are allowed after the token. Is that correct?

RWS is not defined, I assume it is the "required whitespace" from section 1.2.2 of:

There is a reference to RFC2617, but not sure why. That seems to imply that a list of values can be specified, which is not the case.

The fact that there is no escaping mechanism can potentially create problems. The list of allowed characters is spelled out, but what if some implementation uses other characters? Using a name value pair and proper escaping is much safer IMO. For example:

or

The value above can be either a token or a quoted string. HTTP header parsers know how to parse tokens and quoted strings so an implementor has a better chance of doing it right.

Mark Lentczner started a thread on this regard a few moths ago, James Manger replied and suggested something similar:

If it is too late to switch to a name/value pair, then I think we should at least clean up the references.

Marius

---

From: George Fletcher <[email-masked]>
Date: Tue, 24 May 2011 13:24:52 -0400

Do I understand this correctly that each resource owner can define it's 
own format for the "printable non-whitespace ASCII characters"? It seems 
like that would make it difficult for clients to use standard libraries 
because the Authorization header format could be different on a per 
resource/host basis.

Thanks,
George

On 5/23/11 3:10 PM, Mike Jones wrote:
> [snip]
> The definition allows the access token to be any string of one or more 
> printable non-whitespace ASCII characters.  Thus, legal access token 
> strings include ones like the ones you are asking for, such as:
>
>                param="value"
>
>                                                             -- Mike
>
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Marius Scurtescu <[email-masked]>
Date: Tue, 24 May 2011 11:27:50 -0700

The "printable non-whitespace ASCII characters" represents the access
token, which is supposed to be opaque. I don't think this affects
libraries.

Marius

On Tue, May 24, 2011 at 10:24 AM, George Fletcher <[email-masked]> wrote:
> Do I understand this correctly that each resource owner can define it's own
> format for the "printable non-whitespace ASCII characters"? It seems like
> that would make it difficult for clients to use standard libraries because
> the Authorization header format could be different on a per resource/host
> basis.
>
> Thanks,
> George
>
> problems. The list of allowed characters is spelled out, but what if some
> implementation uses other characters? Using a name value pair and proper
> escaping is much safer IMO. For example:
>
> parsers know how to parse tokens and quoted strings so an implementor has a
> better chance of doing it right.
>
>
>
> printable non-whitespace ASCII characters.  Thus, legal access token strings
> include ones like the ones you are asking for, such as:
>
>                param="value"
>
>
>
>                                                             -- Mike
>
>
>
> Not sure how to interpret the authorization header grammar described in
> section 2.1. The intent seems to be for something like:
>
> Bearer dfgh76dfghdfg
>
>
>
> After the scheme name, "Bearer", there is a required whitespace followed by
> the actual token. The token is represented by a sequence of printable
> characters, no escaping. No spaces or other elements are allowed after the
> token. Is that correct?
>
>
>
> There is a reference to RFC2617, but not sure why. That seems to imply that
> a list of values can be specified, which is not the case.
>
>
>
> problems. The list of allowed characters is spelled out, but what if some
> implementation uses other characters? Using a name value pair and proper
> escaping is much safer IMO. For example:
>
> parsers know how to parse tokens and quoted strings so an implementor has a
> better chance of doing it right.
>
>
>

---

From: Mike Jones <[email-masked]>
Date: Tue, 24 May 2011 20:04:32 +0000

George, you are correct that resources and clients must agree upon the format of the bearer token to achieve interoperability.  The means for achieving this agreement is out of the scope of this document.

				-- Mike

-----Original Message-----
From: Marius Scurtescu [mailto:[email-masked]] 
Sent: Tuesday, May 24, 2011 11:28 AM
To: George Fletcher
Cc: Mike Jones; OAuth WG
Subject: Re: [OAUTH-WG] bearer token authorization header

The "printable non-whitespace ASCII characters" represents the access token, which is supposed to be opaque. I don't think this affects libraries.

Marius

On Tue, May 24, 2011 at 10:24 AM, George Fletcher <[email-masked]> wrote:
> Do I understand this correctly that each resource owner can define 
> it's own format for the "printable non-whitespace ASCII characters"? 
> It seems like that would make it difficult for clients to use standard 
> libraries because the Authorization header format could be different 
> on a per resource/host basis.
>
> Thanks,
> George
>
> section
> 1.2.2 of:

---

From: Paul Madsen <[email-masked]>
Date: Wed, 25 May 2011 09:49:52 -0400

Mike/George, can you clarify in what sense must a client and RS agree on 
the format of a bearer token? Are they not opaque to the client, and so 
their internal format irrelevant to it?

paul

On 5/24/11 4:04 PM, Mike Jones wrote:
> On Tue, May 24, 2011 at 10:24 AM, George Fletcher<[email-masked]>  wrote:

---

From: John Kemp <[email-masked]>
Date: Wed, 25 May 2011 13:10:35 -0400

> George, you are correct that resources and clients must agree upon the format of the bearer token to achieve interoperability.  The means for achieving this agreement is out of the scope of this do…

I thought the means for achieving IOP was quite precisely described in the production below (excerpted from 2.1 of http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-04):

   credentials    = "Bearer" RWS access-token

   access-token   = 1*( quoted-char / <"> )

   quoted-char    =   "!" / "#" / "$" / "%" / "&" / "'" / "("
                    / ")" / "*" / "+" / "-" / "." / "/" / DIGIT
                    / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA
                    / "[" / "]" / "^" / "_" / "`" / "{" / "|"
                    / "}" / "~" / "\" / "," / ";"

- John

---

From: Mike Jones <[email-masked]>
Date: Wed, 25 May 2011 17:13:01 +0000

You're correct that I misspoke.  The Authorization Server and the Resource Server must agree on the format of the token.  Yes, it's opaque to the client.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Paul Madsen
Sent: Wednesday, May 25, 2011 6:50 AM
To: [email-masked]
Subject: Re: [OAUTH-WG] bearer token authorization header

Mike/George, can you clarify in what sense must a client and RS agree on the format of a bearer token? Are they not opaque to the client, and so their internal format irrelevant to it?

paul

On 5/24/11 4:04 PM, Mike Jones wrote:
>> It seems like that would make it difficult for clients to use 
>> standard libraries because the Authorization header format could be 
>> different on a per resource/host basis.
>>
>> Thanks,
>> George
>>
>> some implementation uses other characters? Using a name value pair 
>> and proper escaping is much safer IMO. For example:
>>
>> The definition allows the access token to be any string of one or 
>> more printable non-whitespace ASCII characters.  Thus, legal access 
>> token strings include ones like the ones you are asking for, such as:
>>
>>                 param="value"
>>
>>
>>
>>                                                              -- Mike
>>
>>
>>
>> There is a reference to RFC2617, but not sure why. That seems to 
>> imply that a list of values can be specified, which is not the case.
>>
>>
>>
>> some implementation uses other characters? Using a name value pair 
>> and proper escaping is much safer IMO. For example:
>>

---

From: Mike Jones <[email-masked]>
Date: Wed, 25 May 2011 17:15:28 +0000

What you quoted below was the acceptable syntax.  The Authorization Server and the Resource Server still need to agree upon the semantics of the bearer token exchanged.

				-- Mike

-----Original Message-----
From: John Kemp [mailto:[email-masked]] 
Sent: Wednesday, May 25, 2011 10:11 AM
To: Mike Jones
Cc: Marius Scurtescu; George Fletcher; OAuth WG
Subject: Re: [OAUTH-WG] bearer token authorization header

- John

---

From: George Fletcher <[email-masked]>
Date: Thu, 26 May 2011 11:30:01 -0400

So just to make sure that I'm clear... The following is ok...

    The AS and RO decide that the token will be comprised of both a name
    and value part. So the whole token looks like
    'token=asfd2353fasdfa235q54rdasf'. From the protocol perspective,
    the access token is the entire string, even if it looks like to the
    developer that only the 'asfd2353fasdfa235q54rdasf' part is the
    token. As a developer I find this confusing, but I think I now
    understand why the 'token=asfd2353fasdfa235q54rdasf' is legal.

The key is that the client has to treat the response from the AS as 
opaque (as Paul mentioned) and just put it in the Authorization header 
as 'Authorization: Bearer <token>" regardless of what the resulting 
header looks like.

Thanks,
George

On 5/25/11 1:15 PM, Mike Jones wrote:
>     access-token   = 1*( quoted-char /<">  )
>
>                      / ":" / "<" / "=" /">" / "?" / "@" / ALPHA

---

From: Marius Scurtescu <[email-masked]>
Date: Thu, 26 May 2011 09:15:38 -0700

Maybe I created some confusion. Earlier in the thread I was wondering
why isn't the part after the scheme name a list of name/value pairs.
If it was, then the authorization header would look like:

Bearer token=asfd2353fasdfa235q54rdasf

and the actual token would be just asfd2353fasdfa235q54rdasf, and it
should be encoded as a quoted string if it contained special
characters.

But this is not what the spec currently say. The part after the scheme
name is simply the token, no encoding or names or lists. Also, the
spec defines the set of legal characters that can show up in a token
(this limits what tokens can an AS issue). With the current spec the
header would look like:

Bearer asfd2353fasdfa235q54rdasf

The = character is a legal character inside a token, and it has no
special meaning.

I hope this helps, and I hope I got it right,
Marius

On Thu, May 26, 2011 at 8:30 AM, George Fletcher <[email-masked]> wrote:
> The AS and RO decide that the token will be comprised of both a name and
> value part. So the whole token looks like 'token=asfd2353fasdfa235q54rdasf'.
> From the protocol perspective, the access token is the entire string, even
> if it looks like to the developer that only the 'asfd2353fasdfa235q54rdasf'
> part is the token. As a developer I find this confusing, but I think I now
> The key is that the client has to treat the response from the AS as opaque
> (as Paul mentioned) and just put it in the Authorization header as
> 'Authorization: Bearer <token>" regardless of what the resulting header
> looks like.
>
> Thanks,
> George
>
> What you quoted below was the acceptable syntax.  The Authorization Server
> and the Resource Server still need to agree upon the semantics of the bearer
> token exchanged.
>
>                 -- Mike
>
> George, you are correct that resources and clients must agree upon the
> format of the bearer token to achieve interoperability.  The means for
> achieving this agreement is out of the scope of this document.
>
> I thought the means for achieving IOP was quite precisely described in the
> production below (excerpted from 2.1 of
> http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-04):
>
> The "printable non-whitespace ASCII characters" represents the access token,
> which is supposed to be opaque. I don't think this affects libraries.
>
> Marius
>
>
>

---

From: Mike Jones <[email-masked]>
Date: Thu, 26 May 2011 16:20:21 +0000

You got it right. :-)

-----Original Message-----
From: Marius Scurtescu [mailto:[email-masked]] 
Sent: Thursday, May 26, 2011 9:16 AM
To: George Fletcher
Cc: Mike Jones; John Kemp; OAuth WG
Subject: Re: [OAUTH-WG] bearer token authorization header

Maybe I created some confusion. Earlier in the thread I was wondering why isn't the part after the scheme name a list of name/value pairs.
If it was, then the authorization header would look like:

and the actual token would be just asfd2353fasdfa235q54rdasf, and it should be encoded as a quoted string if it contained special characters.

But this is not what the spec currently say. The part after the scheme name is simply the token, no encoding or names or lists. Also, the spec defines the set of legal characters that can show up in a token (this limits what tokens can an AS issue). With the current spec the header would look like:

The = character is a legal character inside a token, and it has no special meaning.

I hope this helps, and I hope I got it right, Marius

On Thu, May 26, 2011 at 8:30 AM, George Fletcher <[email-masked]> wrote:
> and value part. So the whole token looks like 'token=asfd2353fasdfa235q54rdasf'.
> From the protocol perspective, the access token is the entire string, 
> even if it looks like to the developer that only the 'asfd2353fasdfa235q54rdasf'
> part is the token. As a developer I find this confusing, but I think I 
> now understand why the 'token=asfd2353fasdfa235q54rdasf' is legal.
>
> as
> 'Authorization: Bearer <token>" regardless of what the resulting 
> header looks like.
>
> Thanks,
> George
>
> What you quoted below was the acceptable syntax.  The Authorization 
> Server and the Resource Server still need to agree upon the semantics 
> of the bearer token exchanged.
>
>                 -- Mike
>
> I thought the means for achieving IOP was quite precisely described in 
> the production below (excerpted from 2.1 of
> token, which is supposed to be opaque. I don't think this affects libraries.
>
> Marius
>
>
>

---

From: "William J. Mills" <[email-masked]>
Date: Thu, 26 May 2011 19:22:51 -0700 (PDT)

Yes, in fact one could get annoyingly confusing with tokens here and have...

Authorization: bearer token="asfd2353fasdfa235q54rdasf",plaintext="JSON_GOES_HERE",oauth_signature="mysig"

and the token would be 

     token="asfd2353fasdfa235q54rdasf",plaintext="JSON_GOES_HERE",oauth_signature="mysig"

________________________________
From: Marius Scurtescu <[email-masked]>
To: George Fletcher <[email-masked]>
Cc: OAuth WG <[email-masked]>
Sent: Thursday, May 26, 2011 9:15 AM
Subject: Re: [OAUTH-WG] bearer token authorization header