Shiro + JWT + Spring Boot Restful 简易教程

GitHub 项目地址：github.com/Smith-Cruis… 。

原文地址：www.inlighting.org/archives/sp…。

序言

我也是半路出家的人，如果大家有什么好的意见或批评，请务必 issue 下。

如果想要直接体验，直接 clone 项目，运行 mvn spring-boot:run 命令即可进行访问。网址规则自行看教程后面。

如果想了解 Spring Security 可以看

Spring Boot 2.0+Srping Security+Thymeleaf的简易教程

Spring Boot 2 + Spring Security 5 + JWT 的单页应用Restful解决方案 （推荐）

特性

完全使用了 Shiro 的注解配置，保持高度的灵活性。
放弃 Cookie ，Session ，使用JWT进行鉴权，完全实现无状态鉴权。
JWT 密钥支持过期时间。
对跨域提供支持。

准备工作

在开始本教程之前，请保证已经熟悉以下几点。

Spring Boot 基本语法，至少要懂得 Controller 、 RestController 、 Autowired 等这些基本注释。其实看看官方的 Getting-Start 教程就差不多了。
JWT （Json Web Token）的基本概念，并且会简单操作JWT的 JAVA SDK。
Shiro 的基本操作，看下官方的 10 Minute Tutorial 即可。
模拟 HTTP 请求工具，我使用的是 PostMan。

简要的说明下我们为什么要用 JWT ，因为我们要实现完全的前后端分离，所以不可能使用 session， cookie 的方式进行鉴权，所以 JWT 就被派上了用场，你可以通过一个加密密钥来进行前后端的鉴权。

程序逻辑

我们 POST 用户名与密码到 /login 进行登入，如果成功返回一个加密 token，失败的话直接返回 401 错误。
之后用户访问每一个需要权限的网址请求必须在 header 中添加 Authorization 字段，例如 Authorization: token ，token 为密钥。
后台会进行 token 的校验，如果有误会直接返回 401。

Token加密说明

携带了 username 信息在 token 中。
设定了过期时间。
使用用户登入密码对 token 进行加密。

Token校验流程

获得 token 中携带的 username 信息。
进入数据库搜索这个用户，得到他的密码。
使用用户的密码来检验 token 是否正确。

准备Maven文件

新建一个 Maven 工程，添加相关的 dependencies。

复制代码<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>org.inlighting</groupId><artifactId>shiro-study</artifactId><version>1.0-SNAPSHOT</version><dependencies><dependency><groupId>org.apache.shiro</groupId><artifactId>shiro-spring</artifactId><version>1.3.2</version></dependency><dependency><groupId>com.auth0</groupId><artifactId>java-jwt</artifactId><version>3.2.0</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><version>1.5.8.RELEASE</version></dependency></dependencies><build><plugins><!-- Srping Boot 打包工具 --><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>1.5.7.RELEASE</version><executions><execution><goals><goal>repackage</goal></goals></execution></executions></plugin><!-- 指定JDK编译版本 --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><configuration><source>1.8</source><target>1.8</target><encoding>UTF-8</encoding></configuration></plugin></plugins></build>
</project>

注意指定JDK版本和编码。

构建简易的数据源

为了缩减教程的代码，我使用 HashMap 本地模拟了一个数据库，结构如下：

username	password	role	permission
smith	smith123	user	view
danny	danny123	admin	view,edit

这是一个最简单的用户权限表，如果想更加进一步了解，自行百度 RBAC。

之后再构建一个 UserService 来模拟数据库查询，并且把结果放到 UserBean 之中。

UserService.java

复制代码@Component
public class UserService {public UserBean getUser(String username) {// 没有此用户直接返回nullif (! DataSource.getData().containsKey(username))return null;UserBean user = new UserBean();Map<String, String> detail = DataSource.getData().get(username);user.setUsername(username);user.setPassword(detail.get("password"));user.setRole(detail.get("role"));user.setPermission(detail.get("permission"));return user;}
}

UserBean.java

复制代码public class UserBean {private String username;private String password;private String role;private String permission;public String getUsername() {return username;}public void setUsername(String username) {this.username = username;}public String getPassword() {return password;}public void setPassword(String password) {this.password = password;}public String getRole() {return role;}public void setRole(String role) {this.role = role;}public String getPermission() {return permission;}public void setPermission(String permission) {this.permission = permission;}
}

配置 JWT

我们写一个简单的 JWT 加密，校验工具，并且使用用户自己的密码充当加密密钥，这样保证了 token 即使被他人截获也无法破解。并且我们在 token 中附带了 username 信息，并且设置密钥5分钟就会过期。

复制代码public class JWTUtil {// 过期时间5分钟private static final long EXPIRE_TIME = 5*60*1000;/*** 校验token是否正确* @param token 密钥* @param secret 用户的密码* @return 是否正确*/public static boolean verify(String token, String username, String secret) {try {Algorithm algorithm = Algorithm.HMAC256(secret);JWTVerifier verifier = JWT.require(algorithm).withClaim("username", username).build();DecodedJWT jwt = verifier.verify(token);return true;} catch (Exception exception) {return false;}}/*** 获得token中的信息无需secret解密也能获得* @return token中包含的用户名*/public static String getUsername(String token) {try {DecodedJWT jwt = JWT.decode(token);return jwt.getClaim("username").asString();} catch (JWTDecodeException e) {return null;}}/*** 生成签名,5min后过期* @param username 用户名* @param secret 用户的密码* @return 加密的token*/public static String sign(String username, String secret) {try {Date date = new Date(System.currentTimeMillis()+EXPIRE_TIME);Algorithm algorithm = Algorithm.HMAC256(secret);// 附带username信息return JWT.create().withClaim("username", username).withExpiresAt(date).sign(algorithm);} catch (UnsupportedEncodingException e) {return null;}}
}

构建URL

ResponseBean.java

既然想要实现 restful，那我们要保证每次返回的格式都是相同的，因此我建立了一个 ResponseBean 来统一返回的格式。

复制代码public class ResponseBean {// http 状态码private int code;// 返回信息private String msg;// 返回的数据private Object data;public ResponseBean(int code, String msg, Object data) {this.code = code;this.msg = msg;this.data = data;}public int getCode() {return code;}public void setCode(int code) {this.code = code;}public String getMsg() {return msg;}public void setMsg(String msg) {this.msg = msg;}public Object getData() {return data;}public void setData(Object data) {this.data = data;}
}

自定义异常

为了实现我自己能够手动抛出异常，我自己写了一个 UnauthorizedException.java

复制代码public class UnauthorizedException extends RuntimeException {public UnauthorizedException(String msg) {super(msg);}public UnauthorizedException() {super();}
}

URL结构

URL	作用
/login	登入
/article	所有人都可以访问，但是用户与游客看到的内容不同
/require_auth	登入的用户才可以进行访问
/require_role	admin的角色用户才可以登入
/require_permission	拥有view和edit权限的用户才可以访问

Controller

复制代码@RestController
public class WebController {private static final Logger LOGGER = LogManager.getLogger(WebController.class);private UserService userService;@Autowiredpublic void setService(UserService userService) {this.userService = userService;}@PostMapping("/login")public ResponseBean login(@RequestParam("username") String username,@RequestParam("password") String password) {UserBean userBean = userService.getUser(username);if (userBean.getPassword().equals(password)) {return new ResponseBean(200, "Login success", JWTUtil.sign(username, password));} else {throw new UnauthorizedException();}}@GetMapping("/article")public ResponseBean article() {Subject subject = SecurityUtils.getSubject();if (subject.isAuthenticated()) {return new ResponseBean(200, "You are already logged in", null);} else {return new ResponseBean(200, "You are guest", null);}}@GetMapping("/require_auth")@RequiresAuthenticationpublic ResponseBean requireAuth() {return new ResponseBean(200, "You are authenticated", null);}@GetMapping("/require_role")@RequiresRoles("admin")public ResponseBean requireRole() {return new ResponseBean(200, "You are visiting require_role", null);}@GetMapping("/require_permission")@RequiresPermissions(logical = Logical.AND, value = {"view", "edit"})public ResponseBean requirePermission() {return new ResponseBean(200, "You are visiting permission require edit,view", null);}@RequestMapping(path = "/401")@ResponseStatus(HttpStatus.UNAUTHORIZED)public ResponseBean unauthorized() {return new ResponseBean(401, "Unauthorized", null);}
}

处理框架异常

之前说过 restful 要统一返回的格式，所以我们也要全局处理 Spring Boot 的抛出异常。利用 @RestControllerAdvice 能很好的实现。

复制代码@RestControllerAdvice
public class ExceptionController {// 捕捉shiro的异常@ResponseStatus(HttpStatus.UNAUTHORIZED)@ExceptionHandler(ShiroException.class)public ResponseBean handle401(ShiroException e) {return new ResponseBean(401, e.getMessage(), null);}// 捕捉UnauthorizedException@ResponseStatus(HttpStatus.UNAUTHORIZED)@ExceptionHandler(UnauthorizedException.class)public ResponseBean handle401() {return new ResponseBean(401, "Unauthorized", null);}// 捕捉其他所有异常@ExceptionHandler(Exception.class)@ResponseStatus(HttpStatus.BAD_REQUEST)public ResponseBean globalException(HttpServletRequest request, Throwable ex) {return new ResponseBean(getStatus(request).value(), ex.getMessage(), null);}private HttpStatus getStatus(HttpServletRequest request) {Integer statusCode = (Integer) request.getAttribute("javax.servlet.error.status_code");if (statusCode == null) {return HttpStatus.INTERNAL_SERVER_ERROR;}return HttpStatus.valueOf(statusCode);}
}

配置 Shiro

大家可以先看下官方的 Spring-Shiro 整合教程，有个初步的了解。不过既然我们用了 Spring-Boot，那我们肯定要争取零配置文件。

实现JWTToken

JWTToken 差不多就是 Shiro 用户名密码的载体。因为我们是前后端分离，服务器无需保存用户状态，所以不需要 RememberMe 这类功能，我们简单的实现下 AuthenticationToken 接口即可。因为 token 自己已经包含了用户名等信息，所以这里我就弄了一个字段。如果你喜欢钻研，可以看看官方的 UsernamePasswordToken 是如何实现的。

复制代码public class JWTToken implements AuthenticationToken {// 密钥private String token;public JWTToken(String token) {this.token = token;}@Overridepublic Object getPrincipal() {return token;}@Overridepublic Object getCredentials() {return token;}
}

实现Realm

realm 的用于处理用户是否合法的这一块，需要我们自己实现。

复制代码@Service
public class MyRealm extends AuthorizingRealm {private static final Logger LOGGER = LogManager.getLogger(MyRealm.class);private UserService userService;@Autowiredpublic void setUserService(UserService userService) {this.userService = userService;}/*** 大坑！，必须重写此方法，不然Shiro会报错*/@Overridepublic boolean supports(AuthenticationToken token) {return token instanceof JWTToken;}/*** 只有当需要检测用户权限的时候才会调用此方法，例如checkRole,checkPermission之类的*/@Overrideprotected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals) {String username = JWTUtil.getUsername(principals.toString());UserBean user = userService.getUser(username);SimpleAuthorizationInfo simpleAuthorizationInfo = new SimpleAuthorizationInfo();simpleAuthorizationInfo.addRole(user.getRole());Set<String> permission = new HashSet<>(Arrays.asList(user.getPermission().split(",")));simpleAuthorizationInfo.addStringPermissions(permission);return simpleAuthorizationInfo;}/*** 默认使用此方法进行用户名正确与否验证，错误抛出异常即可。*/@Overrideprotected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken auth) throws AuthenticationException {String token = (String) auth.getCredentials();// 解密获得username，用于和数据库进行对比String username = JWTUtil.getUsername(token);if (username == null) {throw new AuthenticationException("token invalid");}UserBean userBean = userService.getUser(username);if (userBean == null) {throw new AuthenticationException("User didn't existed!");}if (! JWTUtil.verify(token, username, userBean.getPassword())) {throw new AuthenticationException("Username or password error");}return new SimpleAuthenticationInfo(token, token, "my_realm");}
}

