Subject: Re: [OAUTH-WG] consistency of token param name in bearer token type

From: David Recordon <[email-masked]>
Date: Wed, 1 Jun 2011 00:06:05 -0700

Yeah, can understand how we got here. Just found it quite confusing
when reading these two specifications together with an implementor's
hat on.

On Tue, May 31, 2011 at 12:29 PM, George Fletcher <[email-masked]> wrote:
> Brief pointer to the "history" of this change. This change was adopted in
> draft 4 of the bearer spec as there were concerns with the previous
> parameter name of 'oauth_token'. The suggestion was made to use
> 'bearer_token' so that it matches the scheme used in the Authorization
> header. The thinking being that reading the bearer token spec would seem
> weird if the Authorization header used one name and the GET/POST methods
> used a different name.
>
> The 'bearer_token' name got a few +1 and no dissents.
>
> Full thread starts here [1]. Mike accepting the 'bearer_token'
> recommendation is here [2].
>
> Thanks,
> George
>
> [1] http://www.ietf.org/mail-archive/web/oauth/current/msg05497.html
> [2] http://www.ietf.org/mail-archive/web/oauth/current/msg05881.html
>
> On 5/28/11 12:30 PM, David Recordon wrote:
>
> Did a full read through of draft 16 and the bear token spec with Paul
> yesterday afternoon in order to do a manual diff from draft 10. The
> point Doug raised was actually confusing. Throughout the core spec
> it's referred to as access_token but then becomes bearer_token upon
> use.
>
> Just thinking through this from a developer documentation perspective,
> it's going to become confusing. Developer documentation focuses on
> getting an access token and then using that access token to interact
> with an API. Thus the code you're writing as a client developer will
> use variables, cache keys, and database columns named `access_token`.
> But then when you're going to use it, you'll need to put this access
> token into a field named bearer_token.
>
> Feels quite a bit simpler to just name it access_token. Realize the
> core spec never did this since we didn't want to trample on protected
> resources which might already have a different type of access_token
> parameter. oauth_token was a good compromise since developers would
> already know that they were using OAuth and thus a new term wasn't
> being introduced. That's no longer true with bearer_token since 99% of
> developers will have never heard of a bearer token.
>
> Googling for "bearer token" turns up Eran's blog post titled "OAuth
> Bearer Tokens are a Terrible Idea" and there isn't a single result on
> the first page which explains what they are. Binging for "bearer
> token" is equally scary.
>
> --David
>
>
> On Mon, May 23, 2011 at 11:38 AM, Mike Jones
> <[email-masked]> wrote:
>
> The working group explicitly decided that a different name should be used,
> to make it clear that other token types other than bearer tokens could also
> be used with OAuth 2.
>
>
>
>                                                             -- Mike
>
>
>
> From: [email-masked] [mailto:[email-masked]] On Behalf Of
> Doug Tangren
> Sent: Wednesday, May 11, 2011 10:09 PM
> To: [email-masked]
> Subject: [OAUTH-WG] consistency of token param name in bearer token type
>
>
>
> This may have come up before so I'm sorry if I'm repeating. Why does bearer
> token spec introduce a new name for oauth2 access tokens [1],
> "bearer_token", and before that [2], "oauth_token"?
>
>
>
> I apologize if this may sound shallow but, why introduce a new parameter
> name verses sticking with what the general oauth2 spec already defines,
> "access_token". It seems arbitrary for an auth server to hand a client an
> apple then have the client hand it off to the resource server and call it an
> orange.
>
>
>
> Was this just for the sake of differentiating the parameter name enough so
> that the bearer tokens may be used in other protocols without being confused
> with oauth2 access_tokens?
>
>
>
> [1]: http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-04#section-2.2
>
> [2]: http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-03#section-2.2
>
>
>
> -Doug Tangren
> http://lessis.me
>
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>
>
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>
>
> --
> Chief Architect                   AIM:  gffletch
> Identity Services Engineering     Work: [email-masked]
> AOL Inc.                          Home: [email-masked]
> Mobile: +1-703-462-3494           Blog: http://practicalid.blogspot.com
> Office: +1-703-265-2544           Twitter: http://twitter.com/gffletch
>

---

From: Mike Jones <[email-masked]>
Date: Wed, 1 Jun 2011 20:14:33 +0000

