*** 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
_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth
