Implementing an Authorization Endpoint with Authlete

Authlete implements the OAuth 2.0 and OpenID Connect specifications; all your authorization endpoint implementation needs to do is pass client requests to the Authlete API and take the actions indicated in the Authlete API response.

There are three entities involved in the authorization process:

Interactive Authorization Flow

The figure below shows the most typical data flow. An HTML page is displayed to an end-user and they decide to either authorize the client application to access their resources or deny the authorization request.

1. The client application sends an authorization request to the service’s authorization endpoint.
2. The authorization endpoint implementation passes the authorization request parameters to Authlete’s /auth/authorization API.
3. Authlete parses the request parameters, computes request information (such as client information, requested scopes, etc.) that the service will need in order to build the UI, and returns it to the service.
4. The service renders the UI to authenticate the end-user and let the end-user authorize the client application.
5. The end-user logs in to the service and decides whether to allow or deny the authorization request.
6. The service receives the decision from the end-user and calls either the /auth/authorization/issue or /auth/authorization/fail API accordingly.
7. Authlete generates a response and returns it to the service. The response may contain an authorization code, an access token and/or an ID token, or an error code, depending on the original authorization request from the client application.
8. The service returns the final response to the client application. In a typical case, the HTTP status of the response is 302 Found and a Location header containing the client’s redirect URI with query parameters.

Non-Interactive Authorization Flow

OpenID Connect introduced a prompt request parameter. When its value is none, the authorization request is processed without user interaction. The figure below illustrates the flow.

1. The client application sends an authorization request with prompt=none to the service’s authorization endpoint.
2. The authorization endpoint implementation passes the authorization request parameters to Authlete’s /auth/authorization API.
3. Authlete parses the request parameters, computes request information (such as client information, requested scopes, etc.) that the service will need in order to build the UI, and returns it to the service.
4. The service verifies that the authorization request satisfies necessary conditions.
5. The service calls either the /auth/authorization/issue or the /auth/authorization/fail API.
6. Authlete generates a response and returns it to the service. The response may contain an authorization code, an access token and/or an ID token, or an error code, depending on the original authorization request from the client application.
7. The service returns the final response to the client application. In a typical case, the HTTP status of the response is 302 Found and a Location header containing the client’s redirect URI with query parameters.

Handling Bad Requests

When an authorization request from a client application is invalid, Authlete’s /auth/authorization API generates a response containing an error report which the service can return to the client. In this case, the service does not have to call the /auth/authorization/issue or /auth/authorization/fail API. The figure below illustrates the flow.

1. The client application sends an authorization request with prompt=none to the authorization endpoint of the service.
2. The authorization endpoint implementation passes the authorization request parameters to Authlete’s /auth/authorization API.
3. Authlete parses the request parameters, detects the error, builds an error report and returns it to the service.
4. The service returns the final response containing the error report to the client application. In a typical case, the HTTP status of the response is 302 Found and Location header contains the client’s redirect URI with the error report. However, if the error was detected before the client’s redirect URI was determined, the service should return 400 Bad Request to the client application.