nCalendar 第三方登录集成：GitHub 篇（Dex）

青萍叙事2025-06-04

🧭 背景介绍

nCalendar 是一个集成 Notion 模板、日历与本地提醒的自动化时间管理工具。

现已以 SaaS 模式提供使用。

为提升用户体验并支持统一认证体系，我们选择通过 Dex 实现 OAuth 登录，使用 Dex 集中处理所有身份接入。

Dex 是一款开源的 OIDC 身份提供平台，可对接 GitHub、Google 等多个身份源，nCalendar 则作为 OIDC 客户端，通过 Dex 实现 OAuth 登录接入。

💡 使用场景

希望通过 Dex 提供统一登录入口（SSO）；
需要简化账号管理、增强安全性并提升登录一致性。
nCalendar 不直接处理 GitHub 登录，而是通过 Dex 做认证中介。

✅ 实现目标

1、用户在登录页面，可点击 使用Github登录

2、点击 使用Github登录，跳转至 Github 认证授权页面（若用户已在Github登录则直接进入nCalendar 管理页面）

3、用户在 Github 登录页面输入 Github 的账号密码认证

4、用户认证通过后进入 nCalendar 管理页面

5、若用户账户在 nCalendar 中未注册则使用 Github 用户名和邮箱自动注册

🖼️ Github 登录流程图

⚙️ 集成步骤

1️⃣ 在 GitHub 创建 OAuth App

首先需要有一个 Github 账号，再点击右上角头像 Settings → GitHub Developer Settings → OAuth Apps → New OAuth App，截图如下：

应用名称、应用主页和应用描述，根据你的实际情况输入。

授权回调地址比较关键，我这里因为是统一使用的 Dex 做认证，所以直接写 Dex 的/callback

生成 Client secrets，上传应用 logo

最后点击保存更新配置即可。

2️⃣ 配置 Dex 对接 GitHub

在 Dex 的配置文件 config.yaml 中添加 GitHub Connector：

connectors:
  - type: github
    id: github
    name: GitHub
    config:
      clientID: YOUR_GITHUB_CLIENT_ID
      clientSecret: YOUR_GITHUB_CLIENT_SECRET
      redirectURI: https://your-dex-domain.com/callback

这里的clientID、clientSecret和redirectURI，需要跟上面Github中的保持一致。

3️⃣ 配置 nCalendar 作为 Dex 的 OAuth 客户端

在 Dex 中添加一个静态客户端用于 nCalendar 的 Github 登录：

staticClients:
  - id: ncalendar-github
    redirectURIs:
      - "https://ncalendar.lusyoe.com/ncalendar/oauth/callback"
      - "https://auth.lusyoe.com/callback"
      - "https://auth.lusyoe.com/auth/github"
    name: "ncalendar-github"
    secret: YOUR_CLIENT_SECRET

这一步的目的就是为了使用 Github 登录成功后可以跳转回 nCalendar。

4️⃣ 登录完成后，nCalendar 获取用户信息

Dex 回调 https://ncalendar.lusyoe.com/ncalendar/oauth/callback

正常来说 nCalendar 再通过 OIDC 流程获取用户信息：

POST /token
  - grant_type=authorization_code
  - code=abc123
  - redirect_uri=https://ncalendar.app/auth/callback
  - client_id=ncalendar
  - client_secret=YOUR_CLIENT_SECRET

但是我这边已经在Dex 服务端做了全域 cookie，没必要再去获取了。

参考上面的流程图，直接就是携带 cookie 到后端去验证并解析 token 获取用户信息。

nCalendar 将使用 cookie id_token 中的信息建立用户会话（自身的token）并显示头像、昵称等。