Extension: Problem Reporting

This is an extension to OAuth, defining how a Service Provider can report a problem to a Consumer. This enables the Consumer to provide a more satisfying experience to the User, by solving the problem quietly or giving the User actionable advice for solving the problem.

To discuss this extension, please use the API failure handling thread in the Google Group OAuth Extensions.

A Service Provider MAY report a problem by including the following parameters in any HTTP response. These parameters SHOULD be included in an OAuth WWW-Authenticate header (per OAuth section 5.4.2), and MAY also be included in the response body (per OAuth section 5.3). These parameters MAY be sent in both the header and body of the same response, in which case these parameters SHOULD be identical in these two places.  Note that parameter values are percent encoded, as specified by OAuth.

The parameter named oauth_problem is a brief string identifying a problem. Its permitted values and their meanings are: 

• version_rejected: the oauth_version isn't supported by the Service Provider. In this case, the response SHOULD also contain an oauth_acceptable_versions parameter (described below).
• parameter_absent: a required parameter wasn't received. In this case, the response SHOULD also contain an oauth_parameters_absent parameter (described below).
• parameter_rejected: an unexpected parameter was received. In this case, the response SHOULD also contain an oauth_parameters_rejected parameter (described below).
• timestamp_refused: the oauth_timestamp value is unacceptable to the Service Provider. In this case, the response SHOULD also contain an oauth_acceptable_timestamps parameter (described below).
• nonce_used: the oauth_nonce value was used in a previous request, and consequently can't be used now.
• signature_method_rejected: the oauth_signature_method is unacceptable to the Service Provider.
• signature_invalid: the oauth_signature is invalid. That is, it doesn't match the signature computed by the Service Provider.
• consumer_key_unknown: the oauth_consumer_key is unknown to the Service Provider.
• consumer_key_rejected: the oauth_consumer_key is permanently unacceptable to the Service Provider. For example, the Consumer may be black listed.
• consumer_key_refused: the oauth_consumer_key is temporarily unacceptable to the Service Provider. For example, the Service Provider may be throttling the Consumer.
• token_used: the oauth_token has been consumed. That is, it can't be used any more because it has already been used in a previous request or requests.
• token_expired: the oauth_token has expired. That is, it was issued too long ago to be used now. If the ScalableOAuth extensions are supported by the Consumer, it can pass on the oauth_session_handle it received in the previous Access Token request to obtain a renewed Access token and secret.
• token_revoked: the oauth_token has been revoked. That is, the Service Provider has unilaterally decided it will never accept this token.
• token_rejected: the oauth_token is unacceptable to the Service Provider. The reason is unspecified. It might mean that the token was never issued, or consumed or expired and then subsequently forgotten by the Service Provider.
• verifier_invalid: the oauth_verifier is incorrect.
• additional_authorization_required: user needs to give additional permissions before the Consumer is allowed access to the resource. If the ScalableOAuth extensions are supported by the Consumer, it can use the oauth_token (access token) it already has as the request token to initiate the authorization process again, in which case it must use the oauth_token_secret (access token secret) to sign the request for a new access token once the user finishes giving authorization.
• permission_unknown: The User hasn't decided whether to permit this Consumer to access Protected Resources. Usually happens when the Consumer requests Access Token before the user completes authorization process.
• permission_denied: The User refused to permit this Consumer to access Protected Resources.
• user_refused: The User (in most cases it's just user's IP) is temporarily unacceptable to the Service Provider. For example, the Service Provider may be rate limiting the IP based on number of requests. This error condition applies to the Authorization process where the user interacts with Service Provider directly. The Service Provider might return this error in the authorization response or in the Access Token request response.

Other values of oauth_problem MUST NOT be used. However, a Consumer SHOULD be prepared to receive other values, from a Service Provider that implements a future version of problem reporting.

The parameter named oauth_acceptable_versions consists of two version numbers separated by '-' (hyphen). It's the range of versions acceptable to the sender. That is, it means the sender will currently accept an oauth_version that's not less than the first number and not greater than the second number. A version A.B is considered greater than C.D if either A > C, or A = C and B > D.

The parameter named oauth_acceptable_timestamps consists of two numbers in decimal notation, separated by '-' (hyphen). It's the range of timestamps acceptable to the sender. That is, it means the sender will currently accept an oauth_timestamp that's not less than the first number and not greater than the second number.

The parameter named oauth_parameters_absent consists of a set of parameter names, percent-encoded and then separated by '&'. Note that this string will be percent-encoded again, because it's the value of oauth_parameters_absent. For example, a response body may contain: oauth_problem=parameter_absent&oauth_parameters_absent=oauth_token%26oauth_nonce

The parameter named oauth_parameters_rejected consists of a set of parameters, encoded as they would be in a URL query string. These are parameters that the sender recently received but didn't expect. Note that these parameters will be percent-encoded twice: once to form a query string and again because the query string is the value of oauth_parameters_rejected.

The parameter named oauth_problem_advice consists of free-form text to be shown to the User. It SHOULD describe the problem in a way that's meaningful to the User, and suggest how to resolve the problem. The Consumer MUST NOT interpret it as HTML or any other markup language; all the characters MUST be displayed to the user. To indicate a line break, the single character LF (Unicode U+000A) MUST be used. 

New Parameter to request Error (status) code in Response Body:

• oauth_error_in_response_body : Consumers can request the return status code in case of errors in the HTTP response body in cases when they cannot read the HTTP Status codes (Ex. Javascript clients running in a browser).

If the Service Provider also supports the custom response data format extension, the return status code and text should be added as an oauth parameter "oauth_error_code" and "oauth_error_text" inside the "response" object along with "oauth_problem" and other related parameters to this extension.

Sample XML:

     <response>
        <oauth_parameter name="oauth_error_code">401</oauth_parameter>
        <oauth_parameter name="oauth_error_text">Unauthorized</oauth_parameter>
        <oauth_parameter name="oauth_problem">token_expired</oauth_parameter>        
     </response>