jap-spring-boot-starter

这是为JustAuth Plus (opens new window) 开发的Spring Boot starter依赖。利用Spring Boot提供的特性，简化了调用流程。

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

开源仓库地址：

GitHub (opens new window)

Gitee (opens new window)

快速开始

1.基本配置

1.1 引入依赖

首先需要引入***template***依赖，该依赖提供了大量简化的授权方法调用：

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

项目为JustAuth Plus的四种授权策略 (opens new window) 都提供了相应的starter依赖。根据你的应用需要支持的授权策略，引入相应的starter。比如，你的项目需要simple和oauth2授权方式，则只需要在pom.xml中引入：

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

其余两种授权策略的maven坐标如下：

<dependency>
    <groupId>xyz.dong6662.jap.spring.boot</groupId>
    <artifactId>jap-social-spring-boot-starter</artifactId> <!--jap social策略-->
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>xyz.dong6662.jap.spring.boot</groupId>
    <artifactId>jap-oidc-spring-boot-starter</artifactId> <!--jap oidc策略-->
    <version>1.0.0</version>
</dependency>

1.2 application.properties中的基础配置

引入maven依赖后，你需要对jap-spring–boot-starter进行一些基础配置，多数情况下采用默认即可。下面是一些简单的例子：

# 基础配置
# 如果启启用了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

准备工作已完成！下面是Oauth2授权方式的指南，其余授权方式大同小异，demo (opens new window)中有详尽的描述。

2.实现Ouath2授权

Step 1：为oauth2实现JapUserServiceType

具体可以参考使用jap-oauth2：实现 JapUserService 接口 (opens new window) 。

❗❗❗特别注意，与链接中代码不同的是，你需要在@Service注解中添加参数JapUserServiceType.OAUTH2，表明这是oauth2的JapUserService，像这样：

@Service(JapUserServiceType.OAUTH2) //表明这是oauth2的service
public class Oauth2UserServiceImpl implements JapUserService {
	......
}

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

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

Step 2：application.properties中配置oauth2

oauth2提供了五种授权方式：授权码（authorization-code）、隐式（implicit）、密码（password）、client-credentials、refresh-token，选择一种或多种作为你的应用支持的oauth2授权方式。

下边是gitee平台 授权码 方式的demo：

# gitee平台，相关api在 https://gitee.com/api/v5/swagger#/getV5User
# 授权码方式，此方式下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
# 获取授权码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

Step 3：编写Controller

使用JapTemplate，仅需在Controller中编写少量代码。调用JapTemplate#authenticateByAuthorizationCode方法，表明使用的是授权码方式，并指定platform即可。

@RestController
@RequestMapping("/oauth")
public class Oauth2Controller {
    @Autowired
    JapTemplate japTemplate;
    
    @RequestMapping("/gitee/authorization-code") //callback-url
    public JapResponse authorizationCode(){
        // 访问该路径需要有code参数
        return japTemplate.opsForOauth2().authenticateByAuthorizationCode("gitee");
    }
}

需要留意的是，这里的url也是上边配置信息中jap.oauth2[0].callback-url填写的参数。

若你还想采用oauth2别的授权方式，比如密码，可以调用方法：

public JapResponse authenticateByPassword(String platform, String username, String password);

但别忘了在配置文件application.properties中添加密码方式相应的配置信息。

引入redis缓存

若需采用redis来缓存token，或作为social策略的缓存，需要引入Redis的Spring Boot Starter：

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

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

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

目前为提供了两类信息的缓存。

首先是token：

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

其次，social授权策略有它单独的缓存：

# social 缓存类型
jap.social.cache.type=redis

较为完整的配置信息

demo中的application.properties (opens new window)文件包含了较为完整的配置，请查阅。

一些可能出现的报错（持续更新）

1. 报错信息：

   Parameter 3 of method simpleStrategy in com.fujieid.jap.spring.boot.japsimplespringbootstarter.autoconfigure.SimpleAutoConfiguration required a bean of type 'com.fujieid.jap.core.cache.JapCache' that could not be found.
   

   有可能你采用了redis作为JapCache的缓存，但是忘记加入redis的starter依赖。请在项目的pom.xml文件中加入redis的starter依赖：

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

推荐阅读

1. 若对oauth授权策略不太熟悉，推荐阅读阮一峰老师的两篇文章： OAuth 2.0 的四种方式 (opens new window) 和 GitHub OAuth 第三方登录示例教程 (opens new window)。