Subject: [OAUTH-WG] In the spirit of compromise

From: Mike Jones <[email-masked]>
Date: Thu, 7 Apr 2011 16:52:57 +0000

Having thought about it over night and discussed it, I'm willing to drop my objection the WWW-Authenticate response not being in the framework specification, so as to close an open issue that could delay completion of the specifications.

Eran, in return, I'd like to ask you to drop your objection to extending the error registry in the framework spec so that "resource server error response" is in the "error usage location" list.  If you do so, this would close another open issue that could delay completion of the specifications.

                                                                Thank you,
                                                                -- Mike

From: Eran Hammer-Lahav [mailto:[email-masked]]
Sent: Wednesday, April 06, 2011 4:35 PM
To: Mike Jones; OAuth WG
Subject: OAuth2 scheme (was Error registry proposal (round 3))

Well... Can't say I didn't see this coming :)

The issue is not simply about putting a section back, but about the overall protocol architecture and how it complies with HTTP.

For example, taking the MAC draft, how do you envision the resource server responding to a failed authentication attempt? A 401 response and what header(s)? WWW-Authenticate with 'OAuth2' scheme? 'MAC' scheme? Both?

Also see: http://trac.tools.ietf.org/wg/httpbis/trac/ticket/78

You might think you are asking for a simple feature, but this is moving the protocol from a purely authorization protocol to an authentication protocol which is what the split of the token types was designed to accomplish.

What I am asking for is to provide full examples of how you envision the OAuth2 scheme to work in practice, especially considering the MAC draft. Assume that the MAC draft, since it is defined as a general purpose scheme, is not going to change (for the sake of argument only), do you envision it being used differently when combines with an OAuth access token? That would be bad.

I removed the WWW-Authenticate header and the OAuth2 scheme because it served no purpose and no one demonstrated how it will be actually used. WRAP is not a good example because WRAP is a closed protocol (just like OAuth 1.0). There is no way to add new authentication schemes to WRAP and in that context, it makes sense to define a scheme. But here it will mean moving backwards to a protocol where only OAuth-specific authentication schemes can be used, and they all must be defined as extensions of this master OAuth2 scheme.

There was pretty good consensus not to define a master scheme with sub schemes. That is well documented on the list. This thread included the discussion about using a common prefix for scheme names, etc. Hope we don't have to repeat that.

So if OAuth2 is not a master scheme for all other scheme to be defined as sub-schemes, what is it? I don't have an answer and we kinda need one to put such a scheme back in the document.

EHL

From: Mike Jones [mailto:[email-masked]]
Sent: Wednesday, April 06, 2011 4:13 PM
To: Eran Hammer-Lahav; OAuth WG
Subject: RE: Error registry proposal (round 3)

Actually, you correctly point out (indirectly), that this is related to one of the open issues that needs to be resolved to complete the specs when you wrote "For such a registry to be useful, you also need to standardize the authentication header across all schemes and define a standard parameter used to deliver such error codes".

This open issue (which there wasn't time to discuss during last week's meeting) was the removal of the WWW-Authenticate Response Header.  This feature was present in WRAP and earlier OAuth drafts but was removed without a clear consensus to do so.  And indeed, during our private discussions on how the draft should be split, at that time, you took the position that the WWW-Authenticate response should remain in the framework spec.

The result has been that there is different and incompatible WWW-Authenticate response functionality in multiple related drafts - specifically draft-hammer-oauth-v2-mac-token-02 and draft-ietf-oauth-v2-bearer-04.  Interoperability and developers would both be better served by moving this functionality back into the core. I don't believe that each related OAuth specification should have to separately specify this functionality.  As this was not discussed during last week's meeting, a consensus call from the chairs may be necessary to resolve this issue.

                                                                -- Mike

From: Eran Hammer-Lahav [mailto:[email-masked]]
Sent: Wednesday, April 06, 2011 3:58 PM
To: Mike Jones; OAuth WG
Subject: RE: Error registry proposal (round 3)