If you can drive a consensus decision for the name "access_token", I'd be glad to change the name in the spec.  I agree that the current names are confusing for developers.

				-- Mike

-----Original Message-----
From: David Recordon [mailto:[email-masked]] 
Sent: Wednesday, June 01, 2011 12:06 AM
To: George Fletcher
Cc: Mike Jones; Doug Tangren; [email-masked]; paul Tarjan
Subject: Re: [OAUTH-WG] consistency of token param name in bearer token type

Yeah, can understand how we got here. Just found it quite confusing when reading these two specifications together with an implementor's hat on.

On Tue, May 31, 2011 at 12:29 PM, George Fletcher <[email-masked]> wrote:
> Brief pointer to the "history" of this change. This change was adopted 
> in draft 4 of the bearer spec as there were concerns with the previous 
> header. The thinking being that reading the bearer token spec would 
> seem weird if the Authorization header used one name and the GET/POST 
> methods used a different name.
>
> The working group explicitly decided that a different name should be 
> used, to make it clear that other token types other than bearer tokens 
> could also be used with OAuth 2.
>
>
>
>                                                             -- Mike
>
>
>
> From: [email-masked] [mailto:[email-masked]] On Behalf 
> Of Doug Tangren
> This may have come up before so I'm sorry if I'm repeating. Why does 
> bearer token spec introduce a new name for oauth2 access tokens [1], 
> I apologize if this may sound shallow but, why introduce a new 
> parameter name verses sticking with what the general oauth2 spec 
> already defines, "access_token". It seems arbitrary for an auth server 
> to hand a client an apple then have the client hand it off to the 
> resource server and call it an orange.
>
>
>
> Was this just for the sake of differentiating the parameter name 
> enough so that the bearer tokens may be used in other protocols 
> without being confused with oauth2 access_tokens?
>
>
>
> [1]: 
> http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-04#section-2.2
>
> [2]: 
> http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-03#section-2.2
>
>
>
> -Doug Tangren
> http://lessis.me
>

---

From: Justin Richer <[email-masked]>
Date: Mon, 6 Jun 2011 16:23:20 -0400

The biggest problem that I can see are the examples and terminology in
the core doc, which tries very hard to not look like it is binding to
any particular use-a-token spec or token format. That plus the history
that George pointed out below (which I still very strongly believe that
'oauth_token' should not be used as that's been claimed by OAuth1) got
us here today. 

One of the downsides to splitting this into three specs is that we need
to be more consistent across them.

 -- Justin

---

From: Marius Scurtescu <[email-masked]>
Date: Wed, 8 Jun 2011 16:50:07 -0700

> If you can drive a consensus decision for the name "access_token", I'd be glad to change the name in the spec.  I agree that the current names are confusing for developers.

At Google we are getting the same feedback, that it is confusing for
developers. It would definitely help if we could change the name to
"access_token".

Marius

---

From: David Recordon <[email-masked]>
Date: Fri, 10 Jun 2011 01:20:17 -0700

George, Doug and Eran are you alright with the Bearer token spec using
the parameter name "access_token" as well?

---

From: George Fletcher <[email-masked]>
Date: Fri, 10 Jun 2011 07:58:31 -0400

Yes, that's fine with me.

Thanks,
George

On 6/10/11 4:20 AM, David Recordon wrote:
> On Wed, Jun 8, 2011 at 4:50 PM, Marius Scurtescu<[email-masked]>  wrote:
>> On Wed, Jun 1, 2011 at 1:14 PM, Mike Jones<[email-masked]>  wrote:

---

From: John Kemp <[email-masked]>
Date: Fri, 10 Jun 2011 15:35:50 +0300

What does this mean for the HTTP Authorization header naming scheme for bearer tokens?

As I understand this decision, we are discussing whether to standardize on the name "access_token" when a bearer token is sent as either a URL query parameter, or in a form POSTed body? 

Currently the HTTP Authorization header looks like this (from http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-05):

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer vF9dft4qmT

Is the proposal then that we have:

1. GET /resource?access_token=vF9dft4qmT
2. POST /resource

access_token=vF9dft4qmT&...

3. 

GET /resource HTTP/1.1
Host: server.example.com
Authorization: access_token vF9dft4qmT

Can someone actually give the details of the proposal, or agree/disagree with the examples above?

- John

On Jun 10, 2011, at 2:58 PM, George Fletcher wrote:

>> On Wed, Jun 8, 2011 at 4:50 PM, Marius Scurtescu 
>> <[email-masked]>
>>  wrote:
>>

---

From: George Fletcher <[email-masked]>
Date: Fri, 10 Jun 2011 09:11:28 -0400

I definitely don't want to change the Authorization header naming 
scheme. I believe it should stay 'Bearer' because that's what the token 
is. We could make it...

Authorization: Bearer access_token=vF9dft4qmT

If that helps with consistency. I don't think we should be associating 
the term 'access_token' with the bearer security mechanism.

Thanks,
George

---

From: Doug Tangren <[email-masked]>
Date: Fri, 10 Jun 2011 09:23:11 -0400

-Doug Tangren
http://lessis.me

> the parameter name "access_token" as well?
Consistency is good and less confusing for developers writing generic client
libraries.
+1. I hope hope that if it changes again this time, it doesn't change again
:)!

