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

[Mike Jones <[e-mail]>]

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

                                                                -- Mike


-----Original Message-----
From: [e-mail] [mailto:[e-mail]] On Behalf Of Julian Reschke
Sent: Tuesday, August 09, 2011 5:07 AM
To: OAuth WG ([e-mail])
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