The OAuth 2.0 Authorization Framework: Bearer Token Usage
draft-ietf-oauth-v2-bearer-23

[Ballot comment]
(I understand that the W3C has review use of the access_token as a general query parameter. Thanks for taking care of that.)

In section 2.3, the new last paragraph starts:

    This method is included to document current use; its use is NOT
    RECOMMENDED...

NOT RECOMMENDED is not defined by 2119, and the language is redundant with the previous paragraph and potentially confusing. I suggest replacing it with simply:

    This method is included to document current use; as indicated
    in the previous paragraph, the use of this method is not
    recommended...

BTW: The "SHOULD NOT unless..." in the previous paragraph is itself redundant. I think you mean "MUST NOT unless...". SHOULD NOT *means* MUST NOT unless you understand what you're doing.

Mark Nottingham's Applications Area review  has a couple of comments that I think deserve further reply:

* Section 1: Introduction

The introduction explains oauth, but it doesn't fully explain the
relationship of this specification to OAuth 2.0. E.g., can it be
used independently from the rest of OAuth? Likewise, the overview
(section 1.3) seems more specific to the OAuth specification than
this document. As I read it, this mechanism could be used for ANY
bearer token, not just one generated through OAuth flows.

If it is indeed more general, I'd recommend minimising the
discussion of OAuth, perhaps even removing it from the document
title.

I agree that the title would be better simply as "HTTP Bearer Tokens", and then explain in the Abstract and Intro that the motivation and intended use of these Bearer Tokens is the OAuth 2.0 specification. A possibly useful side effect of this change might be that you can make OAuth 2.0 an informative (as against a normative) reference, and that these things could be reused for other purposes in the future. Not a huge deal, but I (like Mark) was unconvinced that the reference to OAuth in the title was necessary.

* Section 3 The WWW-Authenticate Response Header Field

The difference between a realm and a scope is not explained. Are the
functionally equivalent, just a single value vs. a list?

Some text, and probably an example, might help explain this a bit better.

One of his comments asked for some additional review. I don't have a personal opinion whether this is needed, but perhaps you should pursue this:

* General

The draft currently doesn't mention whether Bearer is suitable for
use as a proxy authentication scheme. I suspect it *may*; it would
be worth discussing this with some proxy implementers to gauge their
interest (e.g., Squid).

IANA has reviewed draft-ietf-oauth-v2-bearer and has the following comments:

Some of the IANA actions requested in this document are dependent upon
the approval of another Internet-Draft: ietf-oauth-v2

IANA understands that, upon approval of this document, IANA will perform the
following actions - depending on the approval of ietf-oauth-v2 which creates
new registries.

First, in the new OAuth Access Token Type Registry (created by ietf-oauth-v2),
IANA will register the following OAuth Access Token Type:

Type name: Bearer
Additional Token Endpoint Response Parameters: (none)
HTTP Authentication Scheme(s): Bearer
Change controller: IETF
Reference: [ RFC-to-be ]

Second, in the new OAuth Extensions Error Registry (created by ietf-oauth-v2),
IANA will register the following OAuth Extensions Errors:

Error name: invalid_request
Error usage location: Resource access error response
Related protocol extension: Bearer access token type
Change controller: IETF
Specification document(s): [ RFC-to-be ]

Error name: invalid_token
Error usage location: Resource access error response
Related protocol extension: Bearer access token type
Change controller: IETF
Specification document(s): [ RFC-to-be ]

Error name: insufficient_scope
Error usage location: Resource access error response
Related protocol extension: Bearer access token type
Change controller: IETF
Specification document(s): [ RFC-to-be ]

Third, in the new OAuth Authentication Scheme Registry (created by
ietf-oauth-v2), IANA will register the following OAuth Authentication Scheme:

Authentication Scheme Name: Bearer
Reference: [ RFC-to-be ]
Notes (optional): (none)

IANA understands that these three actions are the only actions required upon approval of this document.

Note: The actions requested in this document will not be completed until the document has been approved for publication as an RFC.  This message is only to confirm what actions will be performed.

The following Last Call announcement was sent out:

From: The IESG
To: IETF-Announce
CC:
Reply-To: ietf@ietf.org
Subject: Last Call:  (The OAuth 2.0 Authorization Framework: Bearer Token Usage) to Proposed Standard


The IESG has received a request from the Web Authorization Protocol WG
(oauth) to consider the following document:
- 'The OAuth 2.0 Authorization Framework: Bearer Token Usage'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2012-06-27. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

This 2nd IETF LC is due to an IPR declartion being made after
the previous IETF LC - a reviewer noticed some IPR and did the
right thing and made a declaration.

Abstract


  This specification describes how to use bearer tokens in HTTP
  requests to access OAuth 2.0 protected resources.  Any party in
  possession of a bearer token (a "bearer") can use it to get access to
  the associated resources (without demonstrating possession of a
  cryptographic key).  To prevent misuse, bearer tokens need to be
  protected from disclosure in storage and in transport.

* There is a normative reference to RFC 2246 (TLS 1.0), which has been
obsoleted by RFC 5246 (TLS 1.2).  The document uses this reference to
note that TLS 1.0 is, at this writing, the most widely deployed
version.  The working group believes it is necessary to note that, and
that the reference be normative.

The file can be obtained via
http://datatracker.ietf.org/doc/draft-ietf-oauth-v2-bearer/

IESG discussion can be tracked via
http://datatracker.ietf.org/doc/draft-ietf-oauth-v2-bearer/ballot/


