All Products
Search
Document Center

API authorization

Last Updated: Apr 02, 2021

Learn about the usage scenarios of API authorization. You can enable API authorization, configure authorization rule, define the authorization API, and apply the authorization rule to API based on your business requirement.

Function

API authorization allows you to define common authorization rules for accessing API:

  1. Create authorization API A, make corresponding configuration on the gateway managment page, and then assoicate API A with API B by setting API B.
  2. When the client initiates a request to API B, MGS otains the authorizatoin parameters from the request Header or Cookie according to the authorizaiton configuraion, puts the authorizatoin parameters in Context, and then calls API A which is associated with API B. The server of authorization API A needs to perform business permission verification according to the parameters in Context.
  3. If the verification result is legal, MGS will add the verification result Principal in the request Header, and then forwards the request to backend API B. If cache is required, MGS caches the verification result Principal to improve the performance of authorization.

API authorization

Usage scenarios

Scenario 1

A customer has distributed sessions, and session IDs are generated upon user login. The authorization process is as follows:

  1. User A initiates a request to the login interface. After user A successfully logs in, the gateway generates and saves session ID and session information sessionId: {username:A, age:18, ...} in the distributed cache , and delivers the sessionId to the client.
  2. User A initiates a request to the login interface which needs authorization. The gateway obtains the sessionId from the request header and sends the sessionId to the authorizing system. Then, the authorizing system obtains the user information from the distributed cache according to the sessionId, and returns {username:A, age:18,...} to the gateway.
  3. After confirming the successful login, the gateway adds {username:A, age:18,...} in the request header, and forwards the request to the backend business server.

Scenario 2

The client implements authorization based on HMAC. The authorization process is as follows:

  1. User A delivers a token token=hmac(username+password) to the client after successful login.
  2. User A initiates a request to the login interface which needs authorization. The gateway obtains the token from the request header and sends the token to the authorizing system. Then, the authorizing system calculates the HMAC again. If the HMAC matches, the authorizing systems returns the user information {username:A, age:18,...} to the gateway.
  3. After confirming the successful login, the gateway adds {username:A, age:18,...} in the request header, and forwards the request to the backend business server.

Procedure

1. Configure authorization rule

  1. Log in to the mPaaS console, and from the navigation bar on the left, click Mobile Gateway Service.
  2. Click Manage gateway tab. Under API authorization, click Create authorization API or Detail on the operation column in the list of existing authorization rules to go to the authorization rule configuration page:
    • Authorization API name: Required, name of the authorization rule
    • Authorization API: Required, the interface used to verify request authorization
    • Cache authorization: Whether to cache the verification result of the authorization
    • Cache TTL: Time-to-live of the verification result cache
    • Identity source: If you click Add source field, you can enter the request parameter used for authorization. The identity source comprises two fields:
      • Location: The location where the parameter is, header or cookie.
      • Field: Parament name.
        Note: If the identity source field misses in actual API request, you cannot go through the authorization verification.

2. Define the authorization API

If the authorization interface provided by the back-end system is of HTTP type, the authorization API needs to be configured as the POST method.

Before the business system adds an authorization relationship, an Auth API is required. When an API needs to verify the authorization relationship, the business system calls Auth API to verify the authorization. The definition of Auth API must comply with the following standards:

AuthRequest

 
  1. public class AuthRequest {
  2. private Map<String,String> context;
  3. }

AuthResponse

 
  1. public class AuthResponse {
  2. private boolean success;
  3. private Map<String,String> principal;
  4. }

Instructions:

  • When the value of success field in the authorization verification response is true, the gateway caches the principal information according to the cache policy, adds the principal information in the request header, and passes it to the backend business system.

  • When the value of success field in the authorization verification response is false, the gateway returns 2000 error code. The client needs to do corresponding operation accordingly, such as to pop up a login box.

3. Use the authorization rule

When the authorization rule is completely configured, you can select the corresponding rule from Advanced settings > API authorization on the API configuration page, and enable the authorization function for the current API.

To use the API authorization, you must enable the API authorization function on the gateway management page:

  1. Log in to the mPaaS console, and from the navigation bar on the left, click Mobile Gateway Service.
  2. Click the Manage gateway tab, and switch API authorization on.

The API will go through authorization verification before sending a request to the backend system. If it passes the verification, the gateway routes the request to the backend system. Otherwise, the request will be rejected, and the caller will receive the error response about authorization failure.