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

[Julian Reschke <[e-mail]>]

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

2.  Authenticated Requests

    Clients SHOULD make authenticated requests with a bearer token using
    the "Authorization" request header field defined by [RFC2617].

-> HTTPbis P7

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.


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?

    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.

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

    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.

    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 /
                      "!" / "#" / "$" / "%" / "&" / "'" / "(" / ")" /
                      "*" / "+" / "-" / "." / "/" / ":" / "<" / "=" /
                      ">" / "?" / "@" / "[" / "]" / "^" / "_" / "`" /
                      "{" / "|" / "}" / "~" / "\" / "," / ";"

    error           = "error" "=" quoted-string
    error-desc      = "error_description" "=" quoted-string
    error-uri       = "error_uri" "=" <"> URI-reference <">

-> missing I18N considerations
-> weird syntax (why underscore?)
-> the generic syntax allows token in addition to quoted-string; it's
pointless to rule that out here


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.