The following IPR Declarations may be related to this I-D:

  http://datatracker.ietf.org/ipr/1752/

[Ballot discuss]
Mark Nottingham's Applications Area review  identified the issue of URI query parameters in section 2.3: URI query parameters are normally locally scoped. In this document, a query parameter (access_token) is being defined as applying to all URIs. This is (relatively) novel. A few people in the HTTP community (including Mark) have expressed concerns. (See also http://www.ietf.org/mail-archive/web/apps-discuss/current/msg04932.html and http://www.ietf.org/mail-archive/web/apps-discuss/current/msg04933.html from the apps-discuss archive.) This issue should probably be further reviewed by W3C folks. I'm holding the DISCUSS as per Stephen to make sure we get that review.

[Ballot comment]
In section 2.3, the new last paragraph starts:

    This method is included to document current use; its use is NOT
    RECOMMENDED...

NOT RECOMMENDED is not defined by 2119, and the language is redundant with the previous paragraph and potentially confusing. I suggest replacing it with simply:

    This method is included to document current use; as indicated
    in the previous paragraph, the use of this method is not
    recommended...

BTW: The "SHOULD NOT unless..." in the previous paragraph is itself redundant. I think you mean "MUST NOT unless...". SHOULD NOT *means* MUST NOT unless you understand what you're doing.

Mark Nottingham's Applications Area review  has a couple of comments that I think deserve further reply:

* Section 1: Introduction

The introduction explains oauth, but it doesn't fully explain the
relationship of this specification to OAuth 2.0. E.g., can it be
used independently from the rest of OAuth? Likewise, the overview
(section 1.3) seems more specific to the OAuth specification than
this document. As I read it, this mechanism could be used for ANY
bearer token, not just one generated through OAuth flows.

If it is indeed more general, I'd recommend minimising the
discussion of OAuth, perhaps even removing it from the document
title.

I agree that the title would be better simply as "HTTP Bearer Tokens", and then explain in the Abstract and Intro that the motivation and intended use of these Bearer Tokens is the OAuth 2.0 specification. A possibly useful side effect of this change might be that you can make OAuth 2.0 an informative (as against a normative) reference, and that these things could be reused for other purposes in the future. Not a huge deal, but I (like Mark) was unconvinced that the reference to OAuth in the title was necessary.

* Section 3 The WWW-Authenticate Response Header Field

The difference between a realm and a scope is not explained. Are the
functionally equivalent, just a single value vs. a list?

Some text, and probably an example, might help explain this a bit better.

One of his comments asked for some additional review. I don't have a personal opinion whether this is needed, but perhaps you should pursue this:

* General

The draft currently doesn't mention whether Bearer is suitable for
use as a proxy authentication scheme. I suspect it *may*; it would
be worth discussing this with some proxy implementers to gauge their
interest (e.g., Squid).

[Ballot discuss]
Based on -19.  I'll retain the original #ing.  New text is included after .

10) s3.1: Shouldn't the character set restrictions on error, error_description, and error_uri be in draft-ietf-oauth-v2?



> Yes, I believe these same restrictions should be present in the Core
> spec. Unfortunately, they aren’t at present, I think in part, because
> the “error”, “error_description”, and “error_uri” errors there are used
> in a different protocol contexts where it’s easier to use non-ASCII
> characters. (The Core spec specifies UTF-8 encoding for
> error_description, for instance, rather than limiting it to the ASCII
> subset in the Bearer spec.) I believe it would increase consistency and
> reduce confusion for developers if you filed an issue against the Core
> spec requesting that the same character set restrictions be applied to
> these related error values in Core as were already agreed to (after MUCH
> working group discussion) for Bearer. (ASCII is sufficient because the
> error_description is “to provide developers a human-readable explanation
> that is not meant to be displayed to end users”.)



I already did fie a discuss about this on the base spec :)

I think this one is going to get let go.  The response for my comment on the base spec for this one was:

No, because the bearer specification is limited to HTTP auth headers rules which do not specify an encoding for reserved character. OAuth uses formats with well specified encoding rules to allow any character.



Just waiting for the LC to finish on this issue.

[Ballot discuss]
Based on -19.  I'll retain the original #ing.  New text is included after .

4) s2: What happens if the client uses more than one method?



> The spec says “Clients MUST NOT use more than one method to transmit the
> token in each request.” The behavior when violating a MUST is undefined.

I was wondering if this was maybe an HTTP requirement?

Anyway...often times when you say MUST NOT we'd like to know what happens when the implementation doesn't follow the rules and 2119 provides this helpful bit of advice:

Document authors should take the time
to elaborate the security implications of not following
recommendations or requirements as most implementors will not have
had the benefit of the experience and discussion that produced the
specification.

Was thinking that an error would be thrown.

6) s3: What happens if realm, scope, and the error attributes appear more than once?



> The spec says “The realm attribute MUST NOT appear more than once”, “The
> scope attribute MUST NOT appear more than once”, and “…includes one of
> the following error codes in the response”. The behavior when violating
> these normative requirements is undefined.



see #4.

I was thinking that an error would get thrown.

10) s3.1: Shouldn't the character set restrictions on error, error_description, and error_uri be in draft-ietf-oauth-v2?



