JustAuth 基本使用

前言

官网地址：https://www.justauth.cn/ (opens new window)

1. 引入依赖

在使用 JustAuth 之前，首先需要在项目中引入依赖。这里以 Maven 为例：

<dependency>
    <groupId>me.zhyd.oauth</groupId>
    <artifactId>JustAuth</artifactId>
    <version>1.15.5</version> <!-- 版本号可以根据需要调整 -->
</dependency>

2. 配置第三方登录平台的必要参数

使用 JustAuth 进行第三方登录，首先需要配置一些关键参数，这些参数是与平台进行通信的必备信息。

• clientId: 平台提供的应用标识（如 GitHub 中的 Client ID）
• clientSecret: 平台提供的应用密钥（如 GitHub 中的 Client Secret）
• redirectUri: 授权成功后的回调地址，必须与平台配置一致
• 其他参数：根据平台不同可能需要额外配置，如微信、支付宝等平台的额外参数

示例代码：

// 1. 构建配置对象，传入必要的参数
AuthConfig config = AuthConfig.builder()
    .clientId("你的Client ID") // 平台提供的应用标识，必填
    .clientSecret("你的Client Secret") // 平台提供的应用密钥，必填
    .redirectUri("你的回调地址") // 授权成功后的回调地址，必填，需与平台配置一致
    .build();

注意：

• clientId 和 clientSecret 是各平台申请应用时获得的，必须正确填写。
• redirectUri 是用户授权后跳转回的地址，必须与在平台申请应用时配置的一致，否则授权会失败。

3. 选择平台并构建 AuthRequest 对象

JustAuth 支持多种第三方平台登录，不同的平台对应不同的 AuthRequest 实现类。比如 GitHub 登录对应 AuthGithubRequest，微信登录对应 AuthWeChatRequest。

示例代码：

// 2. 创建具体的 AuthRequest 对象，选择对应的平台实现类
AuthRequest authRequest = new AuthGithubRequest(config);

4. 获取授权地址并跳转

生成授权地址后，用户可以跳转至该地址进行登录授权。授权地址由 authorize 方法生成。

// 3. 获取授权 URL，用户可以跳转到此地址进行授权登录
String authorizeUrl = authRequest.authorize();
System.out.println("请访问以下地址进行登录授权：" + authorizeUrl);

5. 处理授权回调

用户授权后会回调到你配置的 redirectUri，并附带授权信息（如 code）。你需要在回调接口中使用 JustAuth 获取用户信息。

// 4. 在回调方法中处理授权结果并获取用户信息
AuthResponse<AuthUser> response = authRequest.login(authCallback); // authCallback 是包含回调参数的对象

// 处理登录结果
if (response.ok()) {
    // 登录成功，获取用户信息
    AuthUser user = response.getData();
    System.out.println("登录成功，用户信息：" + user);
} else {
    // 登录失败，输出错误信息
    System.out.println("登录失败，错误信息：" + response.getMsg());
}

6. AuthCallback 参数详解

AuthCallback 是回调时用于封装请求参数的对象，通常包括授权码 code 和状态 state。

重要参数说明：

• code: 授权码，平台通过授权回调返回的参数，用于换取 access_token。
• state: 防止 CSRF 攻击的状态码，建议在授权前生成并校验。

示例代码：

// 示例：创建 AuthCallback 对象
AuthCallback authCallback = AuthCallback.builder()
    .code(request.getParameter("code")) // 授权码，回调时平台会附带
    .state(request.getParameter("state")) // 可选，防止 CSRF
    .build();

7. 重要的 API 和参数说明

1. authorize(): 获取授权 URL，用户可以访问此 URL 进行授权。
2. login(AuthCallback authCallback): 处理授权回调并获取用户信息，返回 AuthResponse 对象。
3. AuthResponse<AuthUser>: 包含授权结果和用户信息。
   • ok(): 判断授权是否成功。
   • getData(): 获取授权成功后的用户信息，包含平台用户 ID、昵称、头像等。
   • getMsg(): 获取授权失败时的错误信息。

8. 完整示例代码

import me.zhyd.oauth.config.AuthConfig;
import me.zhyd.oauth.model.AuthCallback;
import me.zhyd.oauth.model.AuthResponse;
import me.zhyd.oauth.model.AuthUser;
import me.zhyd.oauth.request.AuthGithubRequest;
import me.zhyd.oauth.request.AuthRequest;

public class JustAuthExample {

    public static void main(String[] args) {
        // 1. 配置 GitHub 的 Client ID、Client Secret 和回调地址
        AuthConfig config = AuthConfig.builder()
            .clientId("你的Client ID") // 必填
            .clientSecret("你的Client Secret") // 必填
            .redirectUri("你的回调地址") // 必填
            .build();

        // 2. 创建 AuthRequest 对象，指定 GitHub 平台
        AuthRequest authRequest = new AuthGithubRequest(config);

        // 3. 获取授权 URL，供用户跳转
        String authorizeUrl = authRequest.authorize();
        System.out.println("请访问以下地址进行登录授权：" + authorizeUrl);

        // 模拟回调后的处理流程
        AuthCallback authCallback = AuthCallback.builder()
            .code("模拟的授权码") // 回调中获取的授权码
            .state("模拟的状态码") // 可选
            .build();

        // 4. 处理授权回调并获取用户信息
        AuthResponse<AuthUser> response = authRequest.login(authCallback);

        // 5. 根据授权结果进行后续处理
        if (response.ok()) {
            AuthUser user = response.getData();
            System.out.println("登录成功，用户信息：" + user);
        } else {
            System.out.println("登录失败，错误信息：" + response.getMsg());
        }
    }
}

9. 常见错误排查与解决

• 回调地址不匹配：确保平台配置的回调地址与代码中设置的 redirectUri 一致。
• 授权码无效：授权码是一次性有效的，请确保在获取到后立即使用。