Update SproutGate
This commit is contained in:
196
docs/oauth-providers/github.md
Normal file
196
docs/oauth-providers/github.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 使用 GitHub 登录：OAuth 2.0 接入指南（Golang）
|
||||
|
||||
本文介绍在自有应用中接入 **GitHub 账号** 的通用做法：在 GitHub 注册 OAuth App，使用 **授权码流程** 换取 `access_token`，并调用 GitHub REST API 获取用户信息。与具体业务系统无关。
|
||||
|
||||
## 1. 协议与端点
|
||||
|
||||
GitHub 支持标准 OAuth 2.0。Go 中可直接使用：
|
||||
|
||||
```text
|
||||
import "golang.org/x/oauth2/github"
|
||||
|
||||
Endpoint: github.Endpoint // AuthURL + TokenURL 已内置
|
||||
```
|
||||
|
||||
| 步骤 | URL |
|
||||
|------|-----|
|
||||
| 引导用户授权 | `https://github.com/login/oauth/authorize`（由 `oauth2.Config` 生成） |
|
||||
| 用 `code` 换 token | `https://github.com/login/oauth/access_token`（`Exchange` 自动 POST） |
|
||||
| 读当前用户（示例） | `GET https://api.github.com/user`（`Authorization: Bearer {token}`） |
|
||||
| 主邮箱（若 user 里无 email） | `GET https://api.github.com/user/emails` |
|
||||
|
||||
常用 **Scope**：`read:user`、`user:email`（需要邮箱时建议带 `user:email`）。
|
||||
|
||||
官方文档：[Authorizing OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)
|
||||
|
||||
## 2. 在 GitHub 注册应用
|
||||
|
||||
1. 个人：`Settings` → `Developer settings` → `OAuth Apps` → `New OAuth App`。
|
||||
2. **Authorization callback URL** 填你**真实**的回调地址，例如：
|
||||
`http://localhost:8080/oauth/github/callback`（开发）
|
||||
`https://你的域名/oauth/github/callback`（生产）
|
||||
3. 保存 **Client ID** 与 **Client secrets**（机密只显示一次，可轮换）。
|
||||
|
||||
## 3. `redirect_uri` 与换 token
|
||||
|
||||
- 授权请求中的 `redirect_uri` 与在 GitHub 登记的 **必须完全一致**。
|
||||
- 用 `code` 换 token 时，客户端库会带上**同一** `redirect_uri`，否则换 token 失败。
|
||||
|
||||
## 4. Golang 最小示例（授权码 + 拉取用户）
|
||||
|
||||
依赖：`go get golang.org/x/oauth2`，并安装子包引用 `github.Endpoint`（同一 module）。
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"crypto/rand"
|
||||
"encoding/base64"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"log"
|
||||
"net/http"
|
||||
"os"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"golang.org/x/oauth2"
|
||||
"golang.org/x/oauth2/github"
|
||||
)
|
||||
|
||||
func main() {
|
||||
redirectURL := getenv("OAUTH_REDIRECT_URL", "http://127.0.0.1:8080/oauth/github/callback")
|
||||
cfg := &oauth2.Config{
|
||||
ClientID: os.Getenv("GITHUB_CLIENT_ID"),
|
||||
ClientSecret: os.Getenv("GITHUB_CLIENT_SECRET"),
|
||||
RedirectURL: redirectURL,
|
||||
Scopes: []string{"read:user", "user:email"},
|
||||
Endpoint: github.Endpoint,
|
||||
}
|
||||
if cfg.ClientID == "" || cfg.ClientSecret == "" {
|
||||
log.Fatal("set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET")
|
||||
}
|
||||
|
||||
states := newStateStore()
|
||||
|
||||
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
|
||||
b := make([]byte, 16)
|
||||
_, _ = rand.Read(b)
|
||||
state := base64.RawURLEncoding.EncodeToString(b)
|
||||
states.Put(state, time.Now().Add(10*time.Minute))
|
||||
url := cfg.AuthCodeURL(state, oauth2.AccessTypeOnline)
|
||||
http.Redirect(w, r, url, http.StatusFound)
|
||||
})
|
||||
|
||||
http.HandleFunc("/oauth/github/callback", func(w http.ResponseWriter, r *http.Request) {
|
||||
if err := r.URL.Query().Get("error"); err != "" {
|
||||
http.Error(w, r.URL.Query().Get("error_description"), http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
state := r.URL.Query().Get("state")
|
||||
code := r.URL.Query().Get("code")
|
||||
if !states.Consume(state) {
|
||||
http.Error(w, "invalid state", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
ctx := r.Context()
|
||||
tok, err := cfg.Exchange(ctx, code)
|
||||
if err != nil {
|
||||
http.Error(w, "token exchange: "+err.Error(), http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
u, err := fetchGitHubUser(ctx, tok.AccessToken)
|
||||
if err != nil {
|
||||
http.Error(w, err.Error(), http.StatusBadGateway)
|
||||
return
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
||||
_ = json.NewEncoder(w).Encode(u)
|
||||
})
|
||||
|
||||
log.Println("open http://127.0.0.1:8080/ (callback must match GitHub app:", redirectURL+")")
|
||||
log.Fatal(http.ListenAndServe(":8080", nil))
|
||||
}
|
||||
|
||||
type ghUser struct {
|
||||
ID int64 `json:"id"`
|
||||
Login string `json:"login"`
|
||||
Name string `json:"name"`
|
||||
AvatarURL string `json:"avatar_url"`
|
||||
}
|
||||
|
||||
func fetchGitHubUser(ctx context.Context, access string) (*ghUser, error) {
|
||||
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/user", nil)
|
||||
req.Header.Set("Authorization", "Bearer "+access)
|
||||
req.Header.Set("Accept", "application/vnd.github+json")
|
||||
req.Header.Set("User-Agent", "oauth-demo")
|
||||
res, err := http.DefaultClient.Do(req)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer res.Body.Close()
|
||||
b, _ := io.ReadAll(res.Body)
|
||||
if res.StatusCode != http.StatusOK {
|
||||
return nil, fmt.Errorf("github user: %d %s", res.StatusCode, b)
|
||||
}
|
||||
var u ghUser
|
||||
if err := json.Unmarshal(b, &u); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &u, nil
|
||||
}
|
||||
|
||||
type stateStore struct {
|
||||
mu sync.Mutex
|
||||
m map[string]time.Time
|
||||
}
|
||||
|
||||
func newStateStore() *stateStore {
|
||||
return &stateStore{m: make(map[string]time.Time)}
|
||||
}
|
||||
|
||||
func (s *stateStore) Put(key string, exp time.Time) {
|
||||
s.mu.Lock()
|
||||
s.m[key] = exp
|
||||
s.mu.Unlock()
|
||||
}
|
||||
|
||||
func (s *stateStore) Consume(key string) bool {
|
||||
s.mu.Lock()
|
||||
defer s.mu.Unlock()
|
||||
t, ok := s.m[key]
|
||||
if !ok || time.Now().After(t) {
|
||||
return false
|
||||
}
|
||||
delete(s.m, key)
|
||||
return true
|
||||
}
|
||||
|
||||
func getenv(k, def string) string {
|
||||
if v := os.Getenv(k); v != "" {
|
||||
return v
|
||||
}
|
||||
return def
|
||||
}
|
||||
```
|
||||
|
||||
**运行前**：
|
||||
|
||||
- 在 GitHub OAuth App 的回调里填写与 `OAUTH_REDIRECT_URL` **完全一致**的 URL（未设置时默认 `http://127.0.0.1:8080/oauth/github/callback`）。
|
||||
- `export GITHUB_CLIENT_ID=...` 与 `GITHUB_CLIENT_SECRET=...`
|
||||
|
||||
## 5. 常见错误
|
||||
|
||||
| 现象 | 原因 |
|
||||
|------|------|
|
||||
| `redirect_uri` 与登记不符 | 修改了端口、`localhost` vs `127.0.0.1` 或 `http`/`https` 不一致 |
|
||||
| 换 token 失败 | 同上；或 `Client Secret` 错误 |
|
||||
| 用户 email 为空 | 邮箱可能未公开，需调 `user/emails` 并带 `user:email` scope |
|
||||
|
||||
## 6. 安全建议
|
||||
|
||||
- `state` 应随机且**一次性**；生产可用加签或服务端 Session。
|
||||
- `Client Secret` 仅放服务端；勿写入前端。
|
||||
- 对 GitHub 用户 ID（数字 id）做账号绑定主键，勿仅用 login（可改名）。
|
||||
Reference in New Issue
Block a user