> Yes, I believe these same restrictions should be present in the Core
> spec. Unfortunately, they aren’t at present, I think in part, because
> the “error”, “error_description”, and “error_uri” errors there are used
> in a different protocol contexts where it’s easier to use non-ASCII
> characters. (The Core spec specifies UTF-8 encoding for
> error_description, for instance, rather than limiting it to the ASCII
> subset in the Bearer spec.) I believe it would increase consistency and
> reduce confusion for developers if you filed an issue against the Core
> spec requesting that the same character set restrictions be applied to
> these related error values in Core as were already agreed to (after MUCH
> working group discussion) for Bearer. (ASCII is sufficient because the
> error_description is “to provide developers a human-readable explanation
> that is not meant to be displayed to end users”.)



I already did fie a discuss about this on the base spec :)

I think this one is going to get let go.  The response for my comment on the base spec for this one was:

No, because the bearer specification is limited to HTTP auth headers rules which do not specify an encoding for reserved character. OAuth uses formats with well specified encoding rules to allow any character.

[Ballot discuss]
  The Gen-ART Review by Alexey Melnikov on 10-Apr-2012 reports that two
  major issues that were raised in an earlier review were not addressed.
  One has been resolved, and the other has not.  The remaining issue is
  the error codes.

  Section 3.1 specifies Error Codes.  Alexey suggested the use
  of an IANA registry for this field.  Apparently there is already a
  registry created by draft-ietf-oauth-v2. However this document does
  not register values defined in this section in that registry.  Please
  explain why the IANA registry is not leveraged by this document.

[Ballot discuss]

  The Gen-ART Review by Alexey Melnikov on 10-Apr-2012 reports that two
  major issues that were raised in an earlier review were not addressed.
  One has been resolved, and the other has not.  The remaining issue is
  the scope attribute.

  The "scope" attribute is a space-delimited list of scope values
  indicating the required scope of the access token for accessing the
  requested resource.  In some cases, the "scope" value will be used
  when requesting a new access token with sufficient scope of access to
  make use of the protected resource.  The "scope" attribute MUST NOT
  appear more than once.  The "scope" value is intended for programmatic
  use and is not meant to be displayed to end users.

  In response to the previous review by Alexey, the document editor
  provided explanation in email; however, this response was not
  reflected in the subsequent update to the document.

  More information about the "scope" attribute is needed, especially
  about the manner that it is used and the possible values.  As this
  attribute is not meant to be displayed to end users, please indicate
  what values are possible and which entity can allocate them.  Is there
  an IANA registry for possible attribute values?  If so, what are the
  rules for assigning a new registry value.

[Ballot discuss]
Mark Nottingham's Applications Area review  notes the following concern:

* Section 2.3 URI Query Parameter

This section effectively reserves a URI query parameter for the
draft's use. This should not be done lightly, since this would be a
precedent for the IETF encroaching upon a server's URIs (done
previously in RFC5785, but in a much more limited fashion, as a
tactic to prevent further, uncontrolled encroachment).

Given that the draft already discourages the use of this mechanism,
I'd recommend dropping it altogether. If the Working Group wishes it
to remain, this issues should be vetted both through the APPS area
and the W3C liaison.

(The same criticism could be leveled at Section 2.2 Form-Encoded
Body Parameter, but that at least isn't surfaced in an identifier)

I take this as essentially a slippery slope argument: URI query parameters are normally locally scoped. In this case, a query parameter (access_token) is being defined as applying to all URIs. This is (relatively) novel. A few people in the HTTP community (including Mark) have expressed concerns. (See also http://www.ietf.org/mail-archive/web/apps-discuss/current/msg04932.html and http://www.ietf.org/mail-archive/web/apps-discuss/current/msg04933.html from the apps-discuss archive.) This issue should probably be further reviewed by W3C folks. I'm holding the DISCUSS as per Stephen to make sure we get that review.

[Ballot comment]
Mark Nottingham's Applications Area review  has a couple of comments that I think deserve further reply:

* Section 1: Introduction

The introduction explains oauth, but it doesn't fully explain the
relationship of this specification to OAuth 2.0. E.g., can it be
used independently from the rest of OAuth? Likewise, the overview
(section 1.3) seems more specific to the OAuth specification than
this document. As I read it, this mechanism could be used for ANY
bearer token, not just one generated through OAuth flows.

If it is indeed more general, I'd recommend minimising the
discussion of OAuth, perhaps even removing it from the document
title.

I agree that the title would be better simply as "HTTP Bearer Tokens", and then explain in the Abstract and Intro that the motivation and intended use of these Bearer Tokens is the OAuth 2.0 specification. A possibly useful side effect of this change might be that you can make OAuth 2.0 an informative (as against a normative) reference, and that these things could be reused for other purposes in the future. Not a huge deal, but I (like Mark) was unconvinced that the reference to OAuth in the title was necessary.

* Section 3 The WWW-Authenticate Response Header Field

The difference between a realm and a scope is not explained. Are the
functionally equivalent, just a single value vs. a list?

Some text, and probably an example, might help explain this a bit better.

One of his comments asked for some additional review. I don't have a personal opinion whether this is needed, but perhaps you should pursue this:

* General

The draft currently doesn't mention whether Bearer is suitable for
use as a proxy authentication scheme. I suspect it *may*; it would
be worth discussing this with some proxy implementers to gauge their
interest (e.g., Squid).

[Ballot discuss]
While editing this I say Mike's responses so I just cut them in to see if we can't have one thread going on this draft for my discusses/comments.  I added Mike's responses in between  and

#1 was updated based on input from Julian.
#9 was updated based Alexey's GEN-ART review.
#13 is new.

First off, I appreciate that you have likely slayed more than a few dragons working on this draft and I appreciate your efforts.  Would just like to clear up a few things:

1) I'm hoping the answer to this one is "there's no problem" but I gotta ask and maybe the APPs ADs can confirm:  Is there any issue with this specification using ABNF from [I-D.ietf-httpbis-p1-messaging] while OAUTH 2.0 uses [RFC5234]?



> None that I’m aware of.  Both specs are syntactically well-defined.



From Julian: The ABNF from HTTPbis is a superset of RFC 5234 in that it defines a list rule for readability. I don't think that this rule is used anymore in the bearer spec, so it can just say it's using RFC 5234.

So could can this just reference 5234 for the ABNF?

2) I thought maybe this spec was going to explain how the resource server knows that the access token provided hasn't expired, but it didn't.  How's that going to happen again?



