API authorization

API authorization lets Mobile Gateway Service (MGS) validate every incoming API request before forwarding it to your backend. This topic explains how it works, when to use it, and how to configure authorization rules, implement the authorizer interface, and apply rules to your APIs.

How it works

API authorization delegates identity verification to a dedicated authorizer API that you build and register in MGS. The flow for every authorized request is:

1. Create an authorizer API (API A) in gateway management and associate it with a business API (API B) in API B's configuration.

2. When a client calls API B, MGS extracts the authorization parameters from the request header or cookie based on the authorization configuration, places them into the request context, and calls API A. Your API A implementation performs the permission check using those context parameters.

3. If the check succeeds, MGS adds the result — called the principal — to the request header and forwards the request to the backend API B. When caching is enabled, MGS caches the principal for subsequent requests to reduce latency.

Use cases

Session-based authorization

Use this pattern when your backend maintains a distributed session store. After a user logs in, a session ID is issued to the client and the session data is stored server-side.

1. User A logs in successfully. A session ID is generated, and the session data — for example, sessionId: {username:A, age:18, ...} — is stored in a distributed cache. The session ID is returned to the client.

2. User A calls an API that requires authorization. MGS retrieves the session ID from the request header and passes it to the authorizer API. The authorizer looks up the session data in the distributed cache and returns the user information — for example, {username:A, age:18,...} — to the gateway.

3. MGS confirms authorization, attaches {username:A, age:18,...} to the request header as the principal, and forwards the request to the backend business server.

HMAC token-based authorization

Use this pattern for client-side authorization using a Hash-based Message Authentication Code (HMAC). The token is computed from credentials and verified server-side on every request.

1. User A logs in successfully. A token is computed and sent to the client — for example, token=hmac(username+password).

2. User A calls an API that requires authorization. MGS retrieves the token from the request header and passes it to the authorizer API. The authorizer recomputes the HMAC and, if the tokens match, returns the user information — for example, {username:A, age:18,...} — to the gateway.

3. MGS confirms authorization, attaches {username:A, age:18,...} to the request header as the principal, and forwards the request to the backend business server.

Configure authorization rules

Create an authorization rule

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

2. Select the Gateway Management tab. Under API Authorization, click Create authorization API. To modify an existing rule, find it in the list and click Details in the Actions column.

   Configure the following fields on the authorization rule configuration page:

   • Authorization API name: Required. A display name for this authorization rule.

   • Authorization API: Required. The authorizer API that verifies incoming requests.

   • Cache authorization result: Whether to cache the authorization result for repeated requests from the same identity source.

   • Cache TTL: How long the cached authorization result is valid. MGS uses the identity source field values as the cache key, so requests with the same identity source values within the TTL reuse the cached result without calling the authorizer API again.

   • Identity source: Click Add source field to specify which request parameters MGS extracts and passes to the authorizer. Each source field has two properties:

     • Location: Where to find the parameter — header or cookie.

     • Field: The parameter name.

   Note

   If the identity source field is missing from the API request, the authorization validation fails.

Implement the authorizer interface

Before associating an authorization rule with a business API, implement an Auth API in your backend system. When MGS calls this Auth API to check authorization, the Auth API request and response must conform to the following contract:

AuthRequest

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

AuthResponse

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

Interface example

The following example reads a session ID (sid) from the context and returns a derived principal. Replace the logic with your own identity verification.

@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;
}

• When success is true, MGS caches the principal according to the cache policy, then adds the principal to the request header and forwards the request to the backend business system. If there is no principal to return, pass an empty Map.

• When success is false, MGS returns error code 2000 to the client. Handle this in the client by prompting the user to log in again.

Apply authorization rules to an API

After creating an authorization rule, open the target API's configuration page. Under Advanced Settings > API Authorization, select the rule to enable authorization for that API.

API authorization also requires the API Authorization feature to be enabled at the gateway level. To enable it:

1. Log in to the mPaaS console. In the left navigation pane, click the Mobile Gateway Service menu.

2. Log in to the mPaaS console. In the left navigation pane, click Background connection > Mobile Gateway Service.

3. On the Manage gateway tab, ensure that the API Authorization button is turned on.

Once enabled, MGS checks authorization before every API request reaches your backend. Requests that pass the check are forwarded to the backend system. Requests that fail receive an authorization failed error response.