JustAuth 实战文档 - 基础篇

JustAuth实战文档

JustAuth，如你所见，它仅仅是一个第三方授权登录的工具类库，它可以让我们脱离繁琐的第三方登录SDK，让登录变得So easy! 本专栏将会由浅入深，详细介绍如何使用JustAuth实现第三方登录，以及如何使用JustAuth的高级特性。

🎉 使用SpringBoot初始化项目

在教程正式开始前，我们要先准备好相应的软件环境。JustAuth

在IDEA下使用以下方式创建项目：依次点击 File-New-Project然后选择Spring Initializr，根据提示进行操作，配置依赖时勾选 spring-boot-starter-web和 lombok两个依赖，为了方便开发测试，我这儿多选了一个 spring-boot-devtools。

按照提示创建完成后，得到POM如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.6.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>me.zhyd.justauth</groupId>
    <artifactId>justauth-tutorial</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>justauth-tutorial</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

等待项目编译完成后，我们开始正式集成JustAuth。

➕ 添加JustAuth依赖

正式开始前，建议朋友们先看一下JustAuth的用户文档：https://docs.justauth.whnb.wang， 重点关注快速开始这个章节。

这个章节中包含了关于OAuth和JustAuth相关的重要信息，再次建议优先查看该章节内容。

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

1. 申请注册第三方平台的开发者账号

2. 创建第三方平台的应用，获取配置信息( accessKey, secretKey, redirectUri)

3. 使用该工具实现授权登陆

当然， 第三步和前两步谁先谁后都无所谓，您可以先实现代码再申请第三方应用，也可以先申请第三方应用，再集成代码。

接下来我们按照文档上的第一步指示，先添加pom依赖。

1. <dependency>

2. <groupId>me.zhyd.oauth</groupId>

3. <artifactId>JustAuth</artifactId>

4. <version>1.15.1</version>

5. </dependency>

依赖添加完成后，等待项目编译完成，接下来我们就开始正式接入JustAuth。

➕ 集成JustAuth的API

注意，以下代码中，我们的请求链接中是通过动态参数 {source}去取的，这样可以方便的让我们集成任意平台，比如集成gitee时， 我们的请求地址就是：http://localhost:8080/oauth/render/gitee， 而回调地址就是http://localhost:8080/oauth/callback/gitee。

当然，例子中只是举例告诉大家可以这么用，但如果各位只需要集成单一平台的话， 可以直接将 {souce}改为平台名，如gitee

package me.zhyd.justauth;

import me.zhyd.oauth.config.AuthConfig;
import me.zhyd.oauth.model.AuthCallback;
import me.zhyd.oauth.request.AuthGiteeRequest;
import me.zhyd.oauth.request.AuthRequest;
import me.zhyd.oauth.utils.AuthStateUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

/**
 * 实战演示如何使用JustAuth实现第三方登录
 *
 * @author yadong.zhang (yadong.zhang0415(a)gmail.com)
 * @version 1.0.0
 * @since 1.0.0
 */
@RestController
@RequestMapping("/oauth")
public class JustAuthController {

    /**
     * 获取授权链接并跳转到第三方授权页面
     *
     * @param response response
     * @throws IOException response可能存在的异常
     */
    @RequestMapping("/render/{source}")
    public void renderAuth(HttpServletResponse response) throws IOException {
        AuthRequest authRequest = getAuthRequest();
        String authorizeUrl = authRequest.authorize(AuthStateUtils.createState());
        response.sendRedirect(authorizeUrl);
    }

    /**
     * 用户在确认第三方平台授权（登录）后， 第三方平台会重定向到该地址，并携带code、state等参数
     *
     * @param callback 第三方回调时的入参
     * @return 第三方平台的用户信息
     */
    @RequestMapping("/callback/{source}")
    public Object login(AuthCallback callback) {
        AuthRequest authRequest = getAuthRequest();
        return authRequest.login(callback);
    }

    /**
     * 获取授权Request
     *
     * @return AuthRequest
     */
    private AuthRequest getAuthRequest() {
        return new AuthGiteeRequest(AuthConfig.builder()
                .clientId("clientId")
                .clientSecret("clientSecret")
                .redirectUri("redirectUri")
                .build());
    }

}

接下来我们就需要去gitee上创建我们的OAuth应用。登录gitee后，我们点击右上角用户头像，选择设置，然后点击第三方应用进入第三方应用管理页面，点击右上角的创建应用按钮，进入应用创建页面

我们按照提示填入我们的应用信息即可。

应用名称： 一般填写自己的网站名称即可

应用描述： 一般填写自己的应用描述即可

应用主页： 填写自己的网站首页地址

应用回调地址： 重点，该地址为用户授权后需要跳转到的自己网站的地址，默认携带一个code参数

权限： 根据页面提示操作，默认勾选第一个就行，因为我们只需要获取用户信息即可