> That’s out of scope for this specification, as the Bearer spec is, by
> design, token type independent, but in scope for profiles for specific
> token types such as draft-ietf-oauth-saml2-bearer and
> draft-jones-oauth-jwt-bearer. In those profiles you’ll find requirements
> for expiration time assertions in the tokens used.



Okay I'll give you a on this one because this isn't really talking about the direct interaction between the authorization server and the resource server, but just for my own edification where is that exchange defined - is there a draft about this interaction?

3) s1: Last para: Okay isn't it step (D) partially addressed too?  The access token format returned by the authorization server is defined in this specification - right?  Further, in s5.2 there are recommendations for issuance of access tokens and that's covered in (D)?



> You’re correct that semantic requirements are placed upon the access
> token communicated in step D. The protocol portion of D is solely within
> the OAuth Core spec, however, whereas the protocol elements for steps E
> and F are defined in the Bearer spec. If you think it’s warranted, a
> sentence something like “This document also imposes requirements upon
> the access token returned in Step D” could be added at the end of
> Section 1. Your thoughts?



Yeah I think that's worth adding.  Maybe I'm just being pedantic, but I think it's better to add this in.

4) s2: What happens if the client uses more than one method?



> The spec says “Clients MUST NOT use more than one method to transmit the
> token in each request.” The behavior when violating a MUST is undefined.

I was wondering if this was maybe an HTTP requirement?

Anyway...often times when you say MUST NOT we'd like to know what happens when the implementation doesn't follow the rules and 2119 provides this helpful bit of advice:

Document authors should take the time
to elaborate the security implications of not following
recommendations or requirements as most implementors will not have
had the benefit of the experience and discussion that produced the
specification.

5) s2.1: b64token is pretty forgiving in that it allows a whole bunch of different encodings.  Is one the MTI?

> None are MTI, again because this spec is, by design, token type
> independent. Specific profiles using this spec will define particular
> MTI encodings for particular token types.

Okay this confuses me.  Are you saying there's going to be different types of bearer tokens?  Is there going to be a registry for them?

6) s3: What happens if realm, scope, and the error attributes appear more than once?



> The spec says “The realm attribute MUST NOT appear more than once”, “The
> scope attribute MUST NOT appear more than once”, and “…includes one of
> the following error codes in the response”. The behavior when violating
> these normative requirements is undefined.



see #4.

7) s3: Under what circumstances wouldn't you want an error returned?



> The spec says “If the request lacks any authentication information (i.e.
> the client was unaware authentication is necessary or attempted using an
> unsupported authentication method), the resource server SHOULD NOT
> include an error code or other error information.” This restriction is
> in place to avoid leaking potentially useful information to an attacker.



Should'a caught that - consider this one closed.

8) s3.1: Trying to figure out the error requirements.  Are the shoulds in the three codes telling you that you could send other 4** codes than those listed or that if you can come up with a good reason you don't need to send one at all?



> The SHOULDs are there because while the use of 400, 401, and 403 for
> those cases are highly recommended, the working group found, in
> consultation with Mark Nottingham and other experts, that sometimes in
> practice different error codes are used under these same or similar
> circumstances. For instance, some implementations may be returning 401
> (Unauthorized) for insufficient scope conditions, rather than 403
> (Forbidden).



Consider this one closed.

9) s3.1: I thought scope was defined in draft-ietf-oauth-v2 shouldn't you just point there and then you can pick up the character set restrictions from the ABNF there?



> The scope syntax is also defined in Section 3.3 of OAuth Core, but for
>use in different, but semantically related, protocol contexts. (Core
>uses it as a request parameter. Bearer uses it as an error response
>parameter.) Yes, the syntax restrictions for scope values could be
> included by reference to Core, rather than included in Bearer, but given
> that other parameter syntax restrictions are also needed for error
> response parameters (see your next question), it seemed simpler for
> developers to include all of them in once place in the Bearer spec.



and then I added:

Additionally:

If the "scope" attribute defined in draft-ietf-oauth-v2-bearer-18.txt is the same as in draft-ietf-oauth-v2-25.txt, then draft-ietf-oauth-v2-bearer-18.txt must reference Section 3.3 of draft-ietf-oauth-v2.

Secondly, the definitions are a bit out of sync and the one in draft-ietf-oauth-v2 seems a bit better.

This actually answers my question about who can allocate values. (See my
Gen-Art review and associated threads on the OAUTH mailing list.)

If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope.

I think this is quite valuable addition.

