上一篇讲了 OAuth 登录的通用流程，这一篇我们用 GitHub 登录做一次完整配置。

GitHub 登录非常适合面向开发者、独立开发者、开源使用者和技术团队的 SaaS 产品。它可以显著降低注册成本，并方便你获取使用者的开发者身份信息。

使用者痛点：在实际接入时很多团队会因为 OAuth App 创建细节、callback URL 配置错误、Client Secret 泄露或 scope 申请过多而导致登录失败、使用者流失或安全隐患。

说到第一步先，创建 GitHub OAuth App

1. 登录 GitHub。点击右上角头像 → Settings。

2. 在左侧菜单找到 Developer settings → OAuth apps接下来点击 New OAuth App。

必填字段：

Application name：你的产品名称
Homepage URL：你的产品首页地址
Application description：可选。写给使用者看的说明
Authorization callback URL：你的 OAuth 回调地址

使用者痛点：填写内部测试方法或敏感信息会在授权页面暴露，导致信任度下降甚至被使用者拒绝授权。怎么说呢，

说到接下来。配置 Callback URL

Callback URL 是 GitHub 授权完成后跳回你程序的地址。

开发环境：http://localhost:3000/api/auth/callback/github
生产环境这方面。https://example.com/api/auth/callback/github

使用者痛点：GitHub OAuth App 只能配置单一 Callback URL，若开发、测试、生产共用同一个 App 且 URL 不匹配，会直接报错“redirect_uri mismatch”。

方法：

• 方案一：为不同环境分别创建独立的 OAuth App。
• 方案二：使用统一域名并在服务器层实现中转，但实现复杂且不易维护。

：保存 Client ID 与 Client Secret

Create 完成后GitHub 会提供：

• Client ID: 用于生成授权链接，可公开。
• Client Secret: 只能放在服务端，用于 code 换 token。

GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx
GITHUB_CALLBACK_URL=https://example.com/api/auth/callback/github

使用者痛点：If you accidentally commit .env/.gitignore-ignored files containing secret,secret is exposed and attackers can impersonate your app.

第四步的观点是。生成 GitHub 授权链接

User clicks “使用 GitHub 登录” 时需要将其重定向到以下地址：

https://github.com/login/oauth/authorize

client_id = YOUR_CLIENT_ID
redirect_uri= https://example.com/api/auth/callback/github
scope = read:user user:email
state = RANDOM_STRING // 防 CSRF

https://github.com/login/oauth/authorize?说起来，client_id=YOUR_CLIENT_ID&redirect_uri=https://example.com/api/auth/callback/github&scope=read:user%20user:email&state=RANDOM_STATE

User Pain Point:The generated state** parameter is often omitted or not stored server‑side。leading to CSRF attacks or login failures when callback’s state doesn’t match.

第五步这方面，合理申请 Scope

• read:user: 读取基本资料。
• User:email: 读取已验证邮箱列表。

User Pain Point:If you request overly broad scopes such as repo,users will see a scary permission list。hesitate to authorize,and may abandon registration flow.

第六步这方面，处理 GitHub 回调

User 同意授权后GitHub 会跳回你的 Callback URL，并附带 ?code=xxx&state=yyy.

https://example.com/api/auth/callback/github?其实，code=abc123&state=xyz789

• #1 校验 state:If mismatch → 拒绝请求并记录日志。
• #2 用 code 换取 Access Token：

  POST https://github.com/login/oauth/access_token
  Headers: Accept: application/json
  Body :
  client_id=YOUR_CLIENT_ID&
  client_secret=YOUR_CLIENT_SECRET&
  code=CODE_FROM_CALLBACK&
  redirect_uri=YOUR_CALLBACK_URL
  

User Pain Point:If you forget to set `Accept: application/json`。GitHub returns a query‑string format which is easy to parse incorrectly,causing token extraction failures.

第七步这方面，获取 GitHub 使用者信息与邮箱

1. SEND GET https://api.github.com/user with header `Authorization: Bearer ACCESS_TOKEN` → 返回 `id`,`login`,`avatar_url`,`html_url` 等基础信息。其实，
2. SEND GET https://api.github.com/user/emails with same Authorization header → 返回邮箱数组。每条包括 `email`,`primary`,`verified`。

If primary email is hidden,you must iterate through list and pick a verified primary email.

User Pain Point:The email field on `/user` may be empty;其实，ignoring `/user/emails` leads to missing login email and forced account creation failures.

从第八步来看。绑定本地账号

provider_email primary verified email } provider_avatar_url avatar_url } created_at td>绑定时间 /t} updated_at td>最近一次登录时间

绑定要素
provider_user_id	GitHub 返回的唯一 ID
provider_login	login

• If provider_user_id 已存在 → 登录对应本地账号。
• If 不存在 → 根据业务决定是 自动创建新账号 还是 提示绑定已有邮箱账号。

User Pain Point:Merging accounts solely by email can cause security issues when two different users share an email . Always prioritize provideruserid as primary key.

第九步的观点是。创建本地 Session / Token

• Your system generates its own session cookie/JWT after successful GitHub auntication.
• You **不要**直接把 GitHub Access Token 当作登录态返回前端，除非有后续调用需求。老实说，
• If you need long‑term access to repositories later,securely store encrypted token in DB with expiration & revocation logic.
`

User Pain Point:* Storing raw tokens in plaintext DB leads to credential leaks if DB is compromised.*

第十步这方面。常见错误检查清单

• 🔴Callback URL 不匹配： 确保每个环境的 OAuth App 中的 Callback 与代码里的一致。
\
• 🔴Secret 泄露： 只在服务端读取环境变量，不写入前端代码或公共仓库。泄露后立即重新生成，
\
• 🔴State 未校验或失效： 每次发起授权前生成随机字符串并保存在 session/cache 中，回调时比对。话说回来，
\
• 🔴Scope 不足导致邮箱为空： 确保申请了 user:email 并在回调时处理邮箱列表为空的情况。
\
• 🔴使用 Provider User ID 错误绑定： 始终以 provider_user_id 为唯一键进行查询/创建，而不是仅凭邮箱或使用者名。
\
• 🔴未生成本地 Session： 登录成功后一定要创建自己的会话，否则前端无法维持登录状态。
\ <\/ul\

---