Putting aside my view that a registry for resource server error responses across HTTP authentication schemes isn't very useful or interesting, I don't have an objection to the bearer token specification defining such general purpose registry. In a way, it is similar to the error response headers defined by Digest, only never made generally applicable.

The difference in our approaches is that I don't consider the bearer token or mac token specs to be extensions of the v2 spec, but fully specified HTTP authentication schemes with OAuth 2.0 binding (i.e. the access token type registration). Because of that, I don't think the v2 spec is the right place for such a registry, which is really about HTTP authentication schemes and not OAuth. Therefore, I think it will be more confusing to put such a registry in v2.

I'll give you an example. Suppose someone will define a Digest access token type. When issuing one, the server will send an access token (to be used as username) and a secret (to be used as password). To use such a token, the client will use the HTTP Digest scheme (as is). Digest defines its own set and method or specifying error code. Would you expect those to be registered in your proposed registry? I would assume not.

For such a registry to be useful, you also need to standardize the authentication header across all schemes and define a standard parameter used to deliver such error codes. However, we already moved away from that design by defining separate HTTP authentication schemes for each token type.

But again, I don't have an objection to such a registry defined in the bearer token spec. I have no intentions of using it for any HTTP authentication scheme I plan to author.

EHL

From: Mike Jones [mailto:[email-masked]]
Sent: Wednesday, April 06, 2011 3:39 PM
To: Eran Hammer-Lahav; OAuth WG
Subject: RE: Error registry proposal (round 3)

The problem with that situation is that it doesn't provide a central registry for resource server error responses across specs, unlike the other kinds of OAuth error responses.  I could define that registry in the bearer token spec, but it would be less confusing to unify it with the proposed registry in the framework spec.  I suspect developers would thank us for doing that.

What do you say?

                                                                -- Mike

From: Eran Hammer-Lahav [mailto:[email-masked]]
Sent: Wednesday, April 06, 2011 2:58 PM
To: Mike Jones; OAuth WG
Subject: RE: Error registry proposal (round 3)

Hi Mike,

This is intentional. The error registry defined in v2 is not designed to record errors for the protected resource endpoint response or the WWW-Authenticate response header when used with the Bearer token scheme (or any other scheme).

The only purpose of the registry is to avoid name collisions between two errors used differently with the v2 specification. Since errors used with the Bearer token scheme will never appear in the same place as the v2 endpoints, there is no need for combining these two registries.

If the bearer token specification requires error extensibility, you should retain the registry there and limit it to just the protected resource response space. Ideally, you would limit it to just the WWW-Authenticate header 'error' parameter when used with the Bearer scheme. The MAC scheme does not use error codes, but instead, relies fully on HTTP status code since no additional error conditions were identified.

Also, since your ABNF permits adding additional Authorization header parameters, you might want to consider defining a process for doing that, if you are going to define an error registry. Currently, to add additional parameters, one has to update the Bearer token RFC, in contrast to simply registering a new error code (which is likely to come out of a new parameter).

EHL

From: Mike Jones [mailto:[email-masked]]
Sent: Wednesday, April 06, 2011 2:25 PM
To: Eran Hammer-Lahav; OAuth WG
Subject: RE: Error registry proposal (round 3)

Thanks for writing this up, Eran.  I believe that this is a step in the right direction.

Wearing my Bearer Token spec editor hat, I just tried to go through the exercise of editing my document to use the registry in draft 15 to register the errors defined in the bearer token spec and I hit a roadblock.  Specifically, while the errors defined by my spec are returned by resource servers (flow F in Figure 1), the registry defined by draft 15 does not include "resource server error response" in the "error usage location" list.  Can you please add this additional error usage location so that the registry can be used by the bearer token specification?

At that point, I believe we'll be able to close the open issue about the need for an error registry, and I'll update my draft accordingly.

                                                                Thank you,
                                                                -- Mike

