Subject: [OAUTH-WG] Dropping 'realm' parameter

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 24 Nov 2010 00:57:31 -0700

Over the past year we had consensus that the WWW-Authenticate header field 'realm' parameter is both poorly defined and useless in OAuth. Realm does not provide a useful mechanism for the complexity of OAuth tokens and the relationship between the protected resource and authorization server.

RFC 2617 language is cryptic at best with regard to when 'realm' is required. HTTPbis has an open issue (#177 [1]) for deciding what to do with 'realm'.

Since 'realm' does not provide value for OAuth, and is only adding noise and confusion, I am removing it from -11. I'm passing the ball to the HTTPbis WG to figure out how to deal with it.

My schedule has been very busy over the past few months and I was unable to complete -11 as planned. I will be publishing -11 this week no matter what shape the draft is in as it now includes many normative changes collected over the past few months.

EHL

[1] http://trac.tools.ietf.org/wg/httpbis/trac/ticket/177

---

From: John Kemp <[email-masked]>
Date: Wed, 24 Nov 2010 11:23:11 -0500

Forgot to reply to all...

---------- Forwarded message ----------
From: John Kemp <[email-masked]>
Date: Wed, Nov 24, 2010 at 11:22 AM
Subject: Re: [OAUTH-WG] Dropping 'realm' parameter
To: Eran Hammer-Lahav <[email-masked]>

Hi Eran,

> Since 'realm' does not provide value for OAuth, and is only adding noise and confusion, I am removing it from -11. I'm passing the ball to the HTTPbis WG to figure out how to deal with it.

RFC2617 (section 3.2.1 of http://tools.ietf.org/html/rfc2617) says
this when describing the realm parameter:

   'A string to be displayed to users so they know which username and
    password to use. This string should contain at least the name of
    the host performing the authentication and might additionally
    indicate the collection of users who might have access. An example
    might be "[email-masked]".'

Is it true then that realm provides no value for OAuth? The
information contained there could be passed to users in some other way
of course, if we assume that it will be done so by the authz service,
and not by the client... But probably it would be nice if there was
some interop around the display of the name of the service which is
asking the user to grant access to protected resources.

Regards,

- John

> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 24 Nov 2010 09:37:27 -0700

This description of realm doesn't really fit into the OAuth model, as OAuth challenges are not meant for end users, but for clients. The problem with realm is that the existing experience (i.e. Basic) does not match OAuth. Realm does not improve interop because we can't figure out how to use it properly. Note that 'realm' will still be allowed if someone can figure out a useful way to use it. Currently, if you drop 'realm', nothing happens - that's not a good sign.

EHL

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of John Kemp
> Sent: Wednesday, November 24, 2010 8:23 AM
> To: [email-masked]
> Subject: [OAUTH-WG] Fwd: Dropping 'realm' parameter
> 
> > Over the past year we had consensus that the WWW-Authenticate header
> field 'realm' parameter is both poorly defined and useless in OAuth. Realm
> does not provide a useful mechanism for the complexity of OAuth tokens
> and the relationship between the protected resource and authorization
> server.
> >
> > RFC 2617 language is cryptic at best with regard to when 'realm' is required.
> HTTPbis has an open issue (#177 [1]) for deciding what to do with 'realm'.
> >
> > Since 'realm' does not provide value for OAuth, and is only adding noise
> and confusion, I am removing it from -11. I'm passing the ball to the HTTPbis
> WG to figure out how to deal with it.
> 
> RFC2617 (section 3.2.1 of http://tools.ietf.org/html/rfc2617) says this when
> describing the realm parameter:
> 
> Is it true then that realm provides no value for OAuth? The information
> contained there could be passed to users in some other way of course, if we
> assume that it will be done so by the authz service, and not by the client...
> But probably it would be nice if there was some interop around the display of
> the name of the service which is asking the user to grant access to protected
> resources.
> 
> Regards,
> 
> - John
> 
> >
> > My schedule has been very busy over the past few months and I was
> unable to complete -11 as planned. I will be publishing -11 this week no
> matter what shape the draft is in as it now includes many normative changes
> collected over the past few months.
> >
> > EHL
> >

---

From: "Manger, James H" <[email-masked]>
Date: Thu, 25 Nov 2010 16:30:55 +1100

Eran,

> I will be publishing -11 this week no matter what shape the draft is in
> as it now includes many normative changes collected over the past few months.

You are probably still editing this text (https://github.com/theRazorBlade/draft-ietf-oauth/blob/master/draft-ietf-oauth-v2.txt) but here are some comments on the ABNF (mainly in section 6.2 "The WWW-Authenticate Response Header Field"):

The "error", "error_description", "error_uri", "scope", and extra parameters in a "WWW-Authenticate: OAuth2 ..." header have to appear in this order according to the ABNF. I think it would be better if they could appear in any order.

The ABNF implies there will be a extra leading comma (now that the mandatory "realm" attribute has been dropped), eg WWW-Authenticate: OAuth2 ,error="xyz".

Defining the "error" value as a <token>, but in double quotes is weird. I believe the idea is that header parameter values are either <token>s (no quotes) or <quoted-string>s (in double quotes).

The <scope> rule is missing the parameter name: scope = "scope" "=" ...
Its value is also strange. One choice is a <quoted-value>, which doesn't involve any quoting!

I think it would be better to simply make all these parameter values <quoted-string>s.

I assume the <credentials> and <access-token> rules should be removed as they will appear in the other part after the spec split.

Any new parameter value (defined with the <param-value> rule in section 7.3) should match <token> | <quoted-string>, not the OAuth-specific <quoted-value> rule.

Using <quoted-value> as a parameter value is not really legal as RFC2617 (and draft-ietf-httpbis-p7-auth-12) require <token> | <quoted-string> for parameter values. <quoted-value> includes characters not in <token>.

I guess it is too late to use space-separated or semicolon-separated parameters, instead of comma-separated parameters, to avoid confusion when multiple WWW-Authenticate headers are combined as HTTP intermediaries are allowed to do (in which case their values are separated with commas). [Not too late for OAuth, but too late for HTTP auth in general]

What error is returned when a request has no authentication?
The status code should be a 401 so the closest error is "invalid_token", though it is not really appropriate.

It is such a shame a WWW-Authentication response header can give details about OAuth errors, but not providing the basic OAuth information such as a user authorization URI, a client credential swap URI, and a token refresh URI.

--
James Manger

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 25 Nov 2010 00:04:01 -0700

Thanks James.

This is my current text. Let me know if there are more issues.

EHL

---

6.2.  The WWW-Authenticate Response Header Field

   If the protected resource request does not include authentication
   credentials, contains an invalid access token, or is malformed, the
   resource server MUST include the HTTP "WWW-Authenticate" response
   header field.  The "WWW-Authenticate" header field uses the framework
   defined by [RFC2617] as follows:

     challenge       = "OAuth2" RWS #param

     param           = scope /
                       error / error-desc / error-uri /
                       ( token "=" ( token / quoted-string ) )

     scope           = "scope" "=" <"> scope-v *( SP scope-v ) <">
     scope-v         = 1*quoted-char

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

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

   The "scope" attribute is a space-delimited list of scope values
   indicating the required scope of the access token for accessing the
   requested resource.  The "scope" attribute MUST NOT appear more than
   once.

   If the protected resource request included an access token and failed
   authentication, the resource server SHOULD include the "error"
   attribute to provide the client with the reason why the access
   request was declined.  The parameter value is described in
   Section 6.2.1.  In addition, the resource server MAY include the
   "error_description" attribute to provide a human-readable
   explanation, and the "error-uri" attribute with an absolute URI
   identifying a human-readable web page explaining the error.  The
   "error", "error_description", and "error_uri" attribute MUST NOT
   appear more than once.

   For example, in response to a protected resource request without
   authentication:

     HTTP/1.1 401 Unauthorized
     WWW-Authenticate: OAuth2

   And in response to a protected resource request with an
   authentication attempt using an expired access token:

     HTTP/1.1 401 Unauthorized
     WWW-Authenticate: OAuth2
                       error="invalid_token",
                       error_description="The access token expired"

---

From: "Manger, James H" <[email-masked]>
Date: Fri, 26 Nov 2010 09:52:03 +1000

This is better.

<scope> is not quite correct as the right-hand side is not quite a subset of <quoted-string> since <quoted-char> allows "\" as a character, instead of treating it as an escape character.
Option 1: remove "\" from <quoted-char>
Option 2: define <scope> as <"scope" "=" quoted-string>, and in the following paragraph say the "scope" attribute is a space-separated list of individual scope values -- more precisely, individual scope values are separated by <RWS> (and consequently cannot contain <RWS>).

I prefer option 2.

"WWW-Authenticate: OAuth2" is not strictly valid because it doesn't have a space <RWS> after the scheme.
RFC2617 and draft-ietf-httpbis-p7-auth-12 actually uses <1*SP>, instead of <RWS> in the generic definition of <challenge>.

Option 3: <challenge = "OAuth2" 1*SP 1#param>
          Add realm to <param>; add back paragraph saying the mandatory "realm" attribute allows protected resources on a server to be partitioned, as specified in RFC2617. Don't bother with any extra explanation.

Option 4: <challenge = "OAuth2" [ 1*SP #param ]>
          Add a paragraph explicitly saying this scheme does not quite obey the generic rules for schemes defined in RFC2617 because it does not require a "realm" parameter or, in fact, any parameters.

I prefer option 4, despite believing "realm" has some value. Most servers will have a single protection space (=realm), plus NTLM and Negotiate schemes already omit "realm", so I think disobeying RFC2617 here is ok (and fixing draft-ietf-httpbis-p7-auth-12).

<URI-Reference> should be
<URI-reference>

--
James Manger

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 30 Nov 2010 23:16:33 -0700

> From: Manger, James H [mailto:[email-masked]]
> Sent: Thursday, November 25, 2010 3:52 PM
> To: Eran Hammer-Lahav; OAuth WG
> Subject: RE: ABNF in draft 11
> 
> This is better.
> 
> <scope> is not quite correct as the right-hand side is not quite a subset of
> <quoted-string> since <quoted-char> allows "\" as a character, instead of
> treating it as an escape character.
> Option 2: define <scope> as <"scope" "=" quoted-string>, and in the
> following paragraph say the "scope" attribute is a space-separated list of
> individual scope values -- more precisely, individual scope values are
> separated by <RWS> (and consequently cannot contain <RWS>).
> 
> I prefer option 2.

I'm not sure about this yet. I'll leave it and talk to some ABNF gurus.

> RFC2617 and draft-ietf-httpbis-p7-auth-12 actually uses <1*SP>, instead of
> <RWS> in the generic definition of <challenge>.
> 
>           Add realm to <param>; add back paragraph saying the mandatory
> "realm" attribute allows protected resources on a server to be partitioned, as
> specified in RFC2617. Don't bother with any extra explanation.
> 
>           Add a paragraph explicitly saying this scheme does not quite obey the
> generic rules for schemes defined in RFC2617 because it does not require a
> "realm" parameter or, in fact, any parameters.
> 
> I prefer option 4, despite believing "realm" has some value. Most servers will
> have a single protection space (=realm), plus NTLM and Negotiate schemes
> already omit "realm", so I think disobeying RFC2617 here is ok (and fixing
> draft-ietf-httpbis-p7-auth-12).

Nah, I'll just open a ticket against p7 to fix it there.
 
> <URI-Reference> should be

Thanks.
 
EHL