Subject: [OAUTH-WG] Error extensibility proposal

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 29 Mar 2011 16:01:51 -0700

*** Requirements

The following proposal is based on two requirements:

1. Provide a way to return an OAuth error response for error situations other then 400 and 401. For example, if the server is temporarily unavailable, it will return an HTTP 503 status. However, it is often desirable to still return a response body using the same format as any other error. This makes client development easier, having to always check for a single error code.

2. Allow extensions modifying the behavior of the authorization and token endpoints via additional request/response parameters to define additional error codes to go along with the new functionality. For example, the UX extension defines the 'display' parameter. It could define a matching 'unsupported_display' error response.

No other use cases were identified for error extensibility. Note that this proposal is strictly limited to error resulting from the authorization and token endpoints. No other endpoints are included (in particular, protected resources are not covered by this proposal).

*** Design goals

The proposal was specifically designed to be minimalistic, tailored to the specific use cases defined, and as effortless as possible. This avoids defining error codes identical to existing HTTP status codes, as well as bind new errors to specific extension parameters. Since the error is useless without understanding the extension, this method guarantees that those developing and implementing extensions will present it as a complete unit.

*** Proposal

- Non 400/401 responses

If the HTTP response status code is 4xx (other than 400/401) or 5xx, the 'error' parameter SHOULD be set to the HTTP status code. For example:

     HTTP/1.1 503 Service Unavailable
     Content-Type: application/json
     Cache-Control: no-store

     {
       "error":"503"
     }

This will also enable passing HTTP status codes such as 503 via the redirection response which is currently not possible. It will allow the authorization server to indicate a 503 situation without defining another error code that has the exact same meaning.

- Extension errors

Instead of defining an additional error registry, I propose we add a single field to the 'OAuth parameters registry' template:

    Additional error codes:
        Additional error codes related to the parameter usage. Error codes SHOULD begin with the parameter name
        when possible (e.g. 'example_invalid' error code for use with the 'example' parameter).

Error collisions are unlikely because when a new extension is authored, the registry is reviewed for potential conflicts. Since the errors are extension-specific, collisions only matter if two extensions are to be used together. In that case, the review process will identify any potential problems. And since the errors are meaningless without understanding the extension, a registry with a random list of errors is not very helpful.

*** Feedback

Please send any feedback, comments, support, and objections by 3/1 (so it can be included or not in -14).

EHL

---

From: Mike Jones <[email-masked]>
Date: Thu, 31 Mar 2011 18:31:11 +0000

I object to this proposal on two grounds:

First, changing some of the "error" return codes to HTTP numbers is an unnecessary and unsolicited breaking change at a time that we should be stabilizing the spec.

Second, the OAuth Errors registry is simpler and follows IETF standard practices.  I know of no other specification where a parameters registry is overloaded in this manner.  Please incorporate the OAuth Errors registry into the framework specification in lieu of this proposal.

				Thank you,
				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Eran Hammer-Lahav
Sent: Tuesday, March 29, 2011 4:02 PM
To: OAuth WG
Subject: [OAUTH-WG] Error extensibility proposal

*** Requirements

*** Design goals

*** Proposal

- Non 400/401 responses

     {
       "error":"503"
     }

- Extension errors

    Additional error codes:

*** Feedback

EHL

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

---

From: Anthony Nadalin <[email-masked]>
Date: Thu, 31 Mar 2011 18:39:55 +0000

I also object, an error registry the proper approach here.

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Mike Jones
Sent: Thursday, March 31, 2011 11:31 AM
To: Eran Hammer-Lahav; OAuth WG
Subject: Re: [OAUTH-WG] Error extensibility proposal

				Thank you,
				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Eran Hammer-Lahav
Sent: Tuesday, March 29, 2011 4:02 PM
To: OAuth WG
Subject: [OAUTH-WG] Error extensibility proposal

*** Requirements

*** Design goals

*** Proposal

- Non 400/401 responses

     {
       "error":"503"
     }

- Extension errors

    Additional error codes:

*** Feedback

EHL

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 31 Mar 2011 14:43:26 -0700

