API 授权

功能介绍

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 在请求后端系统前，会进行授权验证。通过则接受请求，网关将请求路由到后端系统。否则，请求会被拒绝，调用方将收到授权失败的错误响应。