---

From: George Fletcher <[email-masked]>
Date: Fri, 10 Jun 2011 09:50:00 -0400

+1 :)

On 6/10/11 9:23 AM, Doug Tangren wrote:
>
> I hope hope that if it changes again this time, it doesn't change 
> again :)!

---

From: John Kemp <[email-masked]>
Date: Fri, 10 Jun 2011 19:34:03 +0300

George,

On Jun 10, 2011, at 4:11 PM, George Fletcher wrote:

> I definitely don't want to change the Authorization header naming scheme. I believe it should stay 'Bearer' because that's what the token is. We could make it...
> 
> If that helps with consistency.

Well, it might seem more consistent, but I'm not sure it's worthwhile to make the change just for that reason. 

Is it possible that the Bearer HTTP mechanism would ever take multiple parameters? In which case, having the ability to name the parameters of the Bearer mechanism might become more interesting.

- John

> I don't think we should be associating the term 'access_token' with the bearer security mechanism.
> 
> Thanks,
> George
> 
>> Currently the HTTP Authorization header looks like this (from 
>> http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-05
>> ):
>> 
>> GET /resource HTTP/1.1
>> Host: server.example.com
>>>>> On Wed, Jun 1, 2011 at 1:14 PM, Mike Jones <[email-masked]>
>>>>> 
>>>>> wrote:
>>>>> 
>>>>>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 10 Jun 2011 09:40:50 -0700

Don't care. Will never use it. :-)

EHL

> Sent: Friday, June 10, 2011 1:20 AM
> To: George Fletcher; Eran Hammer-Lahav; Doug Tangren
> Cc: Mike Jones; paul Tarjan; [email-masked]; Marius Scurtescu
> George, Doug and Eran are you alright with the Bearer token spec using the
> parameter name "access_token" as well?
> 
> 
> <[email-masked]> wrote:
> >> If you can drive a consensus decision for the name "access_token", I'd be
> glad to change the name in the spec.  I agree that the current names are
> confusing for developers.
> >

---

From: David Recordon <[email-masked]>
Date: Fri, 10 Jun 2011 09:45:54 -0700

I think it's vital to have the GET and POST parameters make sense to
every developer. I worry less about the authorization header since a
developer implementing it will honestly be a stronger engineer.

--David

---

From: Marius Scurtescu <[email-masked]>
Date: Fri, 10 Jun 2011 10:38:35 -0700

> Is it possible that the Bearer HTTP mechanism would ever take multiple parameters? In which case, having the ability to name the parameters of the Bearer mechanism might become more interesting.

Hard to say, but using a proper name/value pair has several advantages:
- permits extensibility
- no need to limit or define character set of access tokens (name is
either "token" or "quoted string")
- HTTP header parsers can properly deal with name/value pairs

If we make changes to the GET/POST parameter name then I think we
should also consider the header as well.

Marius

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 10 Jun 2011 15:17:42 -0700

Extensibility in authentication schemes is a bad thing, given how they are deployed and the difficulty of changing them. No existing authentication scheme is extensible (explicitly).

EHL

