jap-oauth2-spring-boot-starter 模块使用帮助

# jap-oauth2-spring-boot-starter

为JustAuth Plus (opens new window) 的 oauth2 授权策略开发的Spring Boot Starter依赖。

可访问本starter的demo (opens new window) ，包含较为详尽的调用流程和相关配置说明。

# 开源仓库地址：

GitHub (opens new window)

Gitee (opens new window)

# 快速开始

# 引入依赖

在你项目的 pom.xml 文件中添加jap-social的starter的maven依赖：

<dependency>
    <groupId>xyz.dong6662.jap.spring.boot</groupId>
    <artifactId>jap-oauth2-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

1
2
3
4
5

# application.properties中配置

首先在 application.properties 文件中完成一些基本配置，这些配置信息所有授权策略均会使用到：

# 基础配置
# 如果启启用了sso，则需要对sso进行一些配置
jap.basic.sso=false
jap.basic.cache-expire-time=12
jap.basic.token-expire-time=12
# sso
jap.sso.cookie-domain=xxx
jap.sso.cookie-max-age=xxx
jap.sso.cookie-name=xxx

1
2
3
4
5
6
7
8
9

然后，为oauth2策略添加它的配置信息，下面以gitee平台为例，展示授权码方式的配置信息：

# oauth2策略

# gitee平台，相关api在 https://gitee.com/api/v5/oauth_doc#/
# 授权码方式，此方式下response-type需为type
jap.oauth2[0].platform=gitee
jap.oauth2[0].grant-type=authorization_code
jap.oauth2[0].response-type=code
jap.oauth2[0].client-id=e9b4f19402d2ccb3375f5be19b9c76738fffe071d6b450a65dc4baa70a7ab752
jap.oauth2[0].client-secret=83bd48fc1ec9807f769c6328304e6222f2290b57d60f346a24976b48a752b794
# 从gitee oauth服务获取授权码code的地址
jap.oauth2[0].authorization-url=https://gitee.com/oauth/authorize
# 你的应用服务器接收code的地址
jap.oauth2[0].callback-url=http://localhost:8080/oauth/gitee/authorization-code
# 获取token的地址
jap.oauth2[0].token-url=https://gitee.com/oauth/token
jap.oauth2[0].userinfo-url=https://gitee.com/api/v5/user
# 获取user info的方法，GET、POST等。每个platform的不一样，需要查看具体平台的API
jap.oauth2[0].user-info-endpoint-method-type=get
# 如果访问authorization-url没有带上state参数，这里需要设为false
jap.oauth2[0].verify-state=false

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

其他其中授权方式，如password、implicit也类似，可参考demo。

# 实现JapUserService接口

与jap-oauth2实现JapUserService接口不同的是，🎈你不仅需要为该实现类添加@Service注解，还需要对该注解添加参数JapUserServiceType.Oauth2，表明这是oauth2策略的实现类：

@Service(JapUserServiceType.OAUTH2)
public class Oauth2UserServiceImpl implements JapUserService {

    /**
     * 模拟 DB 操作
     */
    private static final List<JapUser> userDatas = Lists.newArrayList();

    /**
     * 根据第三方平台标识（platform）和第三方平台的用户 uid 查询数据库
     *
     * @param platform 第三方平台标识
     * @param uid      第三方平台的用户 uid
     * @return JapUser
     */
    @Override
    public JapUser getByPlatformAndUid(String platform, String uid) {
        // FIXME 注意：此处仅作演示用，并没有判断 platform，实际业务系统中需要根据 platform 和 uid 进行获取唯一用户
        return userDatas.stream().filter(user -> user.getUserId().equals(uid)).findFirst().orElse(null);
    }

    /**
     * 创建并获取第三方用户，相当于第三方登录成功后，将授权关系保存到数据库（开发者业务系统中 oauth2 user -> sys user 的绑定关系）
     *
     * @param platform 第三方平台标识
     * @param userInfo JustAuth 中的 AuthUser
     * @return JapUser
     */
    @Override
    public JapUser createAndGetOauth2User(String platform, Map<String, Object> userInfo, Object tokenInfo) {
        // FIXME 业务端可以对 tokenInfo 进行保存或其他操作
        AccessToken accessToken = (AccessToken) tokenInfo;
        System.out.println(JsonUtil.toJsonString(accessToken));
        // FIXME 注意：此处仅作演示用，不同的 oauth 平台用户id都不一样，此处需要开发者自己分析第三方平台的用户信息，提取出用户的唯一ID
        String uid = (String) userInfo.get("userId");
        // 查询绑定关系，确定当前用户是否已经登录过业务系统
        JapUser japUser = this.getByPlatformAndUid(platform, uid);
        if (null == japUser) {
            japUser = createJapUser();
            japUser.setAdditional(userInfo);
            userDatas.add(japUser);
        }
        return japUser;
    }

