Mobile Platform as a Service:API authorization

Features

The API authorization feature allows businesses to define common API access authorization rules on MGS:

1. Create an authorization API A and configure it in the gateway management, and then associate it with the service API B configuration.

2. When the client initiates a request to the backend service API B, MGS extracts the authorization parameters from the request header or cookie according to the API authorization configuration and puts them in the context and then calls the authorization API A associated with the service API B. The authorization API A server needs to perform service permission verification based on the parameters in the context.

3. If the verification is valid, MGS adds the verification result principal to the request header and passes it to the backend service API B. If caching is required, MGS caches the verification result principal to improve the performance of authorization.

Usage scenarios

Scenario 1

If a customer has a distributed session, a session ID is generated after login. The authorization process is as follows:

1. User A requests to log in to the interface. After successful login, user A generates a session ID and session information, saves them to the distributed cache, sessionId: {username:A, age:18, ...} them, and delivers the sessionId to the client.

2. User A requests an interface that requires logon authorization. The gateway obtains the sessionId from the request header and sends it to the authorization system. The authorization system obtains the user information from the distributed cache based on the sessionId and returns the {username:A, age:18,...} to the gateway.

3. The gateway determines that the logon is successful, adds the {username:A, age:18,...} to the header, and forwards the request to the backend service server.

Scenario 2

The client uses an HMAC-based authorization scheme. The authorization process is as follows:

1. After user A logs in successfully, a token is issued to the client and token=hmac(username+password).

2. User A requests an interface that requires login authorization. The gateway obtains token from Header and sends it to the authorization system. The authorization system calculates HMAC again according to HMAC. If it matches, it returns the user information to {username:A, age:18,...} to the gateway.

3. The gateway determines that the logon is successful, adds the {username:A, age:18,...} to the request header, and forwards the request to the backend service server.

Procedure

Configure authorization rules

1. Log on to the mPaaS console. In the left-side navigation pane, choose Background connection > Mobile Gateway Service.

2. Click the Manage gateway tab. In the API authorization section, click Create authorization API or click Details in the Actions column of an existing authorization rule.

   • Authorization API name: Required. The name of the authorization rule.

   • Authorization API: Required. The API is used to verify the authorization of the request.

   • Cache authorization result: Indicates whether to cache the verification result of authorization.

   • Cache TTL: the cache lifetime of the verification result.

   • Identity source: If you click Add source field, enter the request parameters that is used for authorization and the request identity, which consists of the following fields:

     • Location: the location, header or cookie, of the parameter.

     • Field: the name of the parameter.

   Note

   If the identity source field in the API request is missing, the authorization verification fails.

Define the authorizer interface

Before adding an authorization relationship, the business system needs to develop a Auth API in advance. When the API needs to verify the authorization relationship, the Auth API is called for authorization verification. The definition of Auth API (request and response) follows the following criteria:

AuthRequest

public class AuthRequest {
  private Map<String,String> context;
}

AuthResponse

public class AuthResponse {
  private boolean success;
  private Map<String,String> principal;
}

Interface example

@PostMapping("/testAuth")
public AuthResponse testAuth(@RequestBody AuthRequest authRequest) {
    String sid = authRequest.getContext().get("sid");
    Map<String, String> principal = new HashMap<>();
    principal.put("uid", sid + "_uid");
    AuthResponse authResponse = new AuthResponse();
    authResponse.setSuccess(true);
    authResponse.setPrincipal(principal);
    return authResponse;
}

• If the value of the success field in the response is true, the gateway caches the principal information based on the cache policy, and then puts the principal information into the header of the request and transparently transmits it to the backend business system. If you do not have a principal, you must pass an empty Map.

• If the value of the success field in the response for verifying authorization is false, the gateway returns a 2000 error code. The client needs to perform corresponding operations as 2000, for example, a logon box appears.

Use authorization rules

After an authorization rule is configured, you can choose Advanced Settings > API Authorization on the API Configuration page to enable the authorization feature for the API.

To use API authorization, make sure that the API authorization feature is enabled on the Manage gateway page. Perform the following steps to enable the feature:

1. Log on to the mPaaS console. In the left-side navigation pane, click Mobile Gateway Service.

2. Click the Manage gateway tab and make sure that API Authorization is enabled.

This API performs authorization verification before requesting the backend system. If you pass, the request is accepted and the gateway routes the request to the backend system. Otherwise, the request will be rejected and the caller will receive an error response of authorization failure.