From: [email-masked] [mailto:[email-masked]] On Behalf Of Eran Hammer-Lahav
Sent: Tuesday, April 05, 2011 3:52 PM
To: OAuth WG
Subject: [OAUTH-WG] Error registry proposal (round 3)

The following is my new proposal, based on Mike Jones' and my earlier proposals. It is basically a combination of the two.

This proposal does not allow defining new error codes unless another extension is involved (new grant type, request parameter, token type). The reason for not defining an open ended error registry is that defining new error codes for existing implementations is bad for interoperability and can lead to unexpected results (developers not taking into account receiving a new error when talking to a compliant 2.0 server). We don't have any use cases for defining such new errors for the v2 specification. New errors only come from extensions and must be defined in that context.

I have applied to changes to the -14 draft and clearly marked them with [[Pending Consensus]] so that there is no issue with removing them or changing them later.

---

Add to the error codes list in sections 4.1.2.1 and 4.2.2.1:

         a 4xx or 5xx HTTP status code (except for 400 and 401)
               The authorization server MAY set the "error" parameter
               value to a numerical HTTP status code from the 4xx or 5xx
               range, with the exception of the 400 (Bad Request) and
               401 (Unauthorized) status codes.  For example, if the
               service is temporarily unavailable, the authorization
               server MAY return an error response with "error" set to
               "503".

Add a new section 8.4:

8.4.  Defining Additional Error Codes

   In cases where protocol extensions (i.e. access token types,

   extension parameters, or extension grant types) require additional

   error codes to be used with the authorization code grant error

   response (Section 4.1.2.1), the implicit grant error response

   (Section 4.2.2.1), or the token error response (Section 5.2), such

   error codes MAY be defined.

   Extension error codes MUST be registered (following the procedures in

   Section 10.3) if the extension they are used in conjunction with is

   registered.  Additional error codes used with unregistered extensions

   MAY be registered.

   Error codes MUST conform to the error-code ABNF, and SHOULD be

   prefixed by an identifying name when possible.  For example, an error

   identifying an invalid value set to the extension parameter "example"

   should be named "example_invalid".

     error-code   = ALPHA *error-char

     error-char   = "-" / "." / "_" / DIGIT / ALPHA

Add a new section 10.3:

10.3.  The OAuth Extensions Error Registry

   This specification establishes the OAuth extensions error registry.

   Additional error codes used together with other protocol extensions

   (i.e. extension grant types, access token types, or extension

   parameters) are registered on the advice of one or more Designated

   Experts (appointed by the IESG or their delegate), with a

   Specification Required (using terminology from [RFC5226]).  However,

   to allow for the allocation of values prior to publication, the

   Designated Expert(s) may approve registration once they are satisfied

   that such a specification will be published.

   Registration requests should be sent to the [TBD]@ietf.org mailing

   list for review and comment, with an appropriate subject (e.g.,

   "Request for error code: example"). [[ Note to RFC-EDITOR: The name

   of the mailing list should be determined in consultation with the

   IESG and IANA.  Suggested name: oauth-ext-review. ]]

   Within at most 14 days of the request, the Designated Expert(s) will

   either approve or deny the registration request, communicating this

   decision to the review list and IANA.  Denials should include an

   explanation and, if applicable, suggestions as to how to make the

   request successful.

   Decisions (or lack thereof) made by the Designated Expert can be

   first appealed to Application Area Directors (contactable using

   [email-masked]<mailto:[email-masked]> email address or directly by looking up their

   email addresses on http://www.iesg.org/ website) and, if the

   appellant is not satisfied with the response, to the full IESG (using

   the [email-masked]<mailto:[email-masked]> mailing list).

   IANA should only accept registry updates from the Designated

   Expert(s), and should direct all requests for registration to the

   review mailing list.

10.3.1.  Registration Template

   Error name:

      The name requested (e.g., "example").

   Error usage location:

      The location(s) where the error can be used.  The possible

      locations are: authorization code grant error response

      (Section 4.1.2.1), implicit grant error response

      (Section 4.2.2.1), or token error response (Section 5.2).

   Related protocol extension:

      The name of the extension grant type, access token type, or

      extension parameter, the error code is used in conjunction with.

   Change controller:

      For standards-track RFCs, state "IETF".  For others, give the name

      of the responsible party.  Other details (e.g., postal address,

      e-mail address, home page URI) may also be included.

   Specification document(s):

      Reference to document that specifies the error code, preferably

      including a URI that can be used to retrieve a copy of the

      document.  An indication of the relevant sections may also be

      included, but is not required.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 7 Apr 2011 11:20:12 -0700

Hi Mike,

I don't think this is a matter of each one giving up something.

I have significant technical reasons for my position, and I am much more interested in taking the time discussing these than just finding an easy way to close issues. There is no reason to expect a thorough discussion taking more than a week or two, which will still be faster than the time it will take to finish review on the security considerations section.

Adding an error registry for error codes used by the various HTTP authentication schemes for use in 401 responses in the WWW-Authenticate header does not make technical sense for the v2 specification as it currently stand. It would only make sense if we were to define a master HTTP authentication scheme called OAuth2 (or similar) and require that every new token type uses that scheme with a sub-scheme. Then, such an error registry will make sense.

For example:

Authorization: OAuth2 type="bearer", token="asdalsijdlkasjd"
Authorization: OAuth2 type="mac", id="asdasdasd", etc...

If you have use cases and requirements for introducing such a new master HTTP authentication scheme, please present them and we will have a discussion about how to best address them, including the possibility of adding such a scheme. In the past, such a proposal was rejected due to lack of working group consensus. If I recall correctly, only Marius was advocating that approach.

Alternatively, if you have use cases or requirements for introducing just the WWW-Authenticate side of an OAuth2 authorization scheme (your open issue), which includes an 'error' attribute for use with the proposed registry, please present those and explain how it will work alongside the Bearer and MAC schemes (as currently drafted).

Thanks,

EHL

From: Mike Jones [mailto:[email-masked]]
Sent: Thursday, April 07, 2011 9:53 AM
To: Eran Hammer-Lahav; OAuth WG
Subject: In the spirit of compromise

                                                                Thank you,
                                                                -- Mike

EHL

                                                                -- Mike

EHL

What do you say?

                                                                -- Mike

Hi Mike,

EHL

                                                                Thank you,
                                                                -- Mike

---

Add a new section 8.4:

   MAY be registered.

Add a new section 10.3:

   request successful.

   review mailing list.

   Error name:

   Error usage location:

   Change controller:

---

From: "William J. Mills" <[email-masked]>
Date: Thu, 7 Apr 2011 12:20:23 -0700 (PDT)

For HTTP authentication things, is the right place to simple define a new HTTP status code that does what we need?  There is already a registry for that and the "slow down" example is one that might make sense in the more general HTTP context.

________________________________
From: Eran Hammer-Lahav <[email-masked]>
To: Mike Jones <[email-masked]>; OAuth WG <[email-masked]>
Sent: Thursday, April 7, 2011 11:20 AM
Subject: Re: [OAUTH-WG] In the spirit of compromise

Hi Mike,
 
I don’t think this is a matter of each one giving up something.

 
For example:
 
Authorization: OAuth2 type=”bearer”, token=”asdalsijdlkasjd”
Authorization: OAuth2 type=”mac”, id=”asdasdasd”, etc…

Alternatively, if you have use cases or requirements for introducing just the WWW-Authenticate side of an OAuth2 authorization scheme (your open issue), which includes an ‘error’ attribute for use with the proposed registry, please present those and explain how it will work alongside the Bearer and MAC schemes (as currently drafted).
 
Thanks,
 
EHL

From:Mike Jones [mailto:[email-masked]] 
Sent: Thursday, April 07, 2011 9:53 AM
To: Eran Hammer-Lahav; OAuth WG
Subject: In the spirit of compromise
 
Having thought about it over night and discussed it, I’m willing to drop my objection the WWW-Authenticate response not being in the framework specification, so as to close an open issue that could delay completion of the specifications.
 
Eran, in return, I’d like to ask you to drop your objection to extending the error registry in the framework spec so that “resource server error response” is in the “error usage location” list.  If you do so, this would close another open issue that could delay completion of the specifications.
 
                                                                Thank you,
                                                                -- Mike
 
From:Eran Hammer-Lahav [mailto:[email-masked]] 
Sent: Wednesday, April 06, 2011 4:35 PM
To: Mike Jones; OAuth WG
Subject: OAuth2 scheme (was Error registry proposal (round 3))
 
Well… Can’t say I didn’t see this coming J

For example, taking the MAC draft, how do you envision the resource server responding to a failed authentication attempt? A 401 response and what header(s)? WWW-Authenticate with ‘OAuth2’ scheme? ‘MAC’ scheme? Both?

 

There was pretty good consensus not to define a master scheme with sub schemes. That is well documented on the list. This thread included the discussion about using a common prefix for scheme names, etc. Hope we don’t have to repeat that.
 
So if OAuth2 is not a master scheme for all other scheme to be defined as sub-schemes, what is it? I don’t have an answer and we kinda need one to put such a scheme back in the document.
 
EHL
 
From:Mike Jones [mailto:[email-masked]] 
Sent: Wednesday, April 06, 2011 4:13 PM
To: Eran Hammer-Lahav; OAuth WG
Subject: RE: Error registry proposal (round 3)
 
Actually, you correctly point out (indirectly), that this is related to one of the open issues that needs to be resolved to complete the specs when you wrote “For such a registry to be useful, you also need to standardize the authentication header across all schemes and define a standard parameter used to deliver such error codes”.
 
This open issue (which there wasn’t time to discuss during last week’s meeting) was the removal of the WWW-Authenticate Response Header.  This feature was present in WRAP and earlier OAuth drafts but was removed without a clear consensus to do so.  And indeed, during our private discussions on how the draft should be split, at that time, you took the position that the WWW-Authenticate response should remain in the framework spec.
 
The result has been that there is different and incompatible WWW-Authenticate response functionality in multiple related drafts – specifically draft-hammer-oauth-v2-mac-token-02 and draft-ietf-oauth-v2-bearer-04.  Interoperability and developers would both be better served by moving this functionality back into the core. I don’t believe that each related OAuth specification should have to separately specify this functionality.  As this was not discussed during last week’s meeting, a consensus call from the chairs may be necessary to resolve this issue.
 
                                                                -- Mike
 
From:Eran Hammer-Lahav [mailto:[email-masked]] 
Sent: Wednesday, April 06, 2011 3:58 PM
To: Mike Jones; OAuth WG
Subject: RE: Error registry proposal (round 3)
 
Putting aside my view that a registry for resource server error responses across HTTP authentication schemes isn’t very useful or interesting, I don’t have an objection to the bearer token specification defining such general purpose registry. In a way, it is similar to the error response headers defined by Digest, only never made generally applicable.
 
The difference in our approaches is that I don’t consider the bearer token or mac token specs to be extensions of the v2 spec, but fully specified HTTP authentication schemes with OAuth 2.0 binding (i.e. the access token type registration). Because of that, I don’t think the v2 spec is the right place for such a registry, which is really about HTTP authentication schemes and not OAuth. Therefore, I think it will be more confusing to put such a registry in v2.
 
I’ll give you an example. Suppose someone will define a Digest access token type. When issuing one, the server will send an access token (to be used as username) and a secret (to be used as password). To use such a token, the client will use the HTTP Digest scheme (as is). Digest defines its own set and method or specifying error code. Would you expect those to be registered in your proposed registry? I would assume not.

But again, I don’t have an objection to such a registry defined in the bearer token spec. I have no intentions of using it for any HTTP authentication scheme I plan to author.
 
EHL

From:Mike Jones [mailto:[email-masked]] 
Sent: Wednesday, April 06, 2011 3:39 PM
To: Eran Hammer-Lahav; OAuth WG
Subject: RE: Error registry proposal (round 3)
 
The problem with that situation is that it doesn’t provide a central registry for resource server error responses across specs, unlike the other kinds of OAuth error responses.  I could define that registry in the bearer token spec, but it would be less confusing to unify it with the proposed registry in the framework spec.  I suspect developers would thank us for doing that.
 
What do you say?
 
                                                                -- Mike
 
From:Eran Hammer-Lahav [mailto:[email-masked]] 
Sent: Wednesday, April 06, 2011 2:58 PM
To: Mike Jones; OAuth WG
Subject: RE: Error registry proposal (round 3)
 
Hi Mike,

 
If the bearer token specification requires error extensibility, you should retain the registry there and limit it to just the protected resource response space. Ideally, you would limit it to just the WWW-Authenticate header ‘error’ parameter when used with the Bearer scheme. The MAC scheme does not use error codes, but instead, relies fully on HTTP status code since no additional error conditions were identified.

EHL

From:Mike Jones [mailto:[email-masked]] 
Sent: Wednesday, April 06, 2011 2:25 PM
To: Eran Hammer-Lahav; OAuth WG
Subject: RE: Error registry proposal (round 3)

Wearing my Bearer Token spec editor hat, I just tried to go through the exercise of editing my document to use the registry in draft 15 to register the errors defined in the bearer token spec and I hit a roadblock.  Specifically, while the errors defined by my spec are returned by resource servers (flow F in Figure 1), the registry defined by draft 15 does not include “resource server error response” in the “error usage location” list.  Can you please add this additional error usage location so that the registry can be used by the bearer token specification?
 
At that point, I believe we’ll be able to close the open issue about the need for an error registry, and I’ll update my draft accordingly.
 
                                                                Thank you,
                                                                -- Mike
 
From:[email-masked] [mailto:[email-masked]] On Behalf Of Eran Hammer-Lahav
Sent: Tuesday, April 05, 2011 3:52 PM
To: OAuth WG
Subject: [OAUTH-WG] Error registry proposal (round 3)
 
The following is my new proposal, based on Mike Jones’ and my earlier proposals. It is basically a combination of the two.

 
---

Add a new section 8.4:

 

Add a new section 10.3:

 

 
   Decisions (or lack thereof) made by the Designated Expert can be
   first appealed to Application Area Directors (contactable using
   [email-masked] email address or directly by looking up their
   email addresses on http://www.iesg.org/ website) and, if the
   appellant is not satisfied with the response, to the full IESG (using
   the [email-masked] mailing list).

 
   Error name:

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

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 7 Apr 2011 13:28:38 -0700

Hey Bill,

It might be in general for some error conditions (such as slow down). I think the current proposal offers a good balance between reusing HTTP codes and defining more detailed error codes for the common 401/400 errors.

The issue here is about new HTTP authentication schemes, how they relate back to OAuth, and how they might share error codes.

EHL

From: William J. Mills [mailto:[email-masked]]
Sent: Thursday, April 07, 2011 12:20 PM
To: Eran Hammer-Lahav; Mike Jones; OAuth WG
Subject: Re: [OAUTH-WG] In the spirit of compromise

For example:

Thanks,

EHL

                                                                Thank you,
                                                                -- Mike

Well… Can’t say I didn’t see this coming ☺

EHL

                                                                -- Mike

EHL

What do you say?

                                                                -- Mike

Hi Mike,

EHL

                                                                Thank you,
                                                                -- Mike

---

Add a new section 8.4:

   MAY be registered.

Add a new section 10.3:

   that such a specification will be

 published.

   either approve or deny the registration request,

 communicating this

   request successful.

   email addresses on

 http://www.iesg.org/ website) and, if the

   review mailing list.

   Error name:

   Error usage location:

      The name of the extension grant type, access

 token type, or

   Change controller:

      including a

 URI that can be used to retrieve a copy of the

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