> Of Marius Scurtescu
> Sent: Friday, June 10, 2011 10:39 AM
> To: John Kemp
> Cc: paul Tarjan; OAuth WG
> scheme. I believe it should stay 'Bearer' because that's what the token is. We
> could make it...
> >>
> > Is it possible that the Bearer HTTP mechanism would ever take multiple
> parameters? In which case, having the ability to name the parameters of the
> Bearer mechanism might become more interesting.
> 
> - no need to limit or define character set of access tokens (name is either
> "token" or "quoted string")

---

From: Stephen Farrell <[email-masked]>
Date: Sat, 11 Jun 2011 13:12:16 +0100

> Extensibility in authentication schemes is a bad thing, given how they are deployed and the difficulty of changing them. No existing authentication scheme is extensible (explicitly).

Maybe that statement is a tad too general? [1]

S.

[1] http://tools.ietf.org/html/rfc3748

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Sat, 11 Jun 2011 09:35:05 -0700

I meant HTTP authentication scheme (given the topic, that was implied).

EHL

> From: Stephen Farrell [mailto:[email-masked]]
> Sent: Saturday, June 11, 2011 5:12 AM
> To: Eran Hammer-Lahav
> Cc: Marius Scurtescu; John Kemp; paul Tarjan; OAuth WG
> > Extensibility in authentication schemes is a bad thing, given how they are
> deployed and the difficulty of changing them. No existing authentication
> scheme is extensible (explicitly).
> 
> >> From: [email-masked] [mailto:[email-masked]] On
> >> Behalf Of Marius Scurtescu
> >> scheme. I believe it should stay 'Bearer' because that's what the
> >> token is. We could make it...
> >>>>
> >>> Well, it might seem more consistent, but I'm not sure it's
> >>> worthwhile to
> >> make the change just for that reason.
> >>>
> >> parameters? In which case, having the ability to name the parameters
> >> of the Bearer mechanism might become more interesting.
> >>

---

From: Bill <[email-masked]>
Date: Tue, 14 Jun 2011 16:12:16 +0100

> developer implementing it will honestly be a stronger engineer.

I agree with David regardless of engineering strength, this is going to 
be confusing to developers. Also tho', devs are exposed to the access 
token response, not just the GET/POST bits. So ideally syntax would line 
up with how the token is obtained 
http://tools.ietf.org/html/draft-ietf-oauth-v2-16#section-5.1 and not 
just across requests using the token.

A possible clarifying change is to use something like "bearer_token" end 
to end.

[[[
{
        "access_token":"vF9dft4qmT",
        "token_type":"bearer_token", /* ? */
...
}

GET /resource HTTP/1.1
Host: server.example.com
Authorization: bearer_token vF9dft4qmT

GET /resource?bearer_token=vF9dft4qmT&...
Host: server.example.com

POST /resource
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

&bearer_token=vF9dft4qmT&...

HTTP/1.1 401 Unauthorized
WWW-Authenticate: bearer_token realm="example"
]]]

Bill

> On Fri, Jun 10, 2011 at 9:34 AM, John Kemp<[email-masked]>  wrote:
>> George,
>>
>>>>>>> On Wed, Jun 1, 2011 at 1:14 PM, Mike Jones<[email-masked]>
>>>>>>>
>>>>>>> wrote:
>>>>>>>
>>>>>>>

---

From: David Recordon <[email-masked]>
Date: Tue, 14 Jun 2011 18:30:15 -0700

Bearer token doesn't exist within the core spec around getting an
access token. The term that is used is "access token".

