# jap-spring-boot-starter

**Repository Path**: fujieid/jap-spring-boot-starter

## Basic Information

- **Project Name**: jap-spring-boot-starter
- **Description**: Spring Boot starter for JustAuth Plus.
- **Primary Language**: Java
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 3
- **Created**: 2021-09-26
- **Last Updated**: 2025-05-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jap-spring-boot-starter

这是为[JustAuth Plus](https://justauth.plus/) 开发的Spring Boot starter依赖。利用Spring Boot提供的特性，简化了调用流程。

可访问本starter的[demo](https://github.com/Vector6662/jap-spring-boot-starter-demo) ，包含较为详尽的调用流程和相关配置说明。

## 快速开始

### 一些基本的配置

#### 一、引入依赖

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

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

项目为JustAuth Plus的[四种授权策略](https://justauth.plus/quickstart/jap-simple/) 都提供了相应的starter依赖。根据你的应用需要支持的授权策略，引入相应的starter。比如，你的项目需要`simple`和`oauth2`授权方式，则只需要在`pom.xml`中引入：

```xml
<dependency>
    <groupId>com.fujieid.jap.spring.boot</groupId>
    <artifactId>jap-simple-spring-boot-starter</artifactId> <!--jap simple策略-->
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>com.fujieid.jap.spring.boot</groupId>
    <artifactId>jap-oauth2-spring-boot-starter</artifactId> <!--jap oauth2策略-->
    <version>1.0.0</version>
</dependency>
```

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

```xml
<dependency>
    <groupId>com.fujieid.jap.spring.boot</groupId>
    <artifactId>jap-social-spring-boot-starter</artifactId> <!--jap social策略-->
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>com.fujieid.jap.spring.boot</groupId>
    <artifactId>jap-oidc-spring-boot-starter</artifactId> <!--jap oidc策略-->
    <version>1.0.0</version>
</dependency>
```



#### 二、application.properties中的基础配置

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

```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
```



准备工作已完成！下面是Oauth2授权方式的指南，其余授权方式大同小异，[demo](https://github.com/Vector6662/jap-spring-boot-starter-demo)中有详尽的描述。

### 实现Ouath2授权

#### Step 1：为oauth2实现`JapUserServiceType`

具体可以参考[使用jap-oauth2：实现 `JapUserService` 接口](https://justauth.plus/quickstart/jap-oauth2/#%E5%AE%9E%E7%8E%B0-japuserservice-%E6%8E%A5%E5%8F%A3) 。

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

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

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

```properties
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：

```properties
# 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即可。

```java
@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别的授权方式，比如*密码*，可以调用方法：

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

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



## 引入redis缓存

若需采用redis缓存token，或social策略的缓存，需要引入Spring Boot的redis starter：

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

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

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

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

首先是token：

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

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

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



## 较为完整的配置信息

demo中的[`application.properties`](https://github.com/Vector6662/jap-spring-boot-starter-demo/blob/master/src/main/resources/application.properties)文件包含了较为完整的配置，请查阅。



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

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依赖：

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


## 推荐阅读

1. 若对oauth授权策略不太熟悉，推荐阅读阮一峰老师的两篇文章： [OAuth 2.0 的四种方式](https://www.ruanyifeng.com/blog/2019/04/oauth-grant-types.html) 和 [GitHub OAuth 第三方登录示例教程](https://www.ruanyifeng.com/blog/2019/04/github-oauth.html)。