Generating error response using “fail” API

Overview

Authlete provides two “fail” APIs; /auth/authorization/fail and /auth/token/fail to support generating error response from authorization server to client.

These APIs generate OAuth 2.0 compliant error response so that your authorization server can easily answer to clients with error messages in line with the standard.

How “fail” API works

After user authentication and access authorization process, authorization server may decide not to issue any tokens to a client. In such case the server makes a request to Authlete’s “fail” API with reason as a “reason” parameter in the request. 

Authlete determines which error message is appropriate and how the message is transferred, and then the API responds authorization server with its result which contains “action” and “responseContent” respectively.

/auth/authorization/fail API

/auth/authorization/fail API is used in the following case:

• Authorization server receives authorization request from client
• The server invokes Authlete’s /auth/authorization API to check if the request is valid and gets successful response
• The server does some interaction with user to authenticate and get consent from him/her
• If conditions for granting access are not satisfied, the server is to provide error response instead of tokens

The following table describes overview of “action and “responseContent.” In most cases Authlete responds the server with “LOCAITON” as redirect_uri is determined.

action	responseContent
INTERNAL_SERVER_ERROR	Authlete’s internal error. It responds authorization server with JSON content which contains description of the error. Authorization server doesn’t have to respond its clients with the content as is
BAD_REQUEST	Authorization server is unable to report error to its clients as redirect_uri is not determined. How the server handles this situation depends on requirement of the server. For example the server may generate error content as HTML and send it back with HTTP status code 400.
LOCATION	Authlete generates redirection URI and responds authorization server with it. The server is expected to include it as a value of Location header in HTTP response with status code 302.
FORM	Authlete generates HTML which contains JavaScript to do POST some content to a callback location, and responds authorization server with it. The server is expected to include it as body of HTTP response with status code 200.

/auth/token/fail API

/auth/token/fail API is used for ROPC (Resource Owner Password Credentials) grant tyoe. Authorization server without ROPC capability doesn’t have to call this API.

Structure of this API is the same as /auth/authorization/fail API.

Developing your own error handling without “fail” API

You don’t have to use “fail” API if your authorization server can completely determine transport method and content of error. There are no side effects in terms of Authlete’s operation.

However you will owe to implement complicated functions in the server such as:

• Keeping redirect_uri value form authorization request
• Keeping response method like query parameters, fragments etc. and Developing some logic for special cases such as response_mode=fragment, which designates fragment as response format even if response_type=code is specified
• Generating HTML form for response_type=form_post
• Keeping state value

Using Authlete’s “fail” API is always recommended to avoid considering these matters.

Resources

• OAuth 2.0 and OpenID Connect Implementation in Laravel (Authlete)

  • 3.9.3. Delegate authorization request processing to Authlete

    • For example, if the client_id request parameter is not included in an authorization request, /api/auth/authorization API returns a response like “Return ‘400 Bad Request’ to the client application. Use ‘…’ as the error message of the response.” If an authorization request is valid, it returns a response like “The authorization request has no problem. Get the user’s consent to the authorization request interactively. Then, call either /api/auth/authorization/issue API or /api/auth/authorization/fail API according to the user’s decision.”

  • 3.11.3. Delegate token request processing to Authlete

    • The resource owner password credentials flow is only an exception. A call of /api/auth/token API does not complete the flow. The implementation of token endpoint has to call either /api/auth/token/issue API or /api/auth/token/fail API additionally.