功能介紹

API 授權功能允許業務在 MGS 上定義通用的 API 訪問授權規則：

1. 創建授權 API A 并在網關管理中配置，然后到業務 API B 配置中做關聯。

2. 客戶端發起對后端業務 API B 的請求時，MGS 會根據 API 授權配置從該請求 Header 或 Cookie 中取出授權參數放到 Context 里然后調用業務 API B 關聯的授權 API A，授權 API A Server 需要根據 Context 中的參數做業務權限校驗。

3. 如校驗合法，MGS 會將校驗結果 Principal 添加在請求 Header 中，傳遞給后端業務 API B。如需緩存，MGS 會緩存校驗結果 Principal，提高授權的性能。

使用場景

場景一

客戶有分布式 session，登錄后會產生會話 ID。授權過程如下：

1. 用戶 A 請求登錄接口，登錄成功后，產生會話 ID 和會話信息保存到分布式緩存中，sessionId: {username:A, age:18, ...} ，并且下發 sessionId 到客戶端。

2. 用戶 A 請求一個需要登錄授權的接口，網關從請求 Header 中獲取 sessionId，發送給授權系統，授權系統根據 sesssionId 從分布式緩存中獲取到用戶信息，并且將 {username:A, age:18,...} 返回給網關。

3. 網關判斷登錄成功，將 {username:A, age:18,...} 添加在 Header 中，轉發請求到后端的業務 Server。

場景二

客戶端基于 HMAC 的授權方案，授權過程如下：

1. 用戶 A 登錄成功后，下發一個 token 到客戶端，token=hmac(username+password) 。

2. 用戶 A 請求一個需要登錄授權的接口，網關從 Header 中獲取 token，發送給授權系統，授權系統根據再算一遍 HMAC，如果符合則返回用戶信息 {username:A, age:18,...} 給網關。

3. 網關判斷登錄成功，將 {username:A, age:18,...} 添加在請求 Header 中，轉發請求到后端的業務 Server。

操作步驟

配置授權規則

1. 登錄 mPaaS 控制臺。在左側導航欄，點擊 后臺服務管理 > 移動網關 菜單。

2. 點擊 網關管理 標簽，在 API 授權 下方，點擊 創建授權方 或點擊已存在的授權規則記錄列表中操作列中的 詳情，進入授權規則配置頁面：

   • 授權方名稱：必填，授權規則的名稱。

   • 授權方接口：必填，用于驗證請求授權情況的接口。

   • 授權緩存：是否緩存授權的驗證結果。

   • 緩存TTL：驗證結果的緩存存活時間。

   • 身份來源：如果點擊 添加來源字段，填寫用于授權的請求參數，表明請求身份的信息，由以下字段組成：

     • 位置：參數所處位置，header 或者 cookie。

     • 字段：參數名稱。

   說明

   如果實際 API 請求時的身份來源字段缺失，授權驗證無法通過。

定義授權方接口

在添加授權關系前，業務系統需要提前開發一個 Auth API。當 API 需要驗證授權關系時，會調用 Auth API 進行授權校驗。Auth API 的定義（請求和響應）遵循以下的標準：

AuthRequest

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

AuthResponse

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

接口示例

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

• 當驗證授權的響應中 success 字段值為 true 時，網關會根據緩存策略緩存 principal 信息，然后將 principal 信息放入這次請求的 header 中，透傳到后端業務系統中。沒有principal也需要傳個空Map。

• 當驗證授權的響應中 success 字段值為 false 時，網關會返回 2000 錯誤碼，客戶端需要根據 2000 做相應的操作，例如彈出登錄框。

使用授權規則

當授權規則配置后，可以在 API 配置頁面中的 高級配置 > API 授權 中選擇對應的規則，為該 API 啟用授權功能。

要使用 API 授權，確保已在 網關管理 頁面中開啟 API 授權 功能。開啟步驟如下：

1. 登錄 mPaaS 控制臺。在左側導航欄，點擊 移動網關 菜單。

2. 點擊 網關管理 標簽，確保 API 授權 按鈕開啟。

該 API 在請求后端系統前，會進行授權驗證。通過則接受請求，網關將請求路由到后端系統。否則，請求會被拒絕，調用方將收到授權失敗的錯誤響應。