    private JapUser createJapUser() {
        JapUser user = new JapUser();
        user.setUserId("1");
        user.setUsername("justauth");
        user.setPassword("justauthpassword");
        return user;
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

当然，也可以在 application.properties 中指定oauth2策略的JapUserService实现类，即指定该实现类的包全名（binary name）：

jap.oauth2-user-service=xyz.dong6662.japspringbootstarterdemo.service.Oauth2UserServiceImpl

# 实现Controller

@RestController
@RequestMapping("/oauth")
public class Oauth2Controller {
    @Autowired
    Oauth2Strategy oauth2Strategy;
    @Autowired
    Oauth2Properties oauth2Properties;

    /**
     * 阿里云 AuthorizationCode授权方式
     * @return
     */
    @RequestMapping("/aliyun/authorization-code")
    public JapResponse aliyunAuthorizationCode(HttpServletRequest request, HttpServletResponse response){
        return oauth2Strategy.authenticate(oauth2Properties.getOauth2().get(3), request, response);
    }

    @RequestMapping("/aliyun/refresh-token")
    public JapResponse aliyunRefreshToken(HttpServletRequest request, HttpServletResponse response) {
        // 这是获取JapUser的一种方式
        JapUser japUser = japUserStore.get(request, response);
        // FIXME: aliyun平台不会在授权信息中返回refresh_token，因此这里refreshToken的是为null
        String refreshToken = ((Kv) japUser.getAdditional()).getString("refresh-token");
        return oauth2Strategy.refreshToken(oauth2Properties.getOauth2().get(3), refreshToken);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 使用JapTemplate

这是为了简化四种授权策略的调用而开发的starter依赖。只需在引入了jap-oauth2的maven依赖的基础上，引入 JapTemplate的依赖便可使用：

<dependency>
    <groupId>xyz.dong6662.jap.spring.boot</groupId>
    <artifactId>jap-spring-boot-starter-template</artifactId>
    <version>1.0.0</version>
</dependency>

1
2
3
4
5

这样，在Controller中的授权代码只需一行便可完成授权：

@RestController
@RequestMapping("/oauth")
public class Oauth2Controller {
    @Autowired
    JapTemplate japTemplate;
    @Autowired
    JapUserStore japUserStore;

    /**
     * gitee AuthorizationCode授权方式
     */
    @RequestMapping("/gitee/authorization-code") //callback-url
    public JapResponse authorizationCode(){
        return japTemplate.opsForOauth2().authenticateByAuthorizationCode("gitee");
    }

    /**
     * gitee password授权方式
     */
    @RequestMapping("/gitee/password")
    public JapResponse passwordGrantType(String username, String password) {
        return japTemplate.opsForOauth2().authenticateByPassword("gitee", username, password);
    }

    @RequestMapping("/gitee/refresh-token")
    public JapResponse refreshToken(HttpServletRequest request, HttpServletResponse response){
        // 这是获取JapUser的一种方式
        JapUser japUser = japUserStore.get(request, response);
        // FIXME: 2021/9/25 gitee平台不会在授权信息中返回refresh_token
        String refreshToken = ((Kv) japUser.getAdditional()).getString("refresh-token");
        return japTemplate.opsForOauth2().refreshToken("gitee",refreshToken);
    }

    /**
     * github AuthorizationCode授权方式
     * @return
     */
    @RequestMapping("/github/authorization-code")
    public JapResponse github(){
        // FIXME: 2021/9/25 GitHub的授权方式似乎并不是严格的oauth2，查看：https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#response
        //  会发现默认情况下返回的授权信息不是json格式，而是类似这样：access_token=XXX&token_type=bearer
        return japTemplate.opsForOauth2().authenticateByAuthorizationCode("github");
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

# 引入Redis缓存

oauth2和oidc授权策略都会缓存token，除了默认的缓存类型（default）外，本starter还支持Redis作为缓存。若采用Redis方式，需要引入Redis的Spring Boot Starter：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

1
2
3
4

并在application.properties中完成redis的一些基本配置：

# redis基础配置
spring.redis.port=6379
spring.redis.host=127.0.0.1
spring.redis.timeout=3m

1
2
3
4

然后指定Redis作为token的缓存即可：

# token缓存
jap.cache.token.type=redis
jap.cache.token.expire-time=3m

1
2
3

编辑

#jap-oauth2 #springboot #starter

Last Updated: 2021/10/21, 17:48:43

← jap-social-spring-boot-starter 模块使用帮助 jap-oidc-spring-boot-starter 模块使用帮助→