Skip to main content

​
Generating error response using “fail” API

fail-api_1 /auth/authorization/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.

​
/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.