'PROPER' REQUIRES USE CASES AND REQUIREMENTS!

You have to show how the proposal does not satisfy you requirements. It fully satisfies all the requirements presented to the working group.

EHL

> From: Anthony Nadalin [mailto:[email-masked]]
> Sent: Thursday, March 31, 2011 11:40 AM
> To: Mike Jones; Eran Hammer-Lahav; OAuth WG
> Subject: RE: Error extensibility proposal
> 
> First, changing some of the "error" return codes to HTTP numbers is an
> unnecessary and unsolicited breaking change at a time that we should be
> stabilizing the spec.
> 
> Second, the OAuth Errors registry is simpler and follows IETF standard
> practices.  I know of no other specification where a parameters registry is
> overloaded in this manner.  Please incorporate the OAuth Errors registry into
> the framework specification in lieu of this proposal.
> 
> 				Thank you,
> 				-- Mike
> 
> 1. Provide a way to return an OAuth error response for error situations other
> then 400 and 401. For example, if the server is temporarily unavailable, it will
> return an HTTP 503 status. However, it is often desirable to still return a
> response body using the same format as any other error. This makes client
> development easier, having to always check for a single error code.
> 
> 2. Allow extensions modifying the behavior of the authorization and token
> endpoints via additional request/response parameters to define additional
> error codes to go along with the new functionality. For example, the UX
> extension defines the 'display' parameter. It could define a matching
> 'unsupported_display' error response.
> 
> No other use cases were identified for error extensibility. Note that this
> proposal is strictly limited to error resulting from the authorization and token
> endpoints. No other endpoints are included (in particular, protected
> resources are not covered by this proposal).
> 
> *** Design goals
> 
> The proposal was specifically designed to be minimalistic, tailored to the
> specific use cases defined, and as effortless as possible. This avoids defining
> error codes identical to existing HTTP status codes, as well as bind new errors
> to specific extension parameters. Since the error is useless without
> understanding the extension, this method guarantees that those developing
> and implementing extensions will present it as a complete unit.
> 
> *** Proposal
> 
> - Non 400/401 responses
> 
> If the HTTP response status code is 4xx (other than 400/401) or 5xx, the
> 'error' parameter SHOULD be set to the HTTP status code. For example:
> 
> This will also enable passing HTTP status codes such as 503 via the redirection
> response which is currently not possible. It will allow the authorization server
> to indicate a 503 situation without defining another error code that has the
> exact same meaning.
> 
> - Extension errors
> 
> Instead of defining an additional error registry, I propose we add a single field
> to the 'OAuth parameters registry' template:
> 
>     Additional error codes:
> Error collisions are unlikely because when a new extension is authored, the
> registry is reviewed for potential conflicts. Since the errors are extension-
> specific, collisions only matter if two extensions are to be used together. In
> that case, the review process will identify any potential problems. And since
> the errors are meaningless without understanding the extension, a registry
> with a random list of errors is not very helpful.
> 
> *** Feedback
>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 31 Mar 2011 15:50:57 -0700

> From: Mike Jones [mailto:[email-masked]]

No errors were changed!

Merely, a few potential errors were added, some match your very own examples! To call this breaking changes is untrue and ridiculous. In particular coming from someone advocating error extensibility. You have to see the total absurdity of your argument here.

> Second, the OAuth Errors registry is simpler

How is it simpler? It requires double registration for all the use cases raised while my proposal makes it a trivial matter (just adding a field to an existing registration request).

> and follows IETF standard practices.

Both are registries and both common IETF practice. If you are going to use process arguments, you need to make sure they are both accurate and complete.

>  I know of no other specification where a parameters registry is
> overloaded in this manner.

This is not overloading anything. Again, get your facts right.

The use cases clearly show that there are only two kinds of additional errors required: matching HTTP codes to non 400/401 cases and those related to extensions which are all implemented via the introduction of additional parameters. In this case, the error is merely an attribute of the parameter added, nothing more.

If you show a valid use case for other requirements, such that require the registration of an error without a matching HTTP code or an extension parameter, I'll reconsider the design proposed.

