Re: [OAUTH-WG] draft-ietf-oauth-v2-bearer-08 HTTP syntax comments

[Mike Jones <[e-mail]>]

Thanks for your note, Julian.  Responses follow inline...

                                                                -- Mike


-----Original Message-----
From: Julian Reschke [mailto:[e-mail]]
Sent: Saturday, September 24, 2011 5:07 AM
To: Mike Jones
Cc: [e-mail]
Subject: Re: [OAUTH-WG] draft-ietf-oauth-v2-bearer-08 HTTP syntax comments



On 2011-09-24 02:13, Mike Jones wrote:

> Thanks for your comments, Julian. Responses to them, which reflect the

> content of draft 09, follow inline.



Thanks!



> ...

> 2.1. The Authorization Request Header Field

>

> The "Authorization" request header field is used by clients to make

>

> authenticated requests with bearer tokens. The client uses the

>

> "Bearer" authentication scheme to transmit the access token in the

>

> request.

>

> For example:

>

> GET /resource HTTP/1.1

>

> Host: server.example.com

>

> Authorization: Bearer vF9dft4qmT

>

> The "Authorization" header field uses the framework defined by

>

> [RFC2617] as follows:

>

> credentials = "Bearer" RWS access-token

>

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

>

> quoted-char = ALPHA / DIGIT /

>

> "!" / "#" / "$" / "%" / "&" / "'" / "(" / ")" /

>

> "*" / "+" / "-" / "." / "/" / ":" / "<" / "=" /

>

> ">" / "?" / "@" / "[" / "]" / "^" / "_" / "`" /

>

> "{" / "|" / "}" / "~" / "\" / "," / ";"

>

> This is incompatible with the RFC2617 grammar which requires auth-params.

>

> HTTPbis P7 will introduce an alternative syntax ("b64token"), but that

> is restricted to a single instance and thus not extensible.

>

> I recommend to use auth-param syntax instead.

>

> Thanks for pointing this out. I changed the credentials syntax to the

> following, which directly uses the syntax in

> draft-ietf-httpbis-p7-auth-16 (and so invents no new syntax):

>

> credentials = "Bearer" 1*SP ( b64token / #auth-param )



The b64token is always there, right?



So you won't be able to use additional parameters, and thus the syntax is effectively



    credentials = "Bearer" 1*SP b64token



Is that intended and acceptable?

No, b64token isn't always there; the syntax specifies that either a b64token OR one or more auth-params will be present.  Yes, that's intended.


> 2.2. Form-Encoded Body Parameter

>

> ...

>

> o The entity-body follows the encoding requirements of the

>

> "application/x-www-form-urlencoded" content-type as defined by

>

> [W3C.REC-html401-19991224].

>

> o The HTTP request entity-header includes the "Content-Type" header

>

> field set to "application/x-www-form-urlencoded".

>

> What about parameters?

>

> Is there specific language either allowing or ruling out parameters to

> the content-type value that you believe would be appropriate? Can you

> provide a concrete motivating example?



The text as currently written makes it impossible to add parameters to the type. However, the rule of thumb for unknown media type parameters is to ignore them, not to reject them.



Maybe:



"The HTTP Content-Type" header field indicates a media type of "application/x-www-form-urlencoded"."

What do others think of this change that is intended to allow additional content-type parameters?



> ...

> challenge = "Bearer" [ RWS 1#param ]

>

> -> please stick to the syntax defined in the authentication framework,

>

> so use "auth-param", and just define the allowed parameters separately.

>

> I have changed the RWS to 1*SP to match httpbis-p7-auth. I retained

> the "param" definition so as to be able to clearly syntactically limit

> the acceptable set of parameters.



But the acceptable set of parameters is open-ended anyway, right?



> param = realm / scope /

>

> error / error-desc / error-uri /

>

> auth-param

>

> scope = "scope" "=" <"> scope-v *( SP scope-v ) <">

>

> scope-v = 1*quoted-char

>

> -> This seems to override the quoted-string syntax. Don't. Generic

>

> parsers *will* use the quoted-string syntax.

>

> quoted-char = ALPHA / DIGIT /

>

> "!" / "#" / "$" / "%" / "&" / "'" / "(" / ")" /

>

> "*" / "+" / "-" / "." / "/" / ":" / "<" / "=" /

>

> ">" / "?" / "@" / "[" / "]" / "^" / "_" / "`" /

>

> "{" / "|" / "}" / "~" / "\" / "," / ";"

>

> This issue is tracked as issue #26. The proposed resolution to this

> issue is being discussed in a separate thread.



OK.



> error = "error" "=" quoted-string

>

> error-desc = "error_description" "=" quoted-string

>

> error-uri = "error_uri" "=" <"> URI-reference <">

>

> -> missing I18N considerations

>

> The draft now contains: "the resource server MAY include the

> error_description attribute to provide developers a UTF-8 encoded

> human-readable explanation". (The UTF-8 language now matches the core

> spec.)



UTF-8 is uncommon in HTTP header fields. It's not strictly forbidden, but most code I've seen assumes ISO-8859-1 (see, for instance, XHR or Java servlet API).



You *can* use UTF-8, but may encounter strange problems caused by software components in between.

This was the working group decision at the interim meeting and is used in both the core and bearer drafts.  I believe that UTF-8 is a reasonable outcome.  Unless there's a clear consensus to change both specifications, I believe that this should stay as-is.


> There was an explicit working decision not to include language codes.



I didn't ask for language codes :-)

OK.  Others had been asking for them before the interim meeting, hence my confusion.


> This is recorded in the meeting minutes sent to the list by Hannes

> Tschofenig on 6/3/11. The key part of the minutes is:

>

> *** Error Description ***

>

> Agreement among the participants that the error codes are meant for

> consumption by the developer rather than the end user. Hence, language

> codes are not important nor a human readable version that is supposed

> to be understood by end users.



In which case I recommend to stick to plain ASCII.

Again, the working group explicitly decided to move from plain ASCII to UTF-8.


> -> weird syntax (why underscore?)

>

> The OAuth specs have always used underscores to separate words in

> protocol messages.



Well, it looks strange in an HTTP message.

It may, but these names reflect working group consensus.


> -> the generic syntax allows token in addition to quoted-string; it's

>

> pointless to rule that out here

>

> The reply syntax is intentionally restricted to simplify implementations.



Special-casing the syntax *complicates* implementations. Using common constructs allows re-using existing parsing code and thus make things easier.



Consider a browser seeing the credentials. It needs to parse the field value for multiple challenges, and the only way for this to work is to have predictable syntax for parameters.

The philosophy behind the syntax restriction is that interoperability is often increased if implementations are prepared to handle all the cases that may arise.  Having these cases be part of a fixed, enumerated set helps achieve this.  Parsing is the easy part; understanding and meaningfully handling the semantics of the messages is the harder part, which is why this restriction intentionally imposes boundaries - so as to limit the cases that implementations need to be prepared handle.


> 4. IANA Considerations

>

> -> If you have a dependency on HTTPbis then you should also add the

>

> registration for the authentication scheme as defined in HTTPbis P7.

>

> Done



Thanks.



Now that you have switched to HTTPbis you probably can get rid of the reference to RFC 2617.

The remaining reference is informational - not normative.


Best regards, Julian

                                                                Thanks again,
                                                                -- Mike