Suggested updated text for draft-ietf-oauth-v2-bearer:.

  The "scope" attribute is defined in Section 3.3 of [draft-ietf-oauth-v2].
  The "scope" attribute is a space-delimited list of case sensitive scope
  values
  indicating the required scope of the access token for accessing the
  requested resource. "scope" values are implementation defined and
  there is no centralized registry for them, allowed values are defined
  by the authorization server. Note that the order of "scope" values
  is not significant. In some cases, the "scope" value will be used
  when requesting a new access token with sufficient scope of access to
  utilize the protected resource. Use of the "scope" attribute is
  OPTIONAL. The "scope" attribute MUST NOT appear more than once. The
  "scope" value is intended for programmatic use and is not meant to be
  displayed to end users.

10) s3.1: Shouldn't the character set restrictions on error, error_description, and error_uri be in draft-ietf-oauth-v2?



> Yes, I believe these same restrictions should be present in the Core
> spec. Unfortunately, they aren’t at present, I think in part, because
> the “error”, “error_description”, and “error_uri” errors there are used
> in a different protocol contexts where it’s easier to use non-ASCII
> characters. (The Core spec specifies UTF-8 encoding for
> error_description, for instance, rather than limiting it to the ASCII
> subset in the Bearer spec.) I believe it would increase consistency and
> reduce confusion for developers if you filed an issue against the Core
> spec requesting that the same character set restrictions be applied to
> these related error values in Core as were already agreed to (after MUCH
> working group discussion) for Bearer. (ASCII is sufficient because the
> error_description is “to provide developers a human-readable explanation
> that is not meant to be displayed to end users”.)



I already did fie a discuss about this on the base spec :)

11) s5.2: TLS is required and that's great, but what I think this means is that if the redirection endpoint (defined in 3.1.2 of draft-ietf-oauth-v2) decides not to implement TLS (it's only a SHOULD) then this token format can't be used in that scenario?  I think this needs to be very clearly documented - then again maybe I'm totally wrong.



> I’m not sure how to be much more clear than the current statement that
> “The authorization server MUST implement TLS”.



Fair enough, let me come up with some words.

12) s5.2: Do the two "issue" recommendations apply generally to all types of tokens?  If they do, then shouldn't they be moved to the base spec?



> (I assume you meant 5.3 here.) No, they do not. For instance,
> proof-of-possession tokens (which require an additional protocol
> exchange in general to use) have very different security
> characteristics. The security considerations for each class of token can
> be different (although sometimes admittedly overlapping).

> BTW, for security considerations of the Core spec, reviewers should also
> be aware of the intentionally much more comprehensive
> draft-ietf-oauth-v2-threatmodel document, which has completed working
> group last call.



I did mean s5.3.  Consider this one closed based on the idea that the explanation to #5 all makes sense.

13) This one most like a DISCUSS-DISCUSS (i.e., nothing for the authors to do at this time):  Do we really want to define an HTTP authentication mechanism herein?  Isn't the http* WG going to work on that?

[Ballot comment]
1) Figure 1: I've made some suggested changes to Figure 1 in draft-ietf-oauth-v2 and you should keep the two aligned.



> Sure. Please send these to me and keep me apprised about whether they
> are adopted in the Core spec.



I'll make to.  There might no be any changes in the end.

2) s2.1: r/Resource servers MUST support this method./Resource servers compliant with this specification MUST support this method.



> OK



3) s2.2/s2.3: r/Resource servers MAY support this method./Resource servers compliant with specification MAY support this method.



> OK



4) s5.2: You could point to the cookies document for security considerations on cookies: RFC 6265.



>cookies: RFC 6265.
> OK in principle. Specific proposed text would be welcomed.



Fair enough.  How about adding the following to the end of the para that starts ... Cookies are typically:

  See [RFC6265] for security considerations about cookies (aka HTTP state management).

5) s5.2: Peter's gone, but his document (RFC 6125) lives on.  It discusses matching server Ids.  Might add a reference to that draft in this draft.



> There’s history on this one. :-/ Per the history entries, a previous
> reference to RFC 2818 was changed to RFC 6125 in draft 14 at the request
> of Stephen Farrell. Then, in draft 17, the 6125 reference was removed in
> favor of text referencing 2818 supplied as a result of the Gen-ART
> review by Alexey Melnikov (and reviewed by Stephen). I’d love to do
> whatever the right thing is here, but if a change is to be made, I’d
> request that the new text be reviewed by all of Stephen, Alexey, and
> Peter Saint-Andre before being changed in the draft.



I'll take the action to coordinate text with the five of us.  Should see a message shortly.

6) s5.3: r/SSL/TLS ;)



> Sure

[Ballot comment]
Mark Nottingham's Applications Area review  has a couple of comments that I think deserve further reply:

* Section 1: Introduction

The introduction explains oauth, but it doesn't fully explain the
relationship of this specification to OAuth 2.0. E.g., can it be
used independently from the rest of OAuth? Likewise, the overview
(section 1.3) seems more specific to the OAuth specification than
this document. As I read it, this mechanism could be used for ANY
bearer token, not just one generated through OAuth flows.

If it is indeed more general, I'd recommend minimising the
discussion of OAuth, perhaps even removing it from the document
title.

I agree that the title would be better simply as "HTTP Bearer Tokens", and then explain in the Abstract and Intro that the motivation and intended use of these Bearer Tokens is the OAuth 2.0 specification. A possibly useful side effect of this change might be that you can make OAuth 2.0 an informative (as against a normative) reference, and that these things could be reused for other purposes in the future. Not a huge deal, but I (like Mark) was unconvinced that the reference to OAuth in the title was necessary.

* Section 3 The WWW-Authenticate Response Header Field

The difference between a realm and a scope is not explained. Are the
functionally equivalent, just a single value vs. a list?

Some text, and probably an example, might help explain this a bit better.

One of his comments asked for some additional review. I don't have a personal opinion whether this is needed, but perhaps you should pursue this:

* General

The draft currently doesn't mention whether Bearer is suitable for
use as a proxy authentication scheme. I suspect it *may*; it would
be worth discussing this with some proxy implementers to gauge their
interest (e.g., Squid).

Finally, there was his major issue. I have not put this in a DISCUSS since, in all honesty, I don't fully understand the implications here. I intend to re-post to the apps-discuss list to see if we can get a better explanation of what the issue is. However, I strongly urge the AD, shepherd, and chairs, as well as the authors, to review this concern. If I get more information that makes the issue clear to me, I may ask the IESG to discuss:

* Section 2.3 URI Query Parameter

This section effectively reserves a URI query parameter for the
draft's use. This should not be done lightly, since this would be a
precedent for the IETF encroaching upon a server's URIs (done
previously in RFC5785, but in a much more limited fashion, as a
tactic to prevent further, uncontrolled encroachment).

Given that the draft already discourages the use of this mechanism,
I'd recommend dropping it altogether. If the Working Group wishes it
to remain, this issues should be vetted both through the APPS area
and the W3C liaison.

(The same criticism could be leveled at Section 2.2 Form-Encoded
Body Parameter, but that at least isn't surfaced in an identifier)

[Ballot discuss]
These are preliminary discusses in that more might show up as result of the secdir review, but if the review doesn't show up before 2012-04-12 at 1130 Eastern these will be the final comments.

First off, I appreciate that you have likely slayed more than a few dragons working on this draft and I appreciate your efforts.  Would just like to clear up a few things:

1) I'm hoping the answer to this one is "there's no problem" but I gotta ask and maybe the APPs ADs can confirm:  Is there any issue with this specification using ABNF from [I-D.ietf-httpbis-p1-messaging] while OAUTH 2.0 uses [RFC5234]?

2) I thought maybe this spec was going to explain how the resource server knows that the access token provided hasn't expired, but it didn't.  How's that going to happen again?

3) s1: Last para: Okay isn't it step (D) partially addressed too?  The access token format returned by the authorization server is defined in this specification - right?  Further, in s5.2 there are recommendations for issuance of access tokens and that's covered in (D)?

4) s2: What happens if the client uses more than one method?

5) s2.1: b64token is pretty forgiving in that it allows a whole bunch of different encodings.  Is one the MTI?

6) s3: What happens if realm, scope, and the error attributes appear more than once?

7) s3: Under what circumstances wouldn't you want an error returned?

8) s3.1: Trying to figure out the error requirements.  Are the shoulds in the three codes telling you that you could send other 4** codes than those listed or that if you can come up with a good reason you don't need to send one at all?

9) s3.1: I thought scope was defined in draft-ietf-oauth-v2 shouldn't you just point there and then you can pick up the character set restrictions from the ABNF there?

10) s3.1: Shouldn't the character set restrictions on error, error_description, and error_uri be in draft-ietf-oauth-v2?

11) s5.2: TLS is required and that's great, but what I think this means is that if the redirection endpoint (defined in 3.1.2 of draft-ietf-oauth-v2) decides not to implement TLS (it's only a SHOULD) then this token format can't be used in that scenario?  I think this needs to be very clearly documented - then again maybe I'm totally wrong.

12) s5.2: Do the two "issue" recommendations apply generally to all types of tokens?  If they do, then shouldn't they be moved to the base spec?

[Ballot comment]
1) Figure 1: I've made some suggested changes to Figure 1 in draft-ietf-oauth-v2 and you should keep the two aligned.

2) s2.1: r/Resource servers MUST support this method./Resource servers compliant with this specification MUST support this method.

3) s2.2/s2.3: r/Resource servers MAY support this method./Resource servers compliant with specification MAY support this method.

4) You could point to the cookies document for security considerations on cookies: RFC 6265.

5) s5.2: Peter's gone, but his document (RFC 6125) lives on.  It discusses matching server Ids.  Might add a reference to that draft in this draft.

6) s5.3: r/SSL/TLS ;)

[Ballot discuss]
  The Gen-ART Review by Alexey Melnikov on 10-Apr-2012 reports that two
  major issues that were raised in an earlier review were not addressed.
  I have added my own thoughts in addition to those provided by Alexey.

  First, the "scope" attribute is a space-delimited list of scope values
  indicating the required scope of the access token for accessing the
  requested resource.  In some cases, the "scope" value will be used
  when requesting a new access token with sufficient scope of access to
  make use of the protected resource.  The "scope" attribute MUST NOT
  appear more than once.  The "scope" value is intended for programmatic
  use and is not meant to be displayed to end users.

  In response to the previous review by Alexey, the document editor
  provided explanation in email; however, this response was not
  reflected in the subsequent update to the document.

  More information about the "scope" attribute is needed, especially
  about the manner that it is used and the possible values.  As this
  attribute is not meant to be displayed to end users, please indicate
  what values are possible and which entity can allocate them.  Is there
  an IANA registry for possible attribute values?  If so, what are the
  rules for assigning a new registry value.

  Second, Section 3.1 specifies Error Codes.  Alexey suggested the use
  of an IANA registry for this field.  Apparently there is already a
  registry created by draft-ietf-oauth-v2. However this document does
  not register values defined in this section in that registry.  Please
  explain why the IANA registry is not leveraged by this document.