Since you have failed to even defend your own examples previously posted, I'm going to ignore this objection on the ground that it is without merit.

EHL

---

From: Peter Saint-Andre <[email-masked]>
Date: Fri, 01 Apr 2011 02:26:44 +0200

On 3/30/11 1:01 AM, Eran Hammer-Lahav wrote:

> Please send any feedback, comments, support, and objections by 3/1

I think you meant 4/1. :)

> (so it can be included or not in -14).

Given how busy things are during IETF week, I'm sure that many people
who are in Prague for the meeting might not have time to review the
proposal in 48 hours or less. I know I won't have time to double-check
the list threads and document history on this point until next week.

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 31 Mar 2011 18:00:57 -0700

Yeah, 4/1 and it gives people the chance to express their views at the meeting.

It's a draft... which is the way this WG has been more effective in getting people's attentions to proposal. I'll include it in -14 and take it out if we have another solution or lack of consensus when I do -15 with the first security consideration section.

EHL

> From: Peter Saint-Andre [mailto:[email-masked]]
> Sent: Thursday, March 31, 2011 5:27 PM
> To: Eran Hammer-Lahav
> Cc: OAuth WG

---

From: Marius Scurtescu <[email-masked]>
Date: Thu, 31 Mar 2011 18:06:46 -0700

> Error collisions are unlikely because when a new extension is authored, the registry is reviewed for potential conflicts. Since the errors are extension-specific, collisions only matter if two exte…

Many error codes (if not most) are not parameter specific. Will this
lead to the registration of fake parameter names just to be used as
error prefixes?

If we are going down this route, why don't we require extensions to
register just a prefix?

Marius

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 31 Mar 2011 18:43:37 -0700

Hi Marius,

> From: Marius Scurtescu [mailto:[email-masked]]
> Sent: Thursday, March 31, 2011 6:07 PM

> Many error codes (if not most) are not parameter specific.

Like what? After a long debate, not a single use case was presented for a new error code that is not:

1. overlapping with an existing HTTP code (4xx, 5xx)
2. directly relates to an extension parameter

Present new use cases and I'll reconsider. This proposal is 100% fit for the given requirements.
 
> Will this lead to the registration of fake parameter names just to be used as error prefixes?

No. If there is an actual need to define a new error code that is not related to at least one extension, I agree that we need a different solution (we can always use the ability to update the RFC). But I have not seen any such need.

In fact, I argue that such additional generic error codes are bad for interoperability. If every client implements the same set of error codes defined in v2, we know that they will all interop well when it comes to an error condition. If the error is the result of an extension, the client must understand that extension to understand any additional error code. Nothing but extension parameter can change the behavior of this protocol. We don't have other extension points that can produce such a change. No change - no new error conditions.

Another example of error code extensibility is the need to express more specific error conditions related to extension grant types. It might be necessary to express why a grant type was rejected, beyond just 'invalid_grand'. However, *replacing* 'invalid_grant' with a more specific error code would be bad for interoperability because it will break existing libraries designed to be extensible but do not offer a fully extensible error code handler (just not likely). The right solution would be to define an additional, grant-type-specific response parameter that will provide sub-meaning to the 'invalid_grant' code.

In this case, no new error codes are even registered, just an extension response parameter.

> If we are going down this route, why don't we require extensions to register
> just a prefix?

What route? Registering a prefix is a good idea if we expect a flood of extension parameters. I'm not.

<rant>
The bottom line is that this proposal is purposely not creating an open-ended registry that will end up being as counter-productive as the OAuth 1.0 error codes wiki page. It is design to put the least amount of process and hurdle in the way of developer extending the protocol.

I am happy to suggest alternatives or even adopt Mike Jones' proposal for an error registry if only someone can present a *single* use case that defines a new requirement not covered by this proposal. Give me just *one* example where this is incomplete. But short of that, discussing the shortcoming of a proposal without clear requirements is a total waste of time.

Extensibility is where most protocol fuck up (pardon my language). It is where crap enters the protocol, pollutes the flow, and breaks interop. We can define experimental features - that's fine because if they fail they just don't get adopted. But unchecked extensibility is how you end up with WS-*, and SOAP, and a never ending list of crap that offers no shred of interop because it was extended beyond recognition.
</rant>

