JustAuth/docs/how-to-use.md

在前面有介绍到，JustAuth的特点之一就是简，极简主义，不给使用者造成不必要的障碍。

既然牛皮吹下了， 那么如何才能用JustAuth实现第三方登录呢？

使用步骤

使用JustAuth总共分三步（这三步也适合于JustAuth支持的任何一个平台）：

1. 申请注册第三方平台的开发者账号
2. 创建第三方平台的应用，获取配置信息(accessKey, secretKey, redirectUri)
3. 使用该工具实现授权登陆

使用方式

• 引入依赖

<dependency>
    <groupId>me.zhyd.oauth</groupId>
    <artifactId>JustAuth</artifactId>
    <version>${latest.version}</version>
</dependency>

获取最新版本：JustAuth

• 调用api

// 创建授权request
AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder()
        .clientId("clientId")
        .clientSecret("clientSecret")
        .redirectUri("redirectUri")
        .build());
// 生成授权页面
authRequest.authorize("state");
// 授权登录后会返回code（auth_code（仅限支付宝））、state，1.8.0版本后，可以用AuthCallback类作为回调接口的参数
// 注：JustAuth默认保存state的时效为3分钟，3分钟内未使用则会自动清除过期的state
authRequest.login(callback);

注意，JustAuth从v1.14.0开始默认集成了的simple-http作为HTTP通用接口（更新说明见JustAuth 1.14.0版本正式发布！完美解耦HTTP工具），鉴于一般项目中都已经集成了HTTP工具，比如OkHttp3、apache HttpClient、hutool-http，因此为了减少不必要的依赖，从v1.14.0开始JustAuth将不会默认集成hutool-http，如果开发者的项目是全新的或者项目内没有集成HTTP实现工具，请自行添加对应的HTTP实现类，备选依赖如下：

• hutool-http

  <dependency>
      <groupId>cn.hutool</groupId>
      <artifactId>hutool-http</artifactId>
      <version>5.2.5</version>
  </dependency>
  

• httpclient

  <dependency>
  	<groupId>org.apache.httpcomponents</groupId>
    	<artifactId>httpclient</artifactId>
    	<version>4.5.12</version>
  </dependency>
  

• okhttp

  <dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.4.1</version>
  </dependency>
  

API分解

JustAuth的核心就是一个个的request，每个平台都对应一个具体的request类，所以在使用之前，需要就具体的授权平台创建响应的request

// 创建授权request
AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder()
        .clientId("clientId")
        .clientSecret("clientSecret")
        .redirectUri("redirectUri")
        .build());

所有可用的Request列表请参考：已集成的平台

获取授权链接

String authorizeUrl = authRequest.authorize("state");

获取到authorizeUrl后，可以手动实现redirect到authorizeUrl上

伪代码

/**
 * 
 * @param source 第三方授权平台，以本例为参考，该值为gitee（因为上面声明的AuthGiteeRequest）
 */
@RequestMapping("/render/{source}")
public void renderAuth(@PathVariable("source") String source, HttpServletResponse response) throws IOException {
    AuthRequest authRequest = getAuthRequest(source);
    String authorizeUrl = authRequest.authorize(AuthStateUtils.createState());
    response.sendRedirect(authorizeUrl);
}

注：state建议必传！state在OAuth的流程中的主要作用就是保证请求完整性，防止CSRF风险，此处传的state将在回调时传回

登录(获取用户信息)

AuthResponse response = authRequest.login(callback);

授权登录后会返回code（auth_code（仅限支付宝）、authorization_code（仅限华为））、state，1.8.0版本后，用AuthCallback类作为回调接口的入参

伪代码

/**
 * 
 * @param source 第三方授权平台，以本例为参考，该值为gitee（因为上面声明的AuthGiteeRequest）
 */
@RequestMapping("/callback/{source}")
public Object login(@PathVariable("source") String source, AuthCallback callback) {
    AuthRequest authRequest = getAuthRequest(source);
    AuthResponse response = authRequest.login(callback);
    return response;
}

注：第三方平台中配置的授权回调地址，以本文为例，在创建授权应用时的回调地址应为：[host]/callback/gitee

刷新token

注：refresh功能，并不是每个平台都支持

AuthResponse response = authRequest.refresh(AuthToken.builder().refreshToken(token).build());

伪代码

/**
 * 
 * @param source 第三方授权平台，以本例为参考，该值为gitee（因为上面声明的AuthGiteeRequest）
 * @param token  login成功后返回的refreshToken
 */
@RequestMapping("/refresh/{source}")
public Object refreshAuth(@PathVariable("source") String source, String token){
    AuthRequest authRequest = getAuthRequest(source);
    return authRequest.refresh(AuthToken.builder().refreshToken(token).build());
}

取消授权

注：revoke功能，并不是每个平台都支持

AuthResponse response = authRequest.revoke(AuthToken.builder().accessToken(token).build());

伪代码

/**
 * 
 * @param source 第三方授权平台，以本例为参考，该值为gitee（因为上面声明的AuthGiteeRequest）
 * @param token  login成功后返回的accessToken
 */
@RequestMapping("/revoke/{source}/{token}")
public Object revokeAuth(@PathVariable("source") String source, @PathVariable("token") String token) throws IOException {
    AuthRequest authRequest = getAuthRequest(source);
    return authRequest.revoke(AuthToken.builder().accessToken(token).build());
}

参考文章

• 实现Gitee授权登录
• 实现Github授权登录
• Spring Boot 快速集成第三方登录功能 : QQ、Github、微信、谷歌、微软、小米、企业微信
• 集成企业微信

配套项目

• JustAuth-demo：普通版springboot项目demo
• jFinal版: Jfinal集成JustAuth的demo by xkcoding
• ActFramework版: ActFramework 集成 JustAuth 的 demo by xkcoding
• Nutzboot版: NutzBoot集成JustAuth的demo by 蛋蛋
• Blade版: Blade集成JustAuth的demo

SpringBoot插件

• justauth-spring-boot-starter: Spring Boot 集成 JustAuth 的最佳实践 by xkcoding
• justauth-spring-security-starter: JustAuth整合Spring security的 starter依赖 by luoqiz