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

From: Mike Jones <[email-masked]>
Date: Sat, 24 Sep 2011 00:13:06 +0000

Thanks for your comments, Julian.  Responses to them, which reflect the content of draft 09, follow inline.

                                                                -- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Julian Reschke
Sent: Tuesday, August 09, 2011 5:07 AM
To: OAuth WG ([email-masked])
Subject: [OAUTH-WG] draft-ietf-oauth-v2-bearer-08 HTTP syntax comments

Hi there,

below a few comments on dependencies to HTTPbis, and the actual header field syntax.

Best regards,

Julian

-- snip --

1.1.  Notational Conventions

    ...

    This document uses the Augmented Backus-Naur Form (ABNF) notation of

    [I-D.ietf-httpbis-p1-messaging], which is based upon the Augmented

    Backus-Naur Form (ABNF) notation of [RFC5234].  Additionally, the

    following rules are included from [RFC2617]: auth-param and realm;

    from [RFC3986]: URI-Reference; and from

    [I-D.ietf-httpbis-p1-messaging]: RWS and quoted-string.

auth-param and realm should come from I-D.ietf-httpbis-p7-auth (optimally from a version >= 16 which we should get out before the end of the month).

Done

2.  Authenticated Requests

    Clients SHOULD make authenticated requests with a bearer token using

    the "Authorization" request header field defined by [RFC2617].

-> HTTPbis P7

Done

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 )

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?

    o  The HTTP request method is one for which a body is permitted to be

       present in the request.  In particular, this means that the "GET"

       method MUST NOT be used.

GET permits a body; it's just not useful.

Changed sentence to "The HTTP request method is one for which the request body has defined semantics", per your suggestion in a private thread.

2.4.  The WWW-Authenticate Response Header Field

    If the protected resource request does not include authentication

    credentials or contains an invalid access token, the resource server

   MUST include the HTTP "WWW-Authenticate" response header field; it

    MAY include it in response to other conditions as well.  The

    "WWW-Authenticate" header field uses the framework defined by

    [RFC2617] as follows:

-> HTTPbis P7

Done

    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.

    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.

    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.)

There was an explicit working decision not to include language codes.  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.

-> weird syntax (why underscore?)

The OAuth specs have always used underscores to separate words in protocol messages.

-> 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.

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

---

From: Julian Reschke <[email-masked]>
Date: Sat, 24 Sep 2011 14:06:53 +0200

> content of draft 09, follow inline.

Thanks!

> HTTPbis P7 will introduce an alternative syntax ("b64token"), but that
> is restricted to a single instance and thus not extensible.
>
> 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):
>

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?

> 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"."

> 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?

> This issue is tracked as issue #26. The proposed resolution to this
> issue is being discussed in a separate thread.

OK.

> 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.

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

I didn't ask for language codes :-)

> 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:
>
> 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.

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

Well, it looks strange in an HTTP message.

> 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.

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

Thanks.

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

Best regards, Julian

---

From: Mike Jones <[email-masked]>
Date: Mon, 26 Sep 2011 19:03:11 +0000

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

                                                                -- Mike

-----Original Message-----
From: Julian Reschke [mailto:[email-masked]]
Sent: Saturday, September 24, 2011 5:07 AM
To: Mike Jones
Cc: [email-masked]
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!

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

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.

> 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?

> 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.

OK.

> 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.

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

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

> to be understood by end users.

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

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

> protocol messages.

It may, but these names reflect working group consensus.

> 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.

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

---

From: William Mills <[email-masked]>
Date: Mon, 26 Sep 2011 12:20:46 -0700 (PDT)

I'm gonna top reply...

> 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.

If the token can be transported in auth-params then I think you must define how that will happen.  It's too loose otherwise.  Go with this obvious and say if auth-parames are used then there must be a token= parameter that carries the token.  That way you are always guaranteed the token is present in the protocol.

-bill

________________________________
From: Mike Jones <[email-masked]>
To: Julian Reschke <[email-masked]>
Cc: "[email-masked]" <[email-masked]>
Sent: Monday, September 26, 2011 12:03 PM
Subject: Re: [OAUTH-WG] draft-ietf-oauth-v2-bearer-08 HTTP syntax comments

Thanks for your note, Julian.  Responses follow inline…
 
                                                                -- Mike
 
-----Original Message-----
From: Julian Reschke [mailto:[email-masked]] 
Sent: Saturday, September 24, 2011 5:07 AM
To: Mike Jones
Cc: [email-masked]
Subject: Re: [OAUTH-WG] draft-ietf-oauth-v2-bearer-08 HTTP syntax comments

Thanks!

 

 
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.

 
Maybe:

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

 
OK.

 
 
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.

 

 

 

 
 
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.

Thanks.

The remaining reference is informational – not normative.
 
Best regards, Julian
 
                                                                Thanks again,
                                                                -- Mike
 
_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: Julian Reschke <[email-masked]>
Date: Mon, 26 Sep 2011 21:24:57 +0200

On 2011-09-26 21:03, Mike Jones wrote:
> ...
> 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.

OK then; just checking :-)

 > ...
> 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.
> ...

This is a serialization issue. Just because one encoding is right in one 
place doesn't mean it's right somewhere else.

> Again, the working group explicitly decided to move from plain ASCII to

I think you need to make a conscious decision about the purpose. If it 
needs to support non-ASCII then using raw UTF-8 in the param may cause 
problems as explained above.

> 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.

First of all: it's pretty clear that you haven't written a conforming 
parser for WWW-Authenticate yet; you may want to look at the test cases 
at <http://greenbytes.de/tech/tc/httpauth/>.

Parsing definitively is *not* simple, and adding special cases over the 
generic syntax will make it even harder.

In particular, using double quotes for something that isn't a quoted 
string is incompatible with the base syntax. (Yes, this is a show-stopper).

> The remaining reference is informational – not normative.

Yes, but what is it for?

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 26 Sep 2011 21:26:53 +0200

On 2011-09-26 21:20, William Mills wrote:
> If the token can be transported in auth-params then I think you must
> define how that will happen. It's too loose otherwise. Go with this
> obvious and say if auth-parames are used then there must be a token=
> parameter that carries the token. That way you are always guaranteed the
> token is present in the protocol.
> ...

+1

In which case the syntax can get rid of the b64token special case 
altogether.

Best regards, Julian

---

From: Mike Jones <[email-masked]>
Date: Mon, 26 Sep 2011 20:10:14 +0000

Getting rid of the b64token would be an unnecessary breaking change.

-----Original Message-----
From: Julian Reschke [mailto:[email-masked]] 
Sent: Monday, September 26, 2011 12:27 PM
To: William Mills
Cc: Mike Jones; [email-masked]
Subject: Re: [OAUTH-WG] draft-ietf-oauth-v2-bearer-08 HTTP syntax comments

On 2011-09-26 21:20, William Mills wrote:
> parameter that carries the token. That way you are always guaranteed 
> the token is present in the protocol.
> ...

+1

In which case the syntax can get rid of the b64token special case altogether.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 26 Sep 2011 22:18:04 +0200

> Getting rid of the b64token would be an unnecessary breaking change.

You're at draft state, right?

If you want to keep b64token *and* be able to use params, then you'll 
need an alternate syntax that puts the token into param (which, 
arguably, would have been the better choice anyway).

Best regards, Julian