Re: [OAUTH-WG] Error registry proposal (round 3)

[Mike Jones <[e-mail]>]

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: [e-mail] [mailto:[e-mail]] 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

   [e-mail]<mailto:[e-mail]> 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 [e-mail]<mailto:[e-mail]> 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.