[Ballot discuss]

  The Gen-ART Review by Alexey Melnikov on 10-Apr-2012 reports that two
  major issues that were raised in an earlier review were no addressed.
  I have added my own thoughts in addition to those provided by Alexey.

  First, the "scope" attribute is a space-delimited list of scope values
  indicating the required scope of the access token for accessing the
  requested resource.  In some cases, the "scope" value will be used
  when requesting a new access token with sufficient scope of access to
  make use of the protected resource.  The "scope" attribute MUST NOT
  appear more than once.  The "scope" value is intended for programmatic
  use and is not meant to be displayed to end users.

  In response to the previous review by Alexey, the document editor
  provided explanation in email; however, this response was not
  reflected in the subsequent update to the document.

  More information about the "scope" attribute is needed, especially
  about the manner that it is used and the possible values.  As this
  attribute is not meant to be displayed to end users, please indicate
  what values are possible and which entity can allocate them.  Is there
  an IANA registry for possible attribute values?  If so, what are the
  rules for assigning a new registry value.

  Second, Section 3.1 specifies Error Codes.  Alexey suggested the use
  of an IANA registry for this field.  Apparently there is already a
  registry created by draft-ietf-oauth-v2. However this document does
  not register values defined in this section in that registry.  Please
  explain why the IANA registry is not leveraged by this document.

[Ballot comment]
In Section 1, I suggest changing:
"for use with other transport protocols"
to something more like:
"for use over other protocols".
HTTP is not a transport protocol.

[Ballot comment]
Section 2.1 states :

Clients SHOULD make authenticated requests with a bearer token using the "Authorization" request header field with the "Bearer" HTTP authorization scheme.

Is the SHOULD simply to show a preference for the Authorization request approach over the methods defined in Sections 2.2 and 2.3?  If so, in what type of situation would the Authorization request approach not be used?

Upon approval of this document, IANA will perform the following actions,
provided that the documents these actions depend on have already been
approved:

ACTION 1:

If , which creates the OAuth Access Token Type Registry, has already
been approved, IANA will register the following OAuth Access Token Type:

Type name:
Bearer

Additional Token Endpoint Response Parameters:
(none)

HTTP Authentication Scheme(s):
Bearer

Change controller:
IETF

Reference:
[[ this document ]]


ACTION 2:

Upon approval of this document, provided that the document that creates
the relevant registry has already been approved, IANA will register the
following in the Authentication Scheme Registry defined in
draft-ietf-httpbis-p7-auth (which IANA has yet to review, as it has not
yet been sent to IETF Last Call):

Authentication Scheme Name:
Bearer

Reference:
[[ this document ]]

Notes (optional):
(none)

State changed to In Last Call from In Last Call.

The following Last Call Announcement was sent out:

From: The IESG
To: IETF-Announce
CC:
Reply-To: ietf@ietf.org
Subject: REVISED Last Call:  (The OAuth 2.0 Authorization Protocol: Bearer Tokens) to Proposed Standard


The IESG has received a request from the Web Authorization Protocol WG
(oauth) to consider the following document:
- 'The OAuth 2.0 Authorization Protocol: Bearer Tokens'
  as a Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2012-02-07. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  This specification describes how to use bearer tokens in HTTP
  requests to access OAuth 2.0 protected resources.  Any party in
  possession of a bearer token (a "bearer") can use it to get access to
  the associated resources (without demonstrating possession of a
  cryptographic key).  To prevent misuse, bearer tokens need to be
  protected from disclosure in storage and in transport.


* There is a normative reference to RFC 2246 (TLS 1.0), which has been
obsoleted by RFC 5246 (TLS 1.2).  The document uses this reference to
note that TLS 1.0 is, at this writing, the most widely deployed
version.  The working group believes it is necessary to note that, and
that the reference be normative.


The file can be obtained via
http://datatracker.ietf.org/doc/draft-ietf-oauth-v2-bearer/

IESG discussion can be tracked via
http://datatracker.ietf.org/doc/draft-ietf-oauth-v2-bearer/


No IPR declarations have been submitted directly on this I-D.

State changed to In Last Call from Last Call Requested.

The following Last Call Announcement was sent out:

From: The IESG
To: IETF-Announce
CC:
Reply-To: ietf@ietf.org
Subject: Last Call:  (The OAuth 2.0 Authorization Protocol: Bearer Tokens) to Proposed Standard


The IESG has received a request from the Web Authorization Protocol WG
(oauth) to consider the following document:
- 'The OAuth 2.0 Authorization Protocol: Bearer Tokens'
  as a Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2012-02-06. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  This specification describes how to use bearer tokens in HTTP
  requests to access OAuth 2.0 protected resources.  Any party in
  possession of a bearer token (a "bearer") can use it to get access to
  the associated resources (without demonstrating possession of a
  cryptographic key).  To prevent misuse, bearer tokens need to be
  protected from disclosure in storage and in transport.




The file can be obtained via
http://datatracker.ietf.org/doc/draft-ietf-oauth-v2-bearer/

IESG discussion can be tracked via
http://datatracker.ietf.org/doc/draft-ietf-oauth-v2-bearer/


No IPR declarations have been submitted directly on this I-D.

Document Shepherd Write-Up for draft-ietf-oauth-v2-bearer-12

  (1.a) Who is the Document Shepherd for this document? Has the
        Document Shepherd personally reviewed this version of the
        document and, in particular, does he or she believe this
        version is ready for forwarding to the IESG for publication?