EHL

---

From: Anthony Nadalin <[email-masked]>
Date: Fri, 1 Apr 2011 02:07:29 +0000

I have not seen your explanation of why an error registry does not satisfy the requirements as originally proposed in the bearer token. Your proposal recognizes the need to have a registry which is good but then you conflate parameters registry with an error registry, not all errors will be parameter driven. So your proposal will confuse those that will just want to register errors like they do with the other specifications today (they know how to do this), this seems very odd to have to do it your proposed way. Can you point me to other specifications that have done it your proposed way?
 
-----Original Message-----
From: Eran Hammer-Lahav [mailto:[email-masked]] 
Sent: Thursday, March 31, 2011 2:43 PM
To: Anthony Nadalin; Mike Jones; OAuth WG
Subject: RE: Error extensibility proposal

EHL

> unnecessary and unsolicited breaking change at a time that we should 
> be stabilizing the spec.
> 
> practices.  I know of no other specification where a parameters 
> registry is overloaded in this manner.  Please incorporate the OAuth 
> Errors registry into the framework specification in lieu of this proposal.
> 
> 				Thank you,
> 				-- Mike
> 
> 1. Provide a way to return an OAuth error response for error 
> situations other then 400 and 401. For example, if the server is 
> temporarily unavailable, it will return an HTTP 503 status. However, 
> it is often desirable to still return a response body using the same 
> format as any other error. This makes client development easier, having to always check for a single error code.
> 
> 2. Allow extensions modifying the behavior of the authorization and 
> token endpoints via additional request/response parameters to define 
> additional error codes to go along with the new functionality. For 
> example, the UX extension defines the 'display' parameter. It could 
> define a matching 'unsupported_display' error response.
> 
> No other use cases were identified for error extensibility. Note that 
> this proposal is strictly limited to error resulting from the 
> authorization and token endpoints. No other endpoints are included (in 
> particular, protected resources are not covered by this proposal).
> 
> *** Design goals
> 
> The proposal was specifically designed to be minimalistic, tailored to 
> the specific use cases defined, and as effortless as possible. This 
> avoids defining error codes identical to existing HTTP status codes, 
> as well as bind new errors to specific extension parameters. Since the 
> error is useless without understanding the extension, this method 
> guarantees that those developing and implementing extensions will present it as a complete unit.
> 
> *** Proposal
> 
> - Non 400/401 responses
> 
> If the HTTP response status code is 4xx (other than 400/401) or 5xx, 
> the 'error' parameter SHOULD be set to the HTTP status code. For example:
> 
> This will also enable passing HTTP status codes such as 503 via the 
> redirection response which is currently not possible. It will allow 
> the authorization server to indicate a 503 situation without defining 
> another error code that has the exact same meaning.
> 
> - Extension errors
> 
> Instead of defining an additional error registry, I propose we add a 
> single field to the 'OAuth parameters registry' template:
> 
>     Additional error codes:
>         Additional error codes related to the parameter usage. Error 
> codes SHOULD begin with the parameter name
> Error collisions are unlikely because when a new extension is 
> authored, the registry is reviewed for potential conflicts. Since the 
> errors are extension- specific, collisions only matter if two 
> extensions are to be used together. In that case, the review process 
> will identify any potential problems. And since the errors are 
> meaningless without understanding the extension, a registry with a random list of errors is not very helpful.
> 
> *** Feedback
>

---

From: Marius Scurtescu <[email-masked]>
Date: Thu, 31 Mar 2011 19:21:13 -0700

Maybe I don't understand how you want to deal with errors, sorry if
you have to repeat the same argument.

Here are a couple of examples.

JavaScript clients need to be able to get new access tokens without
user interaction (after an initial consent). The solution is to define
an immediate mode through an extension. The client sends a parameter
immediate=true which tells the server that no UI should be shown.
Either an access token is returned immediately or a specific error
code. This error code must tell the client that it does need to popup
a UI and try again. In this case the error code could be
immediate_failed, which conforms to your prefix requirement, but I
think only by luck.

