Handling OAuth 2.0 errors
Authorization using OAuth 2.0 can fail in several ways:
- The user aborts the authorization process by closing the browser view or navigating to a different URL.
- The authorization request has been denied by the server, has failed, or is temporarily unavailable.
- Network failures or internal server errors in FotoWeb, or FotoWeb temporarily unavailable.
- The application is incorrectly registered or implemented.
Handling scenario (1) is trivial for web application clients since this means that the user has navigated away from the client, too. For native applications that open a browser window, this means that the application may have to detect that the window was closed. In the worst case, the only solution is to implement a timeout or to simply do nothing if no answer is received on the redirection endpoint. For native applications that embed a browser view, the user may not even have the possibility to close the view. However, the application should provide a means to cancel authorization, e.g., using a "cancel" button.
In scenario (3), error messages will be presented to the user directly in the browser view. The user may have the option to retry authorization. If the error persists, the user will eventually give up and cancel the authorization, which is identical to scenario (1).
In scenario (2), the FotoWeb will send an error response in one of the following ways:
- If authorization is denied in the authorization request, then FotoWeb redirects to the client's redirection endpoint with an authorization error response in the URL, which is explained below.
- If authorization is denied in the token request, then the token request returns an DONE: error status code (400-599) and a token error response in the response body, which is explained below.
Authorization Error Response
The authorization request redirects to the client's redirection endpoint URI as follows:
https://myapplication.com/oauth2/callback?
error=ERROR_TYPE&
error_description=ERROR_DESCRIPTION&
error_uri=ERROR_URI
where
|
Parameter |
Description |
|---|---|
error |
If this parameter is present, then an error has occurred. |
error_description |
OPTIONAL. This parameter MAY or may not be present, even if an error has occurred. Human-readable description of the error to assist the client developer in understanding the error. This description MAY be shown to the user, but is not necessarily useful or understandable for the user and may not be localized to the user's language. According to the OAuth 2.0 specification, the error description is encoded as ASCII. FotoWeb uses the entire Unicode set, encoded as UTF-8 and URL-encoded if necessary. |
error_uri |
OPTIONAL. This parameter MAY or may not be present, even if an error has occurred. URL of a page with a human-readable description of the error. The client MAY open this URL in a browser view to inform the user or client developer about the error, but the information shown is not necessarily useful or understandable for the user and may not be localized to the user's language. |
Token Error Response
The token request returns the following response (if specified, with a different status code):
400 BAD REQUEST
Content-Type: application/json
{
"error": "ERROR",
"error_description": "DESCRIPTION",
"error_uri": "URL"
}
where
|
Parameter |
Description |
|---|---|
error |
If this parameter is present, then an error has occurred. An identifier describing the cause of the error |
error_description |
OPTIONAL. This parameter MAY or may not be present, even if an error has occurred. Human-readable description of the error to assist the client developer in understanding the error. This description MAY be shown to the user, but is not necessarily useful or understandable for the user and may not be localized to the user's language. According to the OAuth 2.0 specification, the error description is encoded as ASCII. FotoWeb uses the entire Unicode set, encoded as a usual JSON string. |
error_uri |
OPTIONAL. This parameter MAY or may not be present, even if an error has occurred. URL of a page with a human-readable description of the error. The client MAY open this URL in a browser view to inform the user or client developer about the error, but the information shown is not necessarily useful or understandable for the user and may not be localized to the user's language. |
Reporting errors to the user
If OAuth 2.0 authorization fails, the user needs to be notified.
Most of the user experience of OAuth 2.0 is in the browser view, and at least the authentication (log-in) interface is provided by FotoWeb. As discussed above, the only responsibility of the client in this scenario is to allow the user to abort the authorization process.
In case FotoWeb returns an error response, the client should present an appropriate user-friendly and (if necessary) localized error message. It is sufficient to tell the user that authorization of the application has failed, and it is recommended to also inform the user who to contact in case of repeated failures (e.g., a support email of the client or the administrator of the FotoWeb server). The error_description attribute and the page linked to by the error_uri attribute are intended for diagnostic purposes for client developers and should not shown by the user. However, the client may present a "Details" button which displays this information, and there is no security risk in showing this information to regular users.