On Tue, Jun 14, 2011 at 8:12 AM, Bill <[email-masked]> wrote:
> I agree with David regardless of engineering strength, this is going to be
> confusing to developers. Also tho', devs are exposed to the access token
> response, not just the GET/POST bits. So ideally syntax would line up with
> how the token is obtained
> http://tools.ietf.org/html/draft-ietf-oauth-v2-16#section-5.1 and not just
> across requests using the token.
>
> A possible clarifying change is to use something like "bearer_token" end to
> end.
>
> [[[
> {
>>>> scheme. I believe it should stay 'Bearer' because that's what the token is.
>>>> We could make it...
>>>>
>>>>> As I understand this decision, we are discussing whether to standardize
>>>>> on the name "access_token" when a bearer token is sent as either a URL query
>>>>> parameter, or in a form POSTed body?
>>>>>
>>>>>>>>> If you can drive a consensus decision for the name "access_token",
>>>>>>>>> I'd be glad to change the name in the spec.  I agree that the current names
>>>>>>>>> are confusing for developers.
>>>>>>>>>
>>>>>>>>>

---

From: Bill <[email-masked]>
Date: Wed, 15 Jun 2011 09:46:05 +0100

> access token. The term that is used is "access token".

Right, I get that Bearer is defined in another draft document (which the 
core spec references and probably should not btw, that's confusing as well)

 >> "token_type":"Bearer"

I was referring to bearer token wrt token_type. The above is how I 
understand one will be supplied.

Bill

>
>
> On Tue, Jun 14, 2011 at 8:12 AM, Bill<[email-masked]>  wrote:

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 15 Jun 2011 10:38:26 -0700

It should be pretty easy :-)

Anyone objects to changing the parameter name from 'bearer_token' to 'access_token'? Let Mike know by 6/20 or he will make the change.

EHL

> Of Mike Jones
> Sent: Wednesday, June 01, 2011 1:15 PM
> To: David Recordon; George Fletcher
> Cc: paul Tarjan; [email-masked]
> Yeah, can understand how we got here. Just found it quite confusing when
> reading these two specifications together with an implementor's hat on.
>

---

From: John Bradley <[email-masked]>
Date: Wed, 15 Jun 2011 14:04:13 -0400

I agree access_token is better.

John B.

---

From: "William J. Mills" <[email-masked]>
Date: Wed, 15 Jun 2011 13:24:55 -0700 (PDT)

Makes sense to me.

________________________________
From: John Bradley <[email-masked]>
To: Eran Hammer-Lahav <[email-masked]>
Cc: paul Tarjan <[email-masked]>; "[email-masked]" <[email-masked]>
Sent: Wednesday, June 15, 2011 11:04 AM
Subject: Re: [OAUTH-WG] consistency of token param name in bearer token type

John B.

---

From: "Lodderstedt, Torsten" <[email-masked]>
Date: Thu, 16 Jun 2011 10:25:32 +0200

The reason why I suggested the name "bearer_token" was to achieve a consistent naming convention across different ways to uses those tokens (URI query, HTTP authn scheme). Now the discussion centers around achieving a consistent naming between token acquisition and usage. I'm basically fine with reverting to "access_token".

Just one question: 
Is the assumption of the group that bearer tokens are the only type of tokens to be used in conjunction with URI query parameters? Otherwise, a mechanism is needed to distinguish bearer and other tokens, e.g. another parameter (token_type?).

Regards,
Torsten.
> -----Ursprüngliche Nachricht-----
> Von: Eran Hammer-Lahav [mailto:[email-masked]]
> Gesendet: Mittwoch, 15. Juni 2011 19:38
> An: Mike Jones; David Recordon; George Fletcher
> Betreff: Re: [OAUTH-WG] consistency of token param name in bearer token
> type
> 
> Anyone objects to changing the parameter name from 'bearer_token' to
> 'access_token'? Let Mike know by 6/20 or he will make the change.
> 
> EHL
> 
> 
> Behalf
> > Subject: Re: [OAUTH-WG] consistency of token param name in bearer
> token
> > type
> >
> I'd be
> > Subject: Re: [OAUTH-WG] consistency of token param name in bearer
> token
> > type
> >
> when
> Behalf

---

From: "KIHARA, Boku" <[email-masked]>
Date: Thu, 16 Jun 2011 21:40:34 +0900

+1 to access_token.

---

From: Doug Tangren <[email-masked]>
Date: Thu, 16 Jun 2011 09:38:12 -0400

-Doug Tangren
http://lessis.me

Just one question:
> Is the assumption of the group that bearer tokens are the only type of
> tokens to be used in conjunction with URI query parameters? Otherwise, a
> mechanism is needed to distinguish bearer and other tokens, e.g. another
> parameter (token_type?).
>
>
I thought the idea was that token_type was a way to define general
extensions which define protocols to provide access_tokens to resources
servicers.

I think its up to the provider of access_tokens to document which of these
token_types they support and how to distinguish them if there are multiple
token_types what use access_tokens in query parameters. I think its up to
the extension authors to provide a consistent naming scheme with the base
oauth2's defined vocabulary.

Where it gets confusing, is when multiple token_type extensions all use
different vocabulary for roughly the same thing. I say that in regards to
the naming of query parameters.

---

From: Justin Richer <[email-masked]>
Date: Thu, 16 Jun 2011 10:01:07 -0400

If we're changing the bearer token's name, are we going to change the
parameter name inside of MAC as well? At the moment, it's "id", which
I've always found an odd naming choice.

I would argue for consistency across the three main documents.

 -- Justin

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 16 Jun 2011 08:29:59 -0700

> From: Lodderstedt, Torsten [mailto:[email-masked]]
> Sent: Thursday, June 16, 2011 1:26 AM
> To: Eran Hammer-Lahav; Mike Jones; David Recordon; George Fletcher
> Subject: AW: [OAUTH-WG] consistency of token param name in bearer
> token type
> 
> The reason why I suggested the name "bearer_token" was to achieve a
> consistent naming convention across different ways to uses those tokens
> (URI query, HTTP authn scheme). Now the discussion centers around
> achieving a consistent naming between token acquisition and usage. I'm
> basically fine with reverting to "access_token".
> 
> Just one question:

YES (i.e. no more). It's bad enough we have this one.

EHL

> > Betreff: Re: [OAUTH-WG] consistency of token param name in bearer
> > token type
> >
> > > > header. The thinking being that reading the bearer token spec
> > > > would seem weird if the Authorization header used one name and the
> > GET/POST
> > > > yesterday afternoon in order to do a manual diff from draft 10.
> > > > The point Doug raised was actually confusing. Throughout the core
> > > > spec it's referred to as access_token but then becomes
> > > > bearer_token upon use.
> > > >
> > > > Feels quite a bit simpler to just name it access_token. Realize
> > > > the core spec never did this since we didn't want to trample on
> > protected
> > > > resources which might already have a different type of
> > > > access_token parameter. oauth_token was a good compromise since
> > > > developers would already know that they were using OAuth and thus
> > > > a new term wasn't being introduced. That's no longer true with
> > > > bearer_token since 99%
> > of
> > > > Googling for "bearer token" turns up Eran's blog post titled
> > > > "OAuth Bearer Tokens are a Terrible Idea" and there isn't a single
> > > > result
> > on
> > > > Mike

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 16 Jun 2011 08:31:06 -0700

Nope. OAuth is a secondary goal of the MAC scheme and calling it access_token there would make no sense for anything but OAuth. 

EHL

> From: Justin Richer [mailto:[email-masked]]
> Sent: Thursday, June 16, 2011 7:01 AM
> To: KIHARA, Boku
> Cc: Eran Hammer-Lahav; [email-masked]
> parameter name inside of MAC as well? At the moment, it's "id", which I've
> always found an odd naming choice.
> 
> > >> Behalf Of Mike Jones
> > >> I'd be glad to change the name in the spec.  I agree that the
> > >> current names are confusing for developers.
> > >>
> > >>                               -- Mike
> > >>
> > >> On Tue, May 31, 2011 at 12:29 PM, George Fletcher
> > >> <[email-masked]>
> > >> wrote:
> > >> > Brief pointer to the "history" of this change. This change was
> > >> > adopted in draft 4 of the bearer spec as there were concerns with
> > >> > the previous parameter name of 'oauth_token'. The suggestion was
> > >> > made to use 'bearer_token' so that it matches the scheme used in
> > >> > the Authorization header. The thinking being that reading the
> > >> > bearer token spec would seem weird if the Authorization header
> > >> > used one name and the GET/POST methods used a different name.
> > >> >
> > >> > [1]
> > >> > http://www.ietf.org/mail-archive/web/oauth/current/msg05497.html
> > >> > [2]
> > >> > http://www.ietf.org/mail-archive/web/oauth/current/msg05881.html
> > >> >
> > >> > Did a full read through of draft 16 and the bear token spec with
> > >> > Paul yesterday afternoon in order to do a manual diff from draft
> > >> > 10. The point Doug raised was actually confusing. Throughout the
> > >> > core spec it's referred to as access_token but then becomes
> > >> > bearer_token upon use.
> > >> >
> > >> > Just thinking through this from a developer documentation
> > >> > perspective, it's going to become confusing. Developer
> > >> > documentation focuses on getting an access token and then using
> > >> > that access token to interact with an API. Thus the code you're
> > >> > writing as a client developer will use variables, cache keys, and
> database columns named `access_token`.
> > >> > But then when you're going to use it, you'll need to put this
> > >> > access token into a field named bearer_token.
> > >> >
> > >> > protected resources which might already have a different type of
> > >> > bearer_token since 99% of developers will have never heard of a
> bearer token.
> > >> >
> > >> > "OAuth Bearer Tokens are a Terrible Idea" and there isn't a
> > >> > single result on the first page which explains what they are.
> > >> > Binging for "bearer token" is equally scary.
> > >> >
> > >> > --David
> > >> >
> > >> >
> > >> > The working group explicitly decided that a different name should
> > >> > be used, to make it clear that other token types other than
> > >> > bearer tokens could also be used with OAuth 2.
> > >> >
> > >> >
> > >> >
> > >> >                                                             --
> > >> > Mike
> > >> >
> > >> >
> > >> >
> > >> > Behalf Of Doug Tangren
> > >> > This may have come up before so I'm sorry if I'm repeating. Why
> > >> > does bearer token spec introduce a new name for oauth2 access
> > >> > tokens [1], "bearer_token", and before that [2], "oauth_token"?
> > >> >
> > >> >
> > >> >
> > >> > already defines, "access_token". It seems arbitrary for an auth
> > >> > server to hand a client an apple then have the client hand it off
> > >> > to the resource server and call it an orange.
> > >> >
> > >> >
> > >> >

---

From: Torsten Lodderstedt <[email-masked]>
Date: Thu, 16 Jun 2011 21:48:11 +0200

token_type is defined in the core spec only and indicates the token type 
to the client and not the resource server.

So either the core spec defines a way to distinguish token types towards 
resource servers (probably by utilizing the token_type parameter) or the 
respective schemes (BEARER, MAC) define ways to recognize the differences.

regards,
Torsten.

Am 16.06.2011 15:38, schrieb Doug Tangren:
>
> -Doug Tangren
> http://lessis.mehe
>
>
>     Just one question:
>     Is the assumption of the group that bearer tokens are the only
>     type of tokens to be used in conjunction with URI query
>     parameters? Otherwise, a mechanism is needed to distinguish bearer
>     and other tokens, e.g. another parameter (token_type?).
>
>
> extensions which define protocols to provide access_tokens to 
> resources servicers.
>
> I think its up to the provider of access_tokens to document which of 
> these token_types they support and how to distinguish them if there 
> are multiple token_types what use access_tokens in query parameters. I 
> think its up to the extension authors to provide a consistent naming 
> scheme with the base oauth2's defined vocabulary.
>
> Where it gets confusing, is when multiple token_type extensions all 
> use different vocabulary for roughly the same thing. I say that in 
> regards to the naming of query parameters.
>
>

---

From: "Manger, James H" <[email-masked]>
Date: Fri, 17 Jun 2011 10:40:36 +1000

> I would argue for consistency across the three main documents.

OAuth2 should be consistent with the authentication schemes for which it dynamically issues credentials - not the other way around.

The root cause of the naming inconsistencies is that OAuth2 puts a massive focus on "Access Token", instead of on "Dynamically-issued credentials".

An "access token response" is a dynamically-issued credential. First you need to know the type of credential (token_type), then you need any extra values specific to that type. [Plus you need metadata about the credentials (expires_in, scope, how/where to renew/revoke, where to use!!).]

For the BEARER type you need: token.
For the MAC type you need: id, key, algorithm, issue time.
For the BASIC type you need: username, password.
For the TLS client cert type you need: certificate, private key.
...

The MAC spec defines mac_key and mac_algorithm fields, but uses the access_token label instead of defining a mac_id field. It has to because OAuth2 treats access_token as a central concept, instead of a credential-specific field.

I am sure developers would more easily understand (get a better mental model) if an "access token responses" looked like the following examples:
 {"type":"bearer", "token":"SlAV32hkKG", ...}
 {"type":"mac", "id":"SlAV32hkKG", "key":"adijq39jdlaska9asud", "algorithm":"hmac-sha-256", ...}

Is it worth clarifying?
Probably, for clarity in the long term.
But obviously there has been a huge amount invested in the current "access token" focus. I am certainly not going to object to the much simpler fix of renaming bearer_token to access_token.

--
James Manger