Another example is the device profile. The profile defines a new grant
type, the device is repeatedly checking the token endpoint to see if
the user has approved or not. Two special error codes are required for
this to work: authorization_pending and slow_down. No meaningful
parameter prefix can be used in this case. See:
http://tools.ietf.org/html/draft-recordon-oauth-v2-device-00#section-1.6

Marius

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 31 Mar 2011 22:48:59 -0700

> Sent: Thursday, March 31, 2011 7:21 PM
> To: Eran Hammer-Lahav
> Cc: OAuth WG
> Maybe I don't understand how you want to deal with errors, sorry if you
> have to repeat the same argument.

This is helpful.

> JavaScript clients need to be able to get new access tokens without user
> interaction (after an initial consent). The solution is to define an immediate
> mode through an extension. The client sends a parameter immediate=true
> which tells the server that no UI should be shown.
> Either an access token is returned immediately or a specific error code. This
> error code must tell the client that it does need to popup a UI and try again.
> In this case the error code could be immediate_failed, which conforms to
> your prefix requirement, but I think only by luck.

The prefix is just a useful suggestion. No need to produce convoluted grammar just to fit the parameter name it. But it usually works out given that the error operates with relation to the parameter.

This examples seems to fit my proposal perfectly.

> Another example is the device profile. The profile defines a new grant type,
> the device is repeatedly checking the token endpoint to see if the user has
> approved or not. Two special error codes are required for this to work:
> authorization_pending and slow_down. No meaningful parameter prefix can
> be used in this case. See:

Ah, a new use case!

So here we have new errors coming out of the use of an extension grant type. As currently drafted, the device grant type (which will need to be assigned a URI) does not introduce any new request or response parameter to the token endpoint, so my proposal does not satisfy this use case.

This does provide a compelling use case for introducing an error registry, separate from the parameters registry. However, it is still directly linked to another extension point (grant type).

I'll combine Mike Jones' proposal with mine and repost.

Thanks for that!

EHL

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 31 Mar 2011 23:05:12 -0700

> Sent: Thursday, March 31, 2011 7:07 PM
> To: Eran Hammer-Lahav; Mike Jones; OAuth WG
> I have not seen your explanation of why an error registry does not satisfy the
> requirements as originally proposed in the bearer token. Your proposal
> recognizes the need to have a registry which is good but then you conflate
> parameters registry with an error registry, not all errors will be parameter
> driven. So your proposal will confuse those that will just want to register
> errors like they do with the other specifications today (they know how to do
> this), this seems very odd to have to do it your proposed way. Can you point
> me to other specifications that have done it your proposed way?

This is exactly what I want to prevent. There should not be a way to add new error codes without adding some other extension. New errors must be specific to new flows not currently specified in the v2 specification.

If someone fully implements v2 and nothing else, they should NEVER receive an unexpected error, just because someone decided to be creative. This is why we have this working group and put so much effort into building consensus. What is a v2 client supposed to do with an unknown error response? Display a 500 error to the user? In previous posts you expressed much concern for the client developer and this seems to be in line with that concern. It is unreasonable to expect client developers to constantly keep up to date with a growing error registry.

A practical example for this restriction is the huge difference in the level of consensus required to add error codes to v2 now (while in draft), compared to requests to register new codes later via the registry process. We used to have more error codes and through the working group process narrowed the selection. Based on the registry rules, the few people who still want those error codes can simply reintroduce them (all they need is a stable document to reference, no RFC required). The DE will not be able to block such a request if it is well formed. This is not something I want to enable.

My proposal ties new errors to new parameters because that was the only source of new errors we had use cases for. Marius just brought up the device grant type as another example, and that is a use case my proposal does not cover. It does, however, fits my criteria for valid new error codes.

I will combine Mike Jones' proposal with mine and resubmit for review.

EHL
 
> You have to show how the proposal does not satisfy you requirements. It
> fully satisfies all the requirements presented to the working group.
> 
> EHL
> 
> 
> > meaningless without understanding the extension, a registry with a
> random list of errors is not very helpful.
> >
> > *** Feedback
> >