如何使用

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

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

# 使用步骤

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

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

# 使用方式

引入依赖

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

1
2
3
4
5

获取最新版本：JustAuth (opens new window)

调用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);

1
2
3
4
5
6
7
8
9
10
11

注意

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

hutool-http 点击查看代码

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

1
2
3
4
5

httpclient 点击查看代码

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

1
2
3
4
5

okhttp 点击查看代码

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

1
2
3
4
5

# 使用国外平台

由于 Q 的限制，在使用国外平台时，需要额外配置 httpConfig，如下：

AuthRequest authRequest = new AuthGoogleRequest(AuthConfig.builder()
                .clientId("Client ID")
                .clientSecret("Client Secret")
                .redirectUri("应用回调地址")
                // 针对国外平台配置代理
                .httpConfig(HttpConfig.builder()
                        // Http 请求超时时间
                        .timeout(15000)
                        // host 和 port 请修改为开发环境的参数
                        .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 10080)))
                        .build())
                .build());

1
2
3
4
5
6
7
8
9
10
11
12

注意

使用代理时，必须开启全局代理！ 开启全局代理！ 开启全局代理！，不能只开启浏览器代理。

# HttpConfig 配置说明

timeout: http 请求超时时间
proxy
- host: 本地一般为127.0.0.1，如果部署到服务器，可以配置为公网 IP
- port: 需要根据使用的唯皮嗯软件修改，以我本地使用的某款工具为例，查看代理端口：

再比如以下参考：

本地如果支持科学上网，就用自己本地的代理端口即可，如果不支持科学上网，可以去网上找一些免费的代理IP进行测试（请自行操作）。

友情提示，经测试，需要单独配置 httpConfig 的平台有：

Github
Google
Facebook
Pinterest
Twitter
其他待补充

# API分解

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

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

1
2
3
4
5
6

# 获取授权链接

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);
}

1
2
3
4
5
6
7
8
9
10

注：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;
}

1
2
3
4
5
6
7
8
9
10

注：第三方平台中配置的授权回调地址，以本文为例，在创建授权应用时的回调地址应为：[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());
}

1
2
3
4
5
6
7
8
9
10

# 取消授权

注：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());
}