Subject: [OAUTH-WG] OAuth 2.0 Bearer Token Specification Draft -10

From: Mike Jones <[email-masked]>
Date: Wed, 19 Oct 2011 23:38:02 +0000

Draft 10<http://self-issued.info/docs/draft-ietf-oauth-v2-bearer-10.html> of the OAuth 2.0 Bearer Token Specification<http://self-issued.info/docs/draft-ietf-oauth-v2-bearer.html> has been published, which incorporates consensus decisions reached since Working Group Last Call feedback.  It closes all open issues.  It contains the following changes:

*        Removed the #auth-param option from Authorization header syntax (leaving only the b64token syntax).

*        Restricted the scope value character set to %x21 / %x23-5B / %x5D-7E (printable ASCII characters excluding double-quote and backslash). Indicated that scope is intended for programmatic use and is not meant to be displayed to end users.

*        Restricted the character set for error_description strings to SP / VCHAR and indicated that they are not meant to be displayed to end users.

*        Included more description in the Abstract, since Hannes Tschofenig indicated that the RFC editor would require this.

*        Changed "Access Grant" to "Authorization Grant", as was done in the core spec.

*        Simplified the introduction to the Authenticated Requests section.

The draft is available at these locations:

*        http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-10

*        http://www.ietf.org/internet-drafts/draft-ietf-oauth-v2-bearer-10.pdf

*        http://www.ietf.org/internet-drafts/draft-ietf-oauth-v2-bearer-10.txt

*        http://www.ietf.org/internet-drafts/draft-ietf-oauth-v2-bearer-10.xml

*        http://self-issued.info/docs/draft-ietf-oauth-v2-bearer-10.html

*        http://self-issued.info/docs/draft-ietf-oauth-v2-bearer-10.pdf

*        http://self-issued.info/docs/draft-ietf-oauth-v2-bearer-10.txt

*        http://self-issued.info/docs/draft-ietf-oauth-v2-bearer-10.xml

*        http://self-issued.info/docs/draft-ietf-oauth-v2-bearer.html (will point to new versions as they are posted)

*        http://self-issued.info/docs/draft-ietf-oauth-v2-bearer.pdf (will point to new versions as they are posted)

*        http://self-issued.info/docs/draft-ietf-oauth-v2-bearer.txt (will point to new versions as they are posted)

*        http://self-issued.info/docs/draft-ietf-oauth-v2-bearer.xml (will point to new versions as they are posted)

*        http://svn.openid.net/repos/specifications/oauth/2.0/ (Subversion repository, with html, pdf, txt, and html versions available)

                                                            -- Mike

---

From: Julian Reschke <[email-masked]>
Date: Thu, 20 Oct 2011 09:12:58 +0200

On 2011-10-20 01:38, Mike Jones wrote:
> Draft 10
> <http://self-issued.info/docs/draft-ietf-oauth-v2-bearer-10.html> of the
> OAuth 2.0 Bearer Token Specification
> <http://self-issued.info/docs/draft-ietf-oauth-v2-bearer.html> has been
> published, which incorporates consensus decisions reached since Working
> Group Last Call feedback. It closes all open issues. It contains the
> following changes:
> ...

This is better.

I still see problems though.

Section 2.2 specifies to use application/x-www-form-urlencoded encoding, 
but doesn't mention the character encoding to use. This may be a 
non-issue now for scopes, but it would be for extension parameters.

Section 2.4 still uses quoted parameters without using the quoted-string 
constructs. This leaves implementers in the dark about whether they can 
use existing quoted-string parsers or not.

Best regards, Julian

---

From: Mike Jones <[email-masked]>
Date: Thu, 20 Oct 2011 07:14:40 +0000

Can you recommend specific wording changes to address both issues?

				-- Mike

-----Original Message-----
From: Julian Reschke [mailto:[email-masked]] 
Sent: Thursday, October 20, 2011 12:13 AM
To: Mike Jones
Cc: [email-masked]
Subject: Re: [OAUTH-WG] OAuth 2.0 Bearer Token Specification Draft -10

On 2011-10-20 01:38, Mike Jones wrote:
> Draft 10
> <http://self-issued.info/docs/draft-ietf-oauth-v2-bearer-10.html> of 
> the OAuth 2.0 Bearer Token Specification 
> <http://self-issued.info/docs/draft-ietf-oauth-v2-bearer.html> has 
> been published, which incorporates consensus decisions reached since 
> Working Group Last Call feedback. It closes all open issues. It 
> contains the following changes:
> ...

