全部产品

API 授权

更新时间:2020-06-04 14:50:09

了解 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,提高授权的性能。

API authorization

使用场景

场景一

客户有分布式 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. 配置授权规则

  1. 登录 mPaaS 控制台。在左侧导航栏,点击 移动网关
  2. 点击 网关管理 标签,在 API 授权 下方,点击 创建授权方 或点击已存在的授权规则记录列表中操作列中的 详情,进入授权规则配置页面:

    • 授权方名称:必填,授权规则的名称。
    • 授权方接口:必填,用于验证请求授权情况的接口。
    • 授权缓存:是否缓存授权的验证结果。
    • 缓存TTL:验证结果的缓存存活时间。
    • 身份来源:如果点击 添加来源字段,填写用于授权的请求参数,表明请求身份的信息,由以下字段组成:

      • 位置:参数所处位置,header 或者 cookie
      • 字段:参数名称。

        注意:如果实际 API 请求时的身份来源字段缺失,授权验证无法通过。

      image.png | left | 619x530

2. 定义授权方接口

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

在添加授权关系前,业务系统需要提前开发一个 Auth API。当 API 需要验证授权关系时,会调用 Auth API 进行授权校验。Auth API 的定义(请求和响应)遵循以下的标准:

AuthRequest

  1. public class AuthRequest {
  2. private Map<String,String> context;
  3. }

AuthResponse

  1. public class AuthResponse {
  2. private boolean success;
  3. private Map<String,String> principal;
  4. }

接口示例

  1. @PostMapping("/testAuth")
  2. public AuthResponse testAuth(@RequestBody AuthRequest authRequest) {
  3. String sid = authRequest.getContext().get("sid");
  4. Map<String, String> principal = new HashMap<>();
  5. principal.put("uid", sid + "_uid");
  6. AuthResponse authResponse = new AuthResponse();
  7. authResponse.setSuccess(true);
  8. authResponse.setPrincipal(principal);
  9. return authResponse;
  10. }

说明:

  • 当验证授权的响应中 success 字段值为 true 时,网关会根据缓存策略缓存 principal 信息,然后将 principal 信息放入这次请求的 header 中,透传到后端业务系统中。没有principal也需要传个空Map。

  • 当验证授权的响应中 success 字段值为 false 时,网关会返回 2000 错误码,客户端需要根据 2000 做相应的操作,例如弹出登录框。

3. 使用授权规则

当授权规则配置后,可以在 API 配置页面中的 高级配置 > API 授权 中选择对应的规则,为该 API 启用授权功能。

注意:要使用 API 授权,确保在 网关管理 页面,API 授权 功能开启:

  1. 登录 mPaaS 控制台。在左侧导航栏,点击 移动网关
  2. 点击 网关管理 标签,确保 API 授权 按钮开启。

该 API 在请求后端系统前,会进行授权验证。通过则接受请求,网关将请求路由到后端系统。否则,请求会被拒绝,调用方将收到授权失败的错误响应。