用法

基础用法

启用权限拦截

引入依赖即可启用权限拦截，默认拦截所有请求。

<dependency>
    <groupId>cn.coufran</groupId>
    <artifactId>coufran-spring-boot-starter-auth</artifactId>
    <version>1.3.0</version>
</dependency>

切换认证方式

使用@EnableAuthXxxx切换认证方式。例如：

@Configuration
@EnableAuthSession // 启用Session认证
//@EnableAuthToken // 启用Token认证
public class AuthConfig {
}

认证方式	启用注解	说明
Session认证	`@EnableAuthSession`	使用Session和Cookie实现认证
Token认证	`@EnableAuthToken`	使用Token实现认证

标记公共接口

使用@Public注解标记公共接口，公共接口不会被拦截。例如：

@RestController
public class OpenController {
    @ReqeustMapping("/demo")
    @Public // 标记公共接口
    public void demo() {
    }
}

与权限拦截交互

所有的交互都是通过AuthUser完成的。可以使用Spring注入AuthUser的方式与其交互，AuthUser方法如下：

登录：AuthUser.login(data)，data为保存在上下文中的数据。
登出：AuthUser.logout()。
获取保存在上下文的数据：AuthUser.getData()。
是否通过认证：AuthUser.isAuthenticated()。

例如：

@RestController
public class DemoController {
    @Resource
    private AuthUser<User> authUser;

    @RequestMapping("/demo")
    public Certificate demo() {
        Certificate certificate;
        if (!authUser.isAuthenticated()) { // 判断是否登录（通过认证）
            certificate = authUser.login(new User("xxx")); // 登录系统
        }
        User user = authUser.getData(); // 访问上下文数据
        if (user.autoLogout()) {
            authUser.logout(); // 登出系统
        }
        return certificate;
    }
}

白名单设置

通过配置拦截白名单，可以将某些不需要拦截的请求放行。可以通过配置文件配置coufran.auth.whitePath，例如：

coufran:
  auth:
    whitePath: /openPath1, /openPath2, /open/openPath3

自定义权限拦截插件

拦截器默认只实现了未认证用户的拦截，如果需要更高级的拦截功能，可以自定义插件，注入拦截过程。自定义权限拦截插件的方式如下：

定义类，实现AuthAddition接口。
重写authIntercept(xxx)方法，需要拦截的请求，抛出AuthException。
将插件类使用@Component标记为Spring Bean。

例如：

@Component
public class DemoAuthAddition implements AuthAddition<Data> {
    @Override
    public void authIntercept(AuthUser<Data> authUser, HttpServletRequest request, Object handler) throws AuthException {
        boolean allowed = false; // do sth.
        if (!allowed) { // 不允许，进行拦截
            throw new AuthException(HttpStatus.FORBIDDEN, Result.error(40300, "测试拦截"));
        }
    }
}

认证方式介绍

权限拦截支持多种认证方式，其中内置了三种认证方式。

简单认证（默认，不推荐）

简单认证无法实现跨请求的认证，请求进入系统默认未认证，只能请求开放接口。

Session认证

使用@EnableAuthSession启用Session认证。
Session认证基于HTTP容器的Session，将权限数据保存在Session中，实现跨请求的认证。
该种方式不支持分布式集群系统。

Token认证

使用@EnableAuthToken启用Token认证。
Token认证基于Token实现认证，请求是无状态的，所有数据保存在Token中，可实现跨服务的认证。
可自定义Token生成规则。

自定义Token注册器

自定义类实现TokenRegister接口。
重写generate(xxx)和parse(xxx)方法。
使用@Component声明为Spring Bean。

例如：

@Component
public class DemoTokenRegister implements TokenRegister {
    public String generate(String payload, int expireTimeDefault) {
        // 生成token
        String token = "xxx";
        return token;
    }
    
    public String parse(String accessToken) {
        // 解析Token，Token过期或解析失败返回null
        String payload = "xxx";
        return payload;
    }
}

高级用法

自定义认证方式

如果内置的两种认证方式无法满足您的需求，您可以自定义认证方式或基于内置的认证方式进行扩展。

核心接口介绍

AuthUser：该接口提供了登录、登出、获取数据等系统与权限拦截相关的交互方法，Bean scope为request。
AuthUserManager：AuthUser的登录、登出等操作将委托给AuthUserManager，负责创建、管理AuthUser。
Certificate：访问系统的证书，不同的认证方式证书不同，有可能不需要。

自定义步骤

实现AuthUser，建议继承AbstractAuthUser，然后在其基础上做定制。
实现AuthUserManager。
实现Certificate，封装证书。
定义配置，定义AuthUser为request scope的Spring Bean，在未认证时创建匿名的，认证时恢复原来的。
建议使用@EnableAuthXxxx定义认证方式的启动开关。

自定义Token数据转换器

Token认证时，数据将被固化在Token中，需要使用TokenPayloadConverter实现数据和字符串你的转换。系统自带了一个PojoJsonTokenPayloadConverter，可以实现基本POJO数据的转换。如果需要转换其他数据或者需要自定义转换过程，可以自定义TokenPayloadConverter。

@Configuration
public class TokenPayloadConverterConfig {
    @Resource(name = "tokenPayloadConverters")
    private List<TokenPayloadConverter<?>> tokenPayloadConverters;

    @PostConstruct
    public void configConverter() {
        // 构造Converter
        TokenPayloadConverter<?> myConverter = new MyConverter();
        // 添加到Converter List中，位置越靠前，优先级越高
        tokenPayloadConverters.add(0, myConverter);
    }
}

自定义Token存储

当前Refresh Token存储不支持集群，如果需要支持集群，可自定义Token存储。

@Component
public class MyRefreshTokenRepository implements RefreshTokenRepository {
    public void save(String refreshToken, Date expireTime) {
        // doSth.
    }
    
    public boolean delete(String refreshToken) {
        // doSth.
        return true;
    }
}

自定义秘钥存储

当前秘钥存储在进程内存中，当应用重启后，会重新生成秘钥，导致现有的Token失效，并且，在集群环境中，秘钥无法同步。

我们为您准备了一个基于文件的存储器FileKeyStore，如果需要，可以通过@Bean将FileKeyStore配置在Spring Bean容器中。

import cn.coufran.springboot.starter.auth.impl.token.KeyStore;
import org.springframework.stereotype.Component;

@Component
public class MyKeyStore implements KeyStore {
    public void save(byte[] key) {
        // save key
    }
    
    public byte[] load() {
        // load key
    }
}

在创建TokenRegister时，会调用秘钥存储器获取秘钥，如果load()方法返回null，则会创建新的秘钥并调用save()方法保存。

历史版本

v1.0（2021-06-25）

增加基于Session和Token的认证。
增加开放接口定义。
增加自定义权限拦截。
增加拦截白名单。

v1.1（2021-07-13）

增加TokenPayloadConverter转换器，实现自定义解析Token。
增加refreshToken和refresh方法，实现刷新登录状态。
增加refreshTokenRepository。
增加对OPTION请求的支持。

v1.2（2021-11-xx）

增加KeyStore，支持Token秘钥存储，重启后Token不再失效。

v1.3（2022-05-21）

更换Maven依赖。

Coufran / coufran-spring-boot-starter-auth

用法

基础用法

启用权限拦截

切换认证方式

标记公共接口

与权限拦截交互

白名单设置

自定义权限拦截插件

认证方式介绍

简单认证（默认，不推荐）

Session认证

Token认证

自定义Token注册器

高级用法

自定义认证方式

核心接口介绍

自定义步骤

自定义Token数据转换器

自定义Token存储

自定义秘钥存储

历史版本

v1.0（2021-06-25）

v1.1（2021-07-13）

v1.2（2021-11-xx）

v1.3（2022-05-21）

简介

发行版 (7)

贡献者

近期动态

Coufran / coufran-spring-boot-starter-auth .gitee-modal { width: 500px !important; }

用法

基础用法

启用权限拦截

切换认证方式

标记公共接口

与权限拦截交互

白名单设置

自定义权限拦截插件

认证方式介绍

简单认证（默认，不推荐）

Session认证

Token认证

自定义Token注册器

高级用法

自定义认证方式

核心接口介绍

自定义步骤

自定义Token数据转换器

自定义Token存储

自定义秘钥存储

历史版本

v1.0（2021-06-25）

v1.1（2021-07-13）

v1.2（2021-11-xx）

v1.3（2022-05-21）

简介

发行版 (7)

贡献者

近期动态

搜索帮助

Coufran / coufran-spring-boot-starter-auth