在 doGetAuthenticationInfo() 中用户可以自定义抛出很多异常，详情见文档。

重写 Filter

所有的请求都会先经过 Filter，所以我们继承官方的 BasicHttpAuthenticationFilter ，并且重写鉴权的方法。

代码的执行流程 preHandle -> isAccessAllowed -> isLoginAttempt -> executeLogin 。

复制代码public class JWTFilter extends BasicHttpAuthenticationFilter {private Logger LOGGER = LoggerFactory.getLogger(this.getClass());/*** 判断用户是否想要登入。* 检测header里面是否包含Authorization字段即可*/@Overrideprotected boolean isLoginAttempt(ServletRequest request, ServletResponse response) {HttpServletRequest req = (HttpServletRequest) request;String authorization = req.getHeader("Authorization");return authorization != null;}/****/@Overrideprotected boolean executeLogin(ServletRequest request, ServletResponse response) throws Exception {HttpServletRequest httpServletRequest = (HttpServletRequest) request;String authorization = httpServletRequest.getHeader("Authorization");JWTToken token = new JWTToken(authorization);// 提交给realm进行登入，如果错误他会抛出异常并被捕获getSubject(request, response).login(token);// 如果没有抛出异常则代表登入成功，返回truereturn true;}/*** 这里我们详细说明下为什么最终返回的都是true，即允许访问* 例如我们提供一个地址 GET /article* 登入用户和游客看到的内容是不同的* 如果在这里返回了false，请求会被直接拦截，用户看不到任何东西* 所以我们在这里返回true，Controller中可以通过 subject.isAuthenticated() 来判断用户是否登入* 如果有些资源只有登入用户才能访问，我们只需要在方法上面加上 @RequiresAuthentication 注解即可* 但是这样做有一个缺点，就是不能够对GET,POST等请求进行分别过滤鉴权(因为我们重写了官方的方法)，但实际上对应用影响不大*/@Overrideprotected boolean isAccessAllowed(ServletRequest request, ServletResponse response, Object mappedValue) {if (isLoginAttempt(request, response)) {try {executeLogin(request, response);} catch (Exception e) {response401(request, response);}}return true;}/*** 对跨域提供支持*/@Overrideprotected boolean preHandle(ServletRequest request, ServletResponse response) throws Exception {HttpServletRequest httpServletRequest = (HttpServletRequest) request;HttpServletResponse httpServletResponse = (HttpServletResponse) response;httpServletResponse.setHeader("Access-control-Allow-Origin", httpServletRequest.getHeader("Origin"));httpServletResponse.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS,PUT,DELETE");httpServletResponse.setHeader("Access-Control-Allow-Headers", httpServletRequest.getHeader("Access-Control-Request-Headers"));// 跨域时会首先发送一个option请求，这里我们给option请求直接返回正常状态if (httpServletRequest.getMethod().equals(RequestMethod.OPTIONS.name())) {httpServletResponse.setStatus(HttpStatus.OK.value());return false;}return super.preHandle(request, response);}/*** 将非法请求跳转到 /401*/private void response401(ServletRequest req, ServletResponse resp) {try {HttpServletResponse httpServletResponse = (HttpServletResponse) resp;httpServletResponse.sendRedirect("/401");} catch (IOException e) {LOGGER.error(e.getMessage());}}
}

getSubject(request, response).login(token); 这一步就是提交给了 realm 进行处理。

配置Shiro

复制代码@Configuration
public class ShiroConfig {@Bean("securityManager")public DefaultWebSecurityManager getManager(MyRealm realm) {DefaultWebSecurityManager manager = new DefaultWebSecurityManager();// 使用自己的realmmanager.setRealm(realm);/** 关闭shiro自带的session，详情见文档* http://shiro.apache.org/session-management.html#SessionManagement-StatelessApplications%28Sessionless%29*/DefaultSubjectDAO subjectDAO = new DefaultSubjectDAO();DefaultSessionStorageEvaluator defaultSessionStorageEvaluator = new DefaultSessionStorageEvaluator();defaultSessionStorageEvaluator.setSessionStorageEnabled(false);subjectDAO.setSessionStorageEvaluator(defaultSessionStorageEvaluator);manager.setSubjectDAO(subjectDAO);return manager;}@Bean("shiroFilter")public ShiroFilterFactoryBean factory(DefaultWebSecurityManager securityManager) {ShiroFilterFactoryBean factoryBean = new ShiroFilterFactoryBean();// 添加自己的过滤器并且取名为jwtMap<String, Filter> filterMap = new HashMap<>();filterMap.put("jwt", new JWTFilter());factoryBean.setFilters(filterMap);factoryBean.setSecurityManager(securityManager);factoryBean.setUnauthorizedUrl("/401");/** 自定义url规则* http://shiro.apache.org/web.html#urls-*/Map<String, String> filterRuleMap = new HashMap<>();// 所有请求通过我们自己的JWT FilterfilterRuleMap.put("/**", "jwt");// 访问401和404页面不通过我们的FilterfilterRuleMap.put("/401", "anon");factoryBean.setFilterChainDefinitionMap(filterRuleMap);return factoryBean;}/*** 下面的代码是添加注解支持*/@Bean@DependsOn("lifecycleBeanPostProcessor")public DefaultAdvisorAutoProxyCreator defaultAdvisorAutoProxyCreator() {DefaultAdvisorAutoProxyCreator defaultAdvisorAutoProxyCreator = new DefaultAdvisorAutoProxyCreator();// 强制使用cglib，防止重复代理和可能引起代理出错的问题// https://zhuanlan.zhihu.com/p/29161098defaultAdvisorAutoProxyCreator.setProxyTargetClass(true);return defaultAdvisorAutoProxyCreator;}@Beanpublic LifecycleBeanPostProcessor lifecycleBeanPostProcessor() {return new LifecycleBeanPostProcessor();}@Beanpublic AuthorizationAttributeSourceAdvisor authorizationAttributeSourceAdvisor(DefaultWebSecurityManager securityManager) {AuthorizationAttributeSourceAdvisor advisor = new AuthorizationAttributeSourceAdvisor();advisor.setSecurityManager(securityManager);return advisor;}
}

里面 URL 规则自己参考文档即可 shiro.apache.org/web.html 。