文档

API 授权

更新时间:

了解 API 授权的使用场景。根据您的业务需求,开启 API 授权、配置授权规则,定义授权方接口,并将授权规则应用到 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,提高授权的性能。

40

使用场景

场景一

客户有分布式 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 请求时的身份来源字段缺失,授权验证无法通过。

定义授权方接口

说明

如果后端系统提供的授权接口为 HTTP 类型,需要将授权 API 配置为 POST 方法。

在添加授权关系前,业务系统需要提前开发一个 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 在请求后端系统前,会进行授权验证。通过则接受请求,网关将请求路由到后端系统。否则,请求会被拒绝,调用方将收到授权失败的错误响应。

  • 本页导读 (0)
文档反馈