The document shepherd is Hannes Tschofenig. I have personally reviewed the
document and I think it is ready for going forward.

  (1.b) Has the document had adequate review both from key WG members
        and from key non-WG members? Does the Document Shepherd have
        any concerns about the depth or breadth of the reviews that
        have been performed? 

The document received a number of reviews from the working group but also
from members outside the working group, including security reviews. 

  (1.c) Does the Document Shepherd have concerns that the document
        needs more review from a particular or broader perspective,
        e.g., security, operational complexity, someone familiar with
        AAA, internationalization or XML?

The document was reviewed by Julian Reschke for HTTP related content.
Changes to the document have been made in response to his review.

There is still disagreement between Julian and working
group members regarding two issues concerning encoding. While the
shepherd feels comfortable going forward with the specification to
the IESG wider IETF review may provide additional feedback.

One issue is related to the encoding of the scope attribute in context
of HTTP authentication parameters:

https://www.ietf.org/mail-archive/web/oauth/current/msg07733.html
https://www.ietf.org/mail-archive/web/oauth/current/msg07734.html
https://www.ietf.org/mail-archive/web/oauth/current/msg07739.html

The other comment by Julian is related to the form encoding, as
described here:
https://www.ietf.org/mail-archive/web/oauth/current/msg07731.html


  (1.d) Does the Document Shepherd have any specific concerns or
        issues with this document that the Responsible Area Director
        and/or the IESG should be aware of? For example, perhaps he
        or she is uncomfortable with certain parts of the document, or
        has concerns whether there really is a need for it. In any
        event, if the WG has discussed those issues and has indicated
        that it still wishes to advance the document, detail those
        concerns here. Has an IPR disclosure related to this document
        been filed? If so, please include a reference to the
        disclosure and summarize the WG discussion and conclusion on
        this issue.

I have no concerns regarding this document but would like to appreciate
feedback from the wider IETF community on the issues raised under
item 1.c. 

  (1.e) How solid is the WG consensus behind this document? Does it
        represent the strong concurrence of a few individuals, with
        others being silent, or does the WG as a whole understand and
        agree with it? 
       
There solid consensus behind this document from the working group.

  (1.f) Has anyone threatened an appeal or otherwise indicated extreme
        discontent? If so, please summarise the areas of conflict in
        separate email messages to the Responsible Area Director. (It
        should be in a separate email because this questionnaire is
        entered into the ID Tracker.)
       
Nobody had shown extreme discontent.

  (1.g) Has the Document Shepherd personally verified that the
        document satisfies all ID nits? (See the Internet-Drafts Checklist
        and http://tools.ietf.org/tools/idnits/). Boilerplate checks are
        not enough; this check needs to be thorough. Has the document
        met all formal review criteria it needs to, such as the MIB
        Doctor, media type and URI type reviews?

I have verified the document. The idnits tool gives a warning about
the RFC 2119 boilerplate, and that warning is incorrect.

  (1.h) Has the document split its references into normative and
        informative? Are there normative references to documents that
        are not ready for advancement or are otherwise in an unclear
        state? If such normative references exist, what is the
        strategy for their completion? Are there normative references
        that are downward references, as described in [RFC3967]? If
        so, list these downward references to support the Area
        Director in the Last Call procedure for them [RFC3967].

The references are split into normative and informative references. 

There is one downref to RFC 2818.

  (1.i) Has the Document Shepherd verified that the document IANA
        consideration section exists and is consistent with the body
        of the document? If the document specifies protocol
        extensions, are reservations requested in appropriate IANA
        registries? Are the IANA registries clearly identified? If
        the document creates a new registry, does it define the
        proposed initial contents of the registry and an allocation
        procedure for future registrations? Does it suggest a
        reasonable name for the new registry? See [RFC5226]. If the
        document describes an Expert Review process has Shepherd
        conferred with the Responsible Area Director so that the IESG
        can appoint the needed Expert during the IESG Evaluation?

I have reviewed the IANA consideration section.
The documents adds new values into an existing registry.

  (1.j) Has the Document Shepherd verified that sections of the
        document that are written in a formal language, such as XML
        code, BNF rules, MIB definitions, etc., validate correctly in
        an automated checker?

The ABNF in the document was verified with
http://trac.tools.ietf.org/wg/httpbis/trac/browser/abnfparser/bap

  (1.k) The IESG approval announcement includes a Document
        Announcement Write-Up. Please provide such a Document
        Announcement Write-Up? Recent examples can be found in the
        "Action" announcements for approved documents. The approval
        announcement contains the following sections:

    Technical Summary

  This specification describes how to use bearer tokens in HTTP
  requests to access OAuth 2.0 protected resources.  Any party in
  possession of a bearer token (a "bearer") can use it to get access to
  granted resources (without demonstrating possession of a
  cryptographic key).  To prevent misuse, the bearer token MUST be
  protected from disclosure in storage and in transport.
 
    Working Group Summary

  The working group decided to develop two types of mechanisms for
  a client to access a protected resource. The second specification
  is being worked on with draft-ietf-oauth-v2-http-mac-00. The
  two specifications offer different security properties to allow
  deployments to meet their specific needs.
 
    Document Quality
 
  This specification is implemented, deployed and used by Microsoft
  Access Control Service (ACS), Google Apps, Facebook Connect and the
  Graph API, Salesforce, Mitre, and many others.
 
  Source code is available as well. For example
  http://static.springsource.org/spring-security/oauth/
  http://incubator.apache.org/projects/amber.html
  https://github.com/nov/rack-oauth2
  + many more, including those listed at
  https://github.com/teohm/teohm.github.com/wiki/OAuth