Subject: [OAUTH-WG] OK to post updated Bearer spec changing and adding examples?

From: Mike Jones <[email-masked]>
Date: Sat, 10 Mar 2012 17:52:08 +0000

OAuth Chairs,

Do you approve of posting an updated Bearer spec as below, assuming the working group does not object by mid-day Monday?

                                                            -- Mike

From: Mike Jones
Sent: Saturday, March 10, 2012 9:50 AM
To: 'Paul Madsen'; Brian Campbell
Cc: oauth
Subject: RE: [OAUTH-WG] question about the b64token syntax in draft-ietf-oauth-v2-bearer

I plan to make the change to the example access token value to mF_9.B5f-4.1JqM before Monday's submission deadline, per the requests for b64token syntax clarification.  I'm also considering adding an access token response example, pre the requests in this thread.  I would propose adding the following new text for this in a new Section 4 (before the current Security Considerations).  This is largely parallel to what is done in Section 5.1 of the MAC spec.

4.  Example Access Token Response

Typically a bearer token is returned to the client as part of an OAuth 2.0 [I-D.ietf-oauth-v2] access token response. An example of such as response is:

     HTTP/1.1 200 OK

     Content-Type: application/json;charset=UTF-8

     Cache-Control: no-store

     Pragma: no-cache

     {

       "access_token":"mF_9.B5f-4.1JqM",

       "token_type":"Bearer",

       "expires_in":3600,

       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"

     }

Please send either +1s or objections to this text by mid-day Monday.  Unless I receive several +1s, to be conservative at this point, I will not be including it in Monday's draft.

                                                            -- Mike

From: [email-masked]<mailto:[email-masked]> [mailto:[email-masked]]<mailto:[mailto:[email-masked]]> On Behalf Of Paul Madsen
Sent: Wednesday, March 07, 2012 1:34 PM
To: Brian Campbell
Cc: oauth
Subject: Re: [OAUTH-WG] question about the b64token syntax in draft-ietf-oauth-v2-bearer

+1

On 3/7/12 4:08 PM, Brian Campbell wrote:

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]><mailto:[email-masked]> wrote:

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:

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]><mailto:[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

________________________________

From: Brian Campbell<[email-masked]><mailto:[email-masked]>

To: Mike Jones<[email-masked]><mailto:[email-masked]>

Cc: oauth<[email-masked]><mailto:[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

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?

On Mon, Mar 5, 2012 at 5:32 PM, Mike Jones<[email-masked]><mailto:[email-masked]>

wrote:

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]> [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,

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?

Yes.

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.

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.

Also, does the use of b64token implicitly limit the allowed characters

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

Yes.

* 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

--

James Manger

_______________________________________________

OAuth mailing list

[email-masked]<mailto:[email-masked]>

https://www.ietf.org/mailman/listinfo/oauth

_______________________________________________

OAuth mailing list

[email-masked]<mailto:[email-masked]>

https://www.ietf.org/mailman/listinfo/oauth

_______________________________________________

OAuth mailing list

[email-masked]<mailto:[email-masked]>

https://www.ietf.org/mailman/listinfo/oauth

_______________________________________________

OAuth mailing list

[email-masked]<mailto:[email-masked]>

https://www.ietf.org/mailman/listinfo/oauth

---

From: Barry Leiba <[email-masked]>
Date: Sat, 10 Mar 2012 12:58:44 -0500

> OAuth Chairs,

Changed CC address; please see my list message:
http://www.ietf.org/mail-archive/web/oauth/current/msg08531.html

> Do you approve of posting an updated Bearer spec as below, assuming the
> working group does not object by mid-day Monday?

Yes, that makes sense.

Barry, still chairing for a short time yet

------------------------------------------------------------------------------------------------------
From: Mike Jones
Sent: Saturday, March 10, 2012 9:50 AM
To: 'Paul Madsen'; Brian Campbell
Cc: oauth
Subject: RE: [OAUTH-WG] question about the b64token syntax in
draft-ietf-oauth-v2-bearer

I plan to make the change to the example access token value to
mF_9.B5f-4.1JqM before Monday’s submission deadline, per the requests
for b64token syntax clarification.  I’m also considering adding an
access token response example, pre the requests in this thread.  I
would propose adding the following new text for this in a new Section
4 (before the current Security Considerations).  This is largely
parallel to what is done in Section 5.1 of the MAC spec.

Typically a bearer token is returned to the client as part of an OAuth
2.0 [I-D.ietf-oauth-v2] access token response. An example of such as
response is:

     HTTP/1.1 200 OK

     Cache-Control: no-store

     Pragma: no-cache

     {

       "token_type":"Bearer",

       "expires_in":3600,

     }

Please send either +1s or objections to this text by mid-day Monday.
Unless I receive several +1s, to be conservative at this point, I will
not be including it in Monday’s draft.

                                                            -- Mike

From: [email-masked] [mailto:[email-masked]] On Behalf
Of Paul Madsen
Sent: Wednesday, March 07, 2012 1:34 PM
To: Brian Campbell
Cc: oauth
Subject: Re: [OAUTH-WG] question about the b64token syntax in
draft-ietf-oauth-v2-bearer

+1

     HTTP/1.1 200 OK

     Cache-Control: no-store

     Pragma: no-cache

     {

       "token_type":"example",

       "expires_in":3600,

     }

On Wed, Mar 7, 2012 at 12:00 PM, Justin Richer <[email-masked]> wrote:

    OAuth-v2-23 section 5.1.

     -- Justin

        draft.

        resource requests.

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

        this:

        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

            From: Brian Campbell<[email-masked]>

            To: Mike Jones<[email-masked]>

            Cc: oauth<[email-masked]>

            However I think that including some text along the lines
of what James

            that the implications of the b64token syntax, particularly
on what AS

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

            agree?

            On Mon, Mar 5, 2012 at 5:32 PM, Mike
Jones<[email-masked]>

            wrote:

                I'm fine with changing the example to make it clearer
that b64token

                allows

                base64url

                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

                Brian,

                    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

                Yes.

                    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

                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:

                to

                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

                    Also, does the use of b64token implicitly limit
the allowed characters

                Yes.

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

                    **

                --

                James Manger