This is better.

Section 2.2 specifies to use application/x-www-form-urlencoded encoding, but doesn't mention the character encoding to use. This may be a non-issue now for scopes, but it would be for extension parameters.

Section 2.4 still uses quoted parameters without using the quoted-string constructs. This leaves implementers in the dark about whether they can use existing quoted-string parsers or not.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 20 Oct 2011 09:37:08 +0200

> Can you recommend specific wording changes to address both issues?

2.2: "The entity-body is encoded using the 
"application/x-www-form-urlencoded" media type (Section 17.13.4 of 
[W3C.REC-html401-19991224]), applied to the UTF-8 [RFC3629] encoded 
forms of the parameter values."

Note 1: HTML4 ignores the encoding issue; this is a case where a 
reference to HTML5 would actually help in practice.

Note 2: I prefer refs in the form of [REC-html] or [HTML] rather than 
[W3C.REC-html401-19991224]...

2.4: As stated earlier, just define all those parameters to be "token / 
quoted-string", and then constrain the values further separately, such as:

"The value of the scope parameter, after potential quoted-string 
unquoting, contains a set of single-SP delimited scope values." Each 
scope value is restricted to

   scope-val-char  = %x21 / %x23-5B / %x5D-7E
   ; HTTPbis P1 qdtext except whitespace, restricted to US-ASCII
"

etc.

Best regards, Julian

---

From: Mike Jones <[email-masked]>
Date: Thu, 20 Oct 2011 07:41:34 +0000

Your proposed wording for 2.4 misses the point:  \ MUST NOT occur at all in the input string.  No quoting may occur.

Care to suggest other wording that recognizes this point but still addresses the issue you raise?

				-- Mike

-----Original Message-----
From: Julian Reschke [mailto:[email-masked]] 
Sent: Thursday, October 20, 2011 12:37 AM
To: Mike Jones
Cc: [email-masked]
Subject: Re: [OAUTH-WG] OAuth 2.0 Bearer Token Specification Draft -10

> Can you recommend specific wording changes to address both issues?

2.2: "The entity-body is encoded using the "application/x-www-form-urlencoded" media type (Section 17.13.4 of [W3C.REC-html401-19991224]), applied to the UTF-8 [RFC3629] encoded forms of the parameter values."

Note 1: HTML4 ignores the encoding issue; this is a case where a reference to HTML5 would actually help in practice.

Note 2: I prefer refs in the form of [REC-html] or [HTML] rather than [W3C.REC-html401-19991224]...

etc.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 20 Oct 2011 10:05:22 +0200

> Your proposed wording for 2.4 misses the point:  \ MUST NOT occur at all in the input string.  No quoting may occur.

No, it doesn't miss the point.

You need to tell implementers whether they can use a quoted-string 
processor. Those processors will accept all the values you want to 
support, plus values that contain "\c" (representing "c"). Is this ok, 
or are recipients supposed to reject these values?

Furthermore, it's not clear what recipients are supposed to do with 
values that are not quoted, for instance for scope. The ABNF makes them 
illegal, but I promise you that many recipients will accept them 
nevertheless (unless you manage them to become draconian using a very 
good test suite).

See <http://greenbytes.de/tech/tc/httpauth/#simplebasictok> for a test 
case checking this for the realm parameter. It's already bad for many 
existing headers, please let's do things right with new ones.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 20 Oct 2011 10:10:45 +0200

On 2011-10-20 10:05, Julian Reschke wrote:
>> Your proposed wording for 2.4 misses the point: \ MUST NOT occur at
>> all in the input string. No quoting may occur.
>  > ...
>

...finally, the syntax for the WWW-Authenticate header field is defined 
by HTTPbis, not the OAuth spec. Recipients need to process the header 
field using a generic parser, and only after doing so can delegate to an 
OAuth-specific component for interpretation of the OAuth-specific 
semantics. Translation: a recipient that supports multiple 
authentication schemes is unlikely to implement an OAuth-specific 
*parser* for the header field.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 20 Oct 2011 10:45:35 +0200

On 2011-10-20 01:38, Mike Jones wrote:
> ...
> ·Removed the #auth-param option from Authorization header syntax
> (leaving only the b64token syntax).
> ...

I recommend that adding a rational, such as:

"The b64token syntax was chosen over an extensible parameter syntax (see 
[HTTPbisP7], Section 2.3.1) due to compatibility concerns with early 
implementations. If in the future, additional fields will be needed, a 
new authentication scheme will have to be defined".

(I think this captures what lead to the choice, and helps other readers 
understand why the spec isn't following the recommendations in the HTTP 
Authentication spec).

Best regards, Julian

---

From: Mike Jones <[email-masked]>
Date: Thu, 20 Oct 2011 15:33:32 +0000

By design, implementations can use existing quoted-string parsers, as these accept and correctly process all legal scope values.

The spec is silent on what to do with illegal values, such as those containing \ or those not surrounded by ".  Conforming implementations will not produce such values, and so there's no actual problem in practice, whether you use an off-the-shelf parameter parser or one specific to the Bearer scheme.

Thanks for sweating the details, by the way.  The spec is better for it.

				Best wishes,
				-- Mike

-----Original Message-----
From: Julian Reschke [mailto:[email-masked]] 
Sent: Thursday, October 20, 2011 1:05 AM
To: Mike Jones
Cc: [email-masked]
Subject: Re: [OAUTH-WG] OAuth 2.0 Bearer Token Specification Draft -10

You need to tell implementers whether they can use a quoted-string processor. Those processors will accept all the values you want to support, plus values that contain "\c" (representing "c"). Is this ok, or are recipients supposed to reject these values?

Furthermore, it's not clear what recipients are supposed to do with values that are not quoted, for instance for scope. The ABNF makes them illegal, but I promise you that many recipients will accept them nevertheless (unless you manage them to become draconian using a very good test suite).

See <http://greenbytes.de/tech/tc/httpauth/#simplebasictok> for a test case checking this for the realm parameter. It's already bad for many existing headers, please let's do things right with new ones.

Best regards, Julian

---

From: William Mills <[email-masked]>
Date: Thu, 20 Oct 2011 08:36:22 -0700 (PDT)

Shouldn't the scope definition here refer to the scope definition in the core spec?

________________________________
From: Julian Reschke <[email-masked]>
To: Mike Jones <[email-masked]>
Cc: "[email-masked]" <[email-masked]>
Sent: Thursday, October 20, 2011 12:37 AM
Subject: Re: [OAUTH-WG] OAuth 2.0 Bearer Token Specification Draft -10

2.4: As stated earlier, just define all those parameters to be "token / quoted-string", and then constrain the values further separately, such as:

"The value of the scope parameter, after potential quoted-string unquoting, contains a set of single-SP delimited scope values." Each scope value is restricted to

etc.

Best regards, Julian
_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: Julian Reschke <[email-masked]>
Date: Thu, 20 Oct 2011 17:46:22 +0200

> The spec is silent on what to do with illegal values, such as those containing \ or those not surrounded by ".  Conforming implementations will not produce such values, and so there's no actual pro…

Conforming implementations can produce WWW-Authenticate header fields 
containing quoted-strings containing escapes. This is under the 
jurisdiction of the HTTP spec, not the OAuth spec.

OAuth can profile the legal values *just* for the OAuth scheme, but 
consumers will still need to be able to process a header field that 
contains multiple challenges from schemes != OAuth, and to do so, they 
*have* to use a proper parser.

Consider the following challenge:

	WWW-Authenticate: foo realm="x", title="my \"test\" site", oauth realm="y"

A component that handles WWW-Authenticate absolutely has to rely on 
predictable syntax for quoted strings. It doesn't make any sense to 
special-case OAuth params just because escaping isn't needed. This makes 
things harder and more likely to fail, not simpler.

Best regards, Julian

---

From: Mike Jones <[email-masked]>
Date: Thu, 20 Oct 2011 18:38:48 +0000

That would make sense once issue 27 is incorporated into the core spec.

                                                            -- Mike

From: William Mills [mailto:[email-masked]]
Sent: Thursday, October 20, 2011 8:36 AM
To: Julian Reschke; Mike Jones
Cc: [email-masked]
Subject: Re: [OAUTH-WG] OAuth 2.0 Bearer Token Specification Draft -10

________________________________
From: Julian Reschke <[email-masked]<mailto:[email-masked]>>
To: Mike Jones <[email-masked]<mailto:[email-masked]>>
Cc: "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
Sent: Thursday, October 20, 2011 12:37 AM
Subject: Re: [OAUTH-WG] OAuth 2.0 Bearer Token Specification Draft -10

etc.

Best regards, Julian
_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth