格姗导航接入第三方登录 - github 图文教程！

原创

格姗知识圈

发布于 2026-08-18 23:20:41

540

文章被收录于专栏：格姗知识圈格姗知识圈

格姗导航 - 第三方登录 GitHub 接入说明

1. 申请应用

1.注册 GitHub 账号

2.创建第三方应用

进入通过右上角进入个人设置页：https://github.com/settings/profile，然后进入开发者设置页面：https://github.com/settings/developers。

在应用管理页面，选择 OAuth App，然后点击右上方的 New OAuth App 按钮进入新建应用页面。

创建应用：

Application name 一般填写自己的网站名称即可
Application description 一般填写自己的应用描述即可
Homepage URL 填写自己的网站首页地址
Authorization callback URL 重点，该地址为用户授权后需要跳转到的自己网站的地址，默认携带一个code参数

以上信息输入完成后，点击下方绿色的 Register application 按钮创建应用。创建完成后，点击进入应用详情页，可以看到应用的密钥等信息。

记录以下三个信息：Client ID、Client Secret和Authorization callback URL，后面我们会用到。

重要提示
"应用密钥"可保护你应用程序的安全，因此请确保其不会泄露！也不要与任何人共享你的"应用密钥"！！！

2. 网站配置

申请通过后，登录后台管理，进入系统导航配置-登录配置，编辑 GitHub，填写对应的值即可。这时就能通过 GitHub 进行登录。

数据已内置 GitHub 配置，只需管理后台填写对应的 GitHub 信息即可。

3. 项目依赖

如果不用了解技术，下面内容可以直接跳过。

本项目使用 JustAuth 作为第三方登录统一解决方案。

3.1 根 POM 依赖声明

文件位置：pom.xml

<!-- JustAuth 版本定义 -->
<just.auth.version>1.16.5</just.auth.version>

<!-- JustAuth 第三方登录模块 -->
<dependency>
    <groupId>me.zhyd.oauth</groupId>
    <artifactId>JustAuth</artifactId>
    <version>${just.auth.version}</version>
</dependency>

3.2 application 模块引入依赖

文件位置：geshanzsq-nav-admin/geshanzsq-nav-admin-application/pom.xml

<!-- JustAuth 第三方登录模块 -->
<dependency>
    <groupId>me.zhyd.oauth</groupId>
    <artifactId>JustAuth</artifactId>
</dependency>

4. 数据库配置

4.1 第三方登录配置表

表名：sys_third_login_config，用于存储各平台（QQ、Gitee、GitHub 等）的登录配置信息。

CREATE TABLE `sys_third_login_config` (
  `id`          bigint(20)   NOT NULL COMMENT '配置 id',
  `login_icon`  varchar(30)  DEFAULT NULL COMMENT '登录图标',
  `source`      varchar(255) DEFAULT ''  COMMENT '登录来源',
  `client_id`   varchar(255) DEFAULT ''  COMMENT '登录 id（Client ID）',
  `client_secret` varchar(255) DEFAULT ''  COMMENT '登录密钥（Client Secret）',
  `sort`        int(11)      DEFAULT NULL COMMENT '排序',
  `status`      int(11)      DEFAULT NULL COMMENT '状态（1 正常，2 停用）',
  `fk_create_user_id` bigint(20) DEFAULT NULL COMMENT '创建人用户 id',
  `gmt_create`  datetime     DEFAULT NULL COMMENT '创建时间',
  `fk_modify_user_id` bigint(20) DEFAULT NULL COMMENT '修改人用户 id',
  `gmt_modify`  datetime     DEFAULT NULL COMMENT '修改时间',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统三方登录配置';

4.2 第三方用户表

表名：sys_third_user，用于存储第三方登录用户的关联信息。

CREATE TABLE `sys_third_user` (
  `id`          bigint(20)   NOT NULL COMMENT '系统第三方用户 id',
  `fk_user_id`  bigint(20)   DEFAULT NULL COMMENT '用户 id',
  `uuid`        varchar(255) DEFAULT NULL COMMENT '平台 uuid',
  `gmt_create`  datetime     DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `source`      varchar(20)  DEFAULT NULL COMMENT '来源',
  `username`    varchar(255) DEFAULT NULL COMMENT '第三方用户名',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='系统第三方用户';

4.3 插入 GitHub 登录配置

数据已内置 GitHub 配置，只需管理后台填写对应的 GitHub 信息即可。如没有，可将申请到的 Client ID 和 Client Secret 填入以下 SQL：

INSERT INTO `sys_third_login_config`
(`id`, `login_icon`, `source`, `client_id`, `client_secret`, `sort`, `status`, `fk_create_user_id`, `gmt_create`, `fk_modify_user_id`, `gmt_modify`)
VALUES
(78261101506068480, 'github', 'Github', '你的Client ID', '你的Client Secret', 1, 3, 1, NOW(), 1, NOW());

说明：source 字段填写 Github（对应枚举 SysThirdLoginConfigSource.GITHUB.code = "github"） login_icon 填写 github，对应前端 SVG 图标 status 设为 1 表示启用

5. 后端配置

5.1 通用配置

文件位置：geshanzsq-nav-admin/geshanzsq-nav-admin-application/src/main/resources/application.yml

# 第三方登录
third-login:
  # 错误地址（登录失败跳转页面）
  error-url: /500
  # 登录页面地址（携带 ticket 参数，前端凭 ticket 换取 token）
  login-url: /login?ticket=

5.2 开发环境配置

文件位置：application-dev.yml

third-login:
  # 前端网站地址
  site-url: http://localhost:8023
  # 登录回调地址（会拼接 source 参数，如 /geshanzsq-nav-api/auth/third/login/callback/github）
  callback-url: /geshanzsq-nav-api/auth/third/login/callback/

5.3 生产环境配置

文件位置：application-prod.yml

third-login:
  site-url: https://gesdh.cn
  callback-url: /geshanzsq-nav-api/auth/third/login/callback/

5.4 安全放行配置

在 application.yml 中，需将第三方登录接口加入免登录放行列表：

security:
  not-login-urls:
    - /auth/third/login/**
    - /system/third/login/list

6. 后端核心代码说明

6.1 枚举：登录来源

文件：SysThirdLoginConfigSource.java

public enum SysThirdLoginConfigSource {
    QQ("qq"),
    GITEE("gitee"),
    GITHUB("github"),
    WE_CHAT("weChat");

    public final String code;

    SysThirdLoginConfigSource(String code) {
        this.code = code;
    }
}

6.2 配置属性类

文件：ThirdLoginProperty.java

@Data
@Configuration
@ConfigurationProperties(prefix = "third-login")
public class ThirdLoginProperty {
    private String siteUrl;      // 网站地址
    private String callbackUrl;  // 登录回调地址
    private String errorUrl;     // 错误地址
    private String loginUrl;     // 登录页面地址
}

6.3 第三方登录控制器

文件：ThirdLoginController.java

@RestController
@RequestMapping("/auth/third/login")
public class ThirdLoginController extends BaseController {

    // 获取第三方登录授权地址
    @GetMapping("/getLoginUrl/{source}")
    public ResponseResult<LoginUrlVO> getLoginUrl(@PathVariable String source) {
        LoginUrlVO loginUrlVO = authService.getLoginUrl(source);
        return ResponseResult.success(loginUrlVO);
    }

    // 第三方登录回调
    @GetMapping("/callback/{source}")
    public void callback(@PathVariable String source,
                         AuthCallback authCallback,
                         HttpServletResponse response) throws IOException {
        authService.callback(source, authCallback, response);
    }
}

6.4 GitHub 登录请求构建（核心）

文件：ThirdLoginServiceImpl.java

GitHub 登录的核心逻辑：

// 构建 GitHub 登录请求
if (SysThirdLoginConfigSource.GITHUB.code.equals(source)) {
    authRequest = new AuthGithubRequest(AuthConfig.builder()
            .clientId(clientId)          // Client ID
            .clientSecret(clientSecret)  // Client Secret
            .redirectUri(callbackUrl)    // 回调地址
            .build());
}

完整回调处理流程：

// 1. 生成授权 URL（前端调用）
public LoginUrlVO getLoginUrl(String source) {
    String callbackUrl = thirdLoginProperty.getSiteUrl()
                       + thirdLoginProperty.getCallbackUrl()
                       + source.toLowerCase();
    AuthRequest authRequest = getAuthRequest(source, callbackUrl);
    String authorizeUrl = authRequest.authorize(AuthStateUtils.createState());
    return new LoginUrlVO(authorizeUrl);
}

// 2. 回调处理（GitHub 重定向后调用）
public void callback(String source, AuthCallback authCallback,
                     HttpServletResponse response) throws IOException {
    AuthRequest authRequest = getAuthRequest(source, callbackUrl);
    AuthResponse authResponse = authRequest.login(authCallback);

    // 判断是否成功（JustAuth 成功码为 2000）
    if (authResponse.getCode() != 2000) {
        response.sendRedirect(siteUrl + errorUrl);
        return;
    }

    // 解析用户信息
    TicketAuth ticketAuth = JSONObject.parseObject(
            JSONObject.toJSONString(authResponse.getData()), TicketAuth.class);

    // 生成临时票据（Redis 缓存 60 秒）
    String ticket = ticketAuthService.createTicket(ticketAuth);

    // 重定向到前端登录页，携带 ticket
    String redirectUrl = StrUtils.format("{}{}{}",
            siteUrl, loginUrl, ticket);
    response.sendRedirect(redirectUrl);
}

6.5 票据服务（TicketAuth）

文件：TicketAuthServiceImpl.java

// 创建票据，存入 Redis，有效期 60 秒
public String createTicket(TicketAuth ticketAuth) {
    String ticket = IdUtils.simpleUUID();
    redisService.set(getTicketCacheKey(ticket), ticketAuth, 60, TimeUnit.SECONDS);
    return ticket;
}

7. 前端代码说明

7.1 API 接口

文件：vue-geshanzsq-nav/src/api/auth/login.js

// 获取登录授权地址
export function getLoginUrl(source) {
  return request({
    url: `/auth/third/login/getLoginUrl/${source}`,
    method: 'get'
  })
}

// 票据登录（前端凭 ticket 换取正式 token）
export function ticketLogin(data) {
  return request({
    url: '/ticket/login',
    method: 'post',
    data
  })
}

文件：vue-geshanzsq-nav/src/api/system/third/login.js

// 获取可用的第三方登录配置列表（公开接口）
export function list() {
  return request({
    url: '/system/third/login/list',
    method: 'get'
  })
}

7.2 后台登录页面

文件：vue-geshanzsq-nav/src/views/login/index.vue

页面加载时调用 list() 接口获取已启用的第三方登录配置
展示「第三方账号登录」区域，遍历 loginConfigList 显示各平台图标
点击 GitHub 图标调用 handleTypeLogin('Github')：

async function handleTypeLogin(source) {
  if (redirect.value) {
    setLoginRedirectPath(redirect.value)
  }
  const { data: { url } } = await getLoginUrl(source)
  window.location.href = url  // 跳转到 GitHub 授权页面
}

用户授权后 GitHub 回调到后端，后端重定向到 /login?ticket=xxx
前端检测到 ticket 参数后自动调用 ticketLogin({ ticket }) 换取 token

function init() {
  const ticket = router.currentRoute.value.query.ticket
  if (ticket) {
    doTicketLogin(ticket)
    return
  }
  initNotLogin()
}

async function doTicketLogin(ticket) {
  const { data } = await ticketLogin({ ticket })
  setToken(data.token)
  store.dispatch('user/setToken', data.token)
  router.push(getLoginRedirectPath() || redirect.value || '/me')
  removeLoginRedirectPath()
}

7.3 前台客户端登录弹窗

文件：vue-geshanzsq-nav/src/layout/client/components/Login/index.vue

前台页面同样支持第三方登录，流程与后台登录一致。

8. 完整登录流程图

┌─────────┐   ①点击GitHub登录   ┌──────────┐   ②GET /auth/third/login/getLoginUrl/Github  ┌──────────┐
│  前端    │ ────────────────→ │  前端    │ ─────────────────────────────────────────────→ │  后端    │
│ (登录页) │                   │ (跳转)   │                                               │ (Java)   │
└─────────┘                   └──────────┘                                               └──────────┘
                                    │                                                         │
                                    │ ③window.location.href = authorizeUrl                    │ ④构建 AuthGithubRequest
                                    ↓                                                         │ 返回 GitHub 授权 URL
                              ┌────────────┐                                                 │
                              │ GitHub授权页 │                                                 │
                              └────────────┘                                                 │
                                    │                                                         │
                                    │ ⑤用户同意授权                                           │
                                    ↓                                                         │
                              ┌──────────┐   ⑥GET /auth/third/login/callback/github           │
                              │  后端    │ ←── GitHub 回调携带 code ─────────────────────────── │
                              │ (回调)   │                                                    │
                              └──────────┘                                                    │
                                    │                                                         │
                                    │ ⑦ authRequest.login(callback) 获取用户信息              │
                                    │ ⑧ 生成 ticket 存入 Redis（60s）                         │
                                    │ ⑨ response.sendRedirect(/login?ticket=xxx)              │
                                    ↓                                                         │
                              ┌──────────┐   ⑩ POST /ticket/login { ticket }                  │
                              │  前端    │ ─────────────────────────────────────────────────→ │
                              │ (登录页) │ ←── 返回 token ──────────────────────────────────  │
                              └──────────┘                                                    │
                                    │                                                         │
                                    │ ⑪ setToken + 跳转到目标页                               │
                                    ↓                                                         │
                              ┌──────────┐
                              │  目标页面  │
                              └──────────┘

9. GitHub 平台回调地址配置

在 GitHub OAuth App 设置页面，Authorization callback URL 需配置为：

开发环境：

http://localhost:8023/geshanzsq-nav-api/auth/third/login/callback/github

生产环境：

https://gesdh.cn/geshanzsq-nav-api/auth/third/login/callback/github

注意：回调地址格式为 {siteUrl}{callbackUrl}{source}，其中：siteUrl：网站地址（如 http://localhost:8023） callbackUrl：配置的回调路径（如 /geshanzsq-nav-api/auth/third/login/callback/） source：登录来源（GitHub 为 github，注意小写）

10. 常见问题

10.1 回调地址不匹配

确保 GitHub OAuth App 后台配置的 Authorization callback URL 与项目中的回调地址完全一致，包括协议（http/https）、域名和路径。

10.2 clientId 或 clientSecret 配置错误

请确认数据库中 sys_third_login_config 表的 client_id 和 client_secret 与 GitHub 申请的 Client ID 和 Client Secret 一致。

10.3 状态未启用

确保 sys_third_login_config 表中 status 字段值为 1（正常），否则后端会返回「当前登录方式不支持」。

10.4 ticket 过期

票据（ticket）有效期为 60 秒，如果用户从 GitHub 回调后长时间未跳转到登录页，ticket 可能已过期，需重新发起登录。

10.5 前端回调后未自动登录

检查浏览器地址栏是否包含 ?ticket= 参数，前端 init() 方法会自动检测并调用票据登录接口。确保 /ticket/login 接口在安全放行列表中。

11. 管理后台操作

登录系统后台后，进入 系统管理 → 第三方登录配置 页面，可以进行以下操作：

新增配置：添加 GitHub 或其他平台的登录配置
编辑配置：修改 Client ID、Client Secret 等信息
停用/启用：控制该登录方式是否对外展示
排序：调整各登录方式的展示顺序

12. 参考文档

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

oauth2.0

github