如何做 HTTP 接口的访问控制

发布日期:2020年03月05日本文同步发表于公众号:

Cover

之前分享的 HTTP API 接口设计方案(https://www.jitao.tech/blog/2020/01/java-http-api)和示例代码(https://github.com/flmn/http-api-demo),收到了十分积极的反馈,所以深受鼓舞,这次加入访问控制的功能。

概述

这个方案有点类似于 Servlet 容器的 Session,但是比较简化,全流程都由自己控制,也比较好扩展和定制。

客户端通过登录接口首先获取一个 accessToken,后续的请求将这个 accessToken 放入 HTTP Header 中;服务端使用 Spring 框架的 HandlerInterceptor 进行统一处理,将用户信息放入请求上下文,供 Controller 使用。

流程

  1. 客户端使用用户名和密码(此处可以是手机号/验证码,小程序的登录 code 等)调用服务端/app/account/login 接口;
  2. 服务端使用客户端提交的凭证,检查用户合法性,如果通过,使用随机数产生一个 accessToken,并使用这个 accessToken 作为 Redis key 的一部分,将用户信息保存在 Redis 的 Hash 数据结构里,并设置过期时间,并将 accessToken 返回给客户端
  3. 后续请求,客户端将这个 accessToken 放到 HTTP Header 中,名称为:X-Access-Token
  4. 服务端使用 HandlerInterceptor 拦截每一个请求,根据从 HTTP Header X-Access-Token 中取得的 accessToken,如果没有 accessToken 为空,向客户端返回 401 错误。如果获得了 accessToken,服务端使用 accessToken 构造 Key 到 Redis 中查询用户信息,如果查不到,可能是登录已过期或者已注销,向客户端返回 401 错误。如果查到信息,将用户信息存入 Request 对象的 Attribute;
  5. 服务端 Controller 可以通过 @RequestAttribute 标记的参数,获取第 4 步 HandlerInterceptor 保存在 Request 对象的 Attribute 中的用户信息;
  6. 客户端调用 /app/account/logout 接口注销,服务端从 Redis 中删除 accessToken Key。

上述是整个过程的描述,在实际开发时,有一些需要注意的细节,请看下面的代码讲解。

代码

登录接口

代码:src/main/java/tech/jitao/httpapidemo/api/app/account/Login.java

...
@RestController(Login.PATH)
@CrossOrigin
@NoAuth
public class Login {
    static final String PATH = "/app/account/login";

    @Autowired
    private AccountService accountService;
...

这里的重点是 @NoAuth 标记,因为调用登录接口时,用户处在未登录状态,所以,通过这个标记,告诉 HandlerInterceptor 跳过这个接口的验证。@NoAuth 标记也可以用在其他无需访问控制的接口上,比如微信支付/支付宝的回调请求。

@NoAuth 标记的代码:src/main/java/tech/jitao/httpapidemo/config/auth/NoAuth.java

另外,来自 Spring 框架的 @CrossOrigin 标记,使这个接口可以跨域调用。关于跨域请求,可以参考阮一峰老师的这篇文章:跨域资源共享 CORS 详解

登录处理

代码:src/main/java/tech/jitao/httpapidemo/service/AccountService.java

... 检查用户

String token = RandomStringUtils.randomAlphanumeric(8) + UuidHelper.gen() + RandomStringUtils.randomAlphanumeric(8);
String keyToken = String.format(RedisKeys.SESSION, token);
HashOperations<String, String, String> hashOperations = redis.opsForHash();
hashOperations.put(keyToken, "userId", String.valueOf(user.getId()));
redis.expire(keyToken, LOGIN_TTL, TimeUnit.DAYS);
logger.info("User {}({}) login with token {}", user.getUsername(), user.getId(), token);

... 向客户端返回数据

这里比较简单,生成一个随机串作为 accessToken,将 userId 保存到 Redis。

拦截器

代码太多,可以直接看 src/main/java/tech/jitao/httpapidemo/config/auth/AuthInterceptor.java

要点如下:

  • PREFIXES,可以设置只对哪些路径开头的请求进行拦截。
  • 如果是跨域请求,即使是返回 401,也要返回 Access-Control-Allow-Origin 头,否则浏览器报的错误是 404。

拦截器的注册

代码:src/main/java/tech/jitao/httpapidemo/config/TheWebMvcConfigurer.java

...
@Configuration
public class TheWebMvcConfigurer implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authInterceptor());
    }

    @Bean
    public AuthInterceptor authInterceptor() {
        return new AuthInterceptor();
    }
    ...
}
...

TheWebMvcConfigurer 要实现 WebMvcConfigurer,然后 Override addInterceptors 方法注册 AuthInterceptor

Controller 获取用户信息

代码:src/main/java/tech/jitao/httpapidemo/api/web/document/CreateDocument.java

...
@PostMapping(PATH)
public ApiResult process(@Validated @RequestBody Request request,
                         @RequestAttribute(RequestAttributes.USER_ID) long userId) {
    ...
}
...

标记 @RequestAttribute 的参数能够自动获取 AuthInterceptor 中使用 request.setAttribute(RequestAttributes.USER_ID, userId); 设置的信息。

注销处理

代码:src/main/java/tech/jitao/httpapidemo/api/app/account/Logout.java

@RestController(Logout.PATH)
@CrossOrigin
@NoAuth
public class Logout {
    static final String PATH = "/app/account/logout";

    @Autowired
    private AccountService accountService;

    @PostMapping(PATH)
    public ApiResult process(@RequestHeader(value = RequestHeaders.ACCESS_TOKEN, required = false) String accessToken) {
        accountService.logout(accessToken);

        return ApiResult.ok();
    }
}

代码:src/main/java/tech/jitao/httpapidemo/service/AccountService.java

public void logout(String accessToken) {
    if (!Strings.isNullOrEmpty(accessToken)) {
        String keyToken = String.format(RedisKeys.SESSION, accessToken);
        redis.delete(keyToken);

        logger.info("User with access token {} logout.", accessToken);
    }
}

这里做了些容错处理,首先 logout 接口也标记为 @NoAuth,accessToken 直接从 HTTP Header 中取,如果 accessToken 不合法,则略过。原则就是不给前端返回错误,前端会有界面跳转和清存储的动作,也不会注销失败。

本文的示例代码可在 https://github.com/flmn/http-api-demo 获得。

玩得愉快。