Definitive Guide

Authorization Data Flow

  1. Data Flow (Interactive)
  2. Data Flow (Non-Interactive)
  3. Data Flow (Bad Request)

This document illustrates data flows that your implementation of authorization endpoint needs to handle. Entities involved in the flows are as follows.

Client A client application that makes an authorization request.
Service Your implementation of authorization endpoint.
Authlete Web APIs that you use to implement your authorization endpoint.

1. Data Flow (Interactive)

The figure below illustrates the most typical data flow. An HTML page is displayed to an end-user and he/she decides to grant authorization to the client application or deny the authorization request.

Authorization Data Flow (Interactive)
  1. The client application makes an authorization request to the authorization endpoint of the service.
  2. The implementation of the authorization endpoint extracts all the request parameters from the authorization request and passes them to Authlete's /api/auth/authorization API.
  3. Authlete parses the request parameters, builds request information (such as client information, requested scopes, etc.) that the service needs to build the UI, and returns it to the service.
  4. The service builds the UI to authenticate the end-user and let the end-user grant authorization to the client application and sends it to the client application.
  5. The end-user logins the service and decides either to grant authorization to the client application or to deny the authorization request.
  6. The service receives the decision from the end-user and calls either /api/auth/authorization/issue API or /api/auth/authorization/fail API accordingly.
  7. Authlete generates a response content and returns it to the service. The response content 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 Location header contains the client's redirect URI with response parameters.

2. Data Flow (Non-Interactive)

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

Authorization Data Flow (Non-Interactive)
  1. The client application makes an authorization request with prompt=none to the authorization endpoint of the service.
  2. The implementation of the authorization endpoint extracts all the request parameters from the authorization request and passes them to Authlete's /api/auth/authorization API.
  3. Authlete parses the request parameters, builds request information (such as client information, requested scopes, etc.) that the service needs to build the UI, and returns it to the service.
  4. The service checks whether the authorization request satisfies necessary conditions.
  5. The service calls either /api/auth/authorization/issue API or /api/auth/authorization/fail API.
  6. Authlete generates a response content and returns it to the service. The response content 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 Location header contains the client's redirect URI with response parameters.

3. Data Flow (Bad Request)

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

Authorization Data Flow (Bad Request)
  1. The client application makes an authorization request with prompt=none to the authorization endpoint of the service.
  2. The implementation of the authorization endpoint extracts all the request parameters from the authorization request and passes them to Authlete's /api/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.