以上信息输入完成后，点击确定按钮创建应用。创建完成后，点击进入应用详情页，可以看到应用的密钥等信息

复制以下三个信息：Client ID、Client Secret和应用回调地址。

➕ 自定义HTTP工具

将上一步获取到配置信息配置 AuthConfig中，如下：

private AuthRequest getAuthRequest() {
        return new AuthGiteeRequest(AuthConfig.builder()
                .clientId("4c504cd2e1b1dbaba8dc1187d8070adf679acab17b2bc9cf6dfa76b9ae06aadc")
                .clientSecret("fa5857175723475e4675e36af9eafde338545c1a0dfa49d1e0cc78f9c3ce5ebe")
                .redirectUri("http://localhost:8080/oauth/callback/gitee")
                .build());
    }
}

以上工作完成后，我们直接启动项目，然后在浏览器中访问http://localhost:8080/oauth/render/gitee，当出现以下页面时，表示我们已经集成成功，并且已跳转到了第三方的授权页面。

注意，如果您当前没有在浏览器中登录过您的账号，您将会看到如下页面：

我们点击“同意授权”后，第三方应用（Gitee）将会生成一个code授权码，连带着我们先前传过去的state一并回调到我们配置的redirectUri接口中。

如上图，进入回调接口后，我们可以断点跟踪到第三方平台传回的信息：state和code。

如果您是新项目，这儿可能会出现一个小小的问题：

2020-04-21 23:50:02 http-nio-8080-exec-4 me.zhyd.oauth.log.Log(error:45) [ERROR] - Failed to login with oauth authorization.
com.xkcoding.http.exception.SimpleHttpException: HTTP 实现类未指定！
  at com.xkcoding.http.HttpUtil.checkHttpNotNull(HttpUtil.java:70)
  at com.xkcoding.http.HttpUtil.post(HttpUtil.java:119)
  at me.zhyd.oauth.request.AuthDefaultRequest.doPostAuthorizationCode(AuthDefaultRequest.java:213)
  at me.zhyd.oauth.request.AuthGiteeRequest.getAccessToken(AuthGiteeRequest.java:31)
  at me.zhyd.oauth.request.AuthDefaultRequest.login(AuthDefaultRequest.java:79)
  at me.zhyd.justauth.JustAuthController.login(JustAuthController.java:47)
  at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
  at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
  at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
  at java.lang.reflect.Method.invoke(Method.java:498)
  at org.springframework.web.method.support.InvocableHandlerMethod.doInvoke(InvocableHandlerMethod.java:190)
  at org.springframework.web.method.support.InvocableHandlerMethod.invokeForRequest(InvocableHandlerMethod.java:138)
  at org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod.invokeAndHandle(ServletInvocableHandlerMethod.java:105)
  at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.invokeHandlerMethod(RequestMappingHandlerAdapter.java:879)
  at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.handleInternal(RequestMappingHandlerAdapter.java:793)
  at org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:87)
  at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1040)
  at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:943)
  at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1006)
  at org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:898)
  at javax.servlet.http.HttpServlet.service(HttpServlet.java:634)
  at org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:883)
  at javax.servlet.http.HttpServlet.service(HttpServlet.java:741)
  at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:231)
  at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
  at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:53)
  at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:193)
  at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
  at org.springframework.web.filter.RequestContextFilter.doFilterInternal(RequestContextFilter.java:100)
  at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:119)
  at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:193)
  at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
  at org.springframework.web.filter.FormContentFilter.doFilterInternal(FormContentFilter.java:93)
  at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:119)
  at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:193)
  at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
  at org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(CharacterEncodingFilter.java:201)
  at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:119)
  at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:193)
  at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
  at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:202)
  at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:96)
  at org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:541)
  at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:139)
  at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:92)
  at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:74)
  at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:343)
  at org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:373)
  at org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:65)
  at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:868)
  at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1594)
  at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49)
  at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
  at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
  at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
  at java.lang.Thread.run(Thread.java:748)

这是因为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实现类，JustAuth提供了三种备选的pom依赖：

hutool-http

1. <dependency>

2. <groupId>cn.hutool</groupId>

3. <artifactId>hutool-http</artifactId>

4. <version>5.2.5</version>

5. </dependency>

httpclient

1. <dependency>

2. <groupId>org.apache.httpcomponents</groupId>

3. <artifactId>httpclient</artifactId>

4. <version>4.5.12</version>

5. </dependency>

okhttp

1. <dependency>

2. <groupId>com.squareup.okhttp3</groupId>

3. <artifactId>okhttp</artifactId>

4. <version>4.4.1</version>

5. </dependency>

添加完HTTP工具依赖后，重启项目，重新访问http://localhost:8080/oauth/render/gitee链接，然后进行授权。

授权完成后，您将会看到如下页面：