GitHub OAuth App 多個 callback URL 怎麼設？一起檢查 wildcard 與 refresh token

這次 OAuth App 多了哪些設定#

GitHub Changelog 把這次更新拆成三個互相獨立的能力。先分開理解，才不會只因為想支援 staging 就順手打開 wildcard 或 token rotation。

GitHub 文件把 OAuth App 的 callback URL 稱為 redirect URL。這和 GitHub App 的 user authorization callback URL 是不同設定，不要只搜尋其中一種文件就當成兩者完全相同。

先依環境登記 callback URL#

在 OAuth App 設定頁使用 Add redirect URI，把真正會接收授權 code 的路徑逐一加進去。例如：

1
https://app.example.com/auth/github/callback
2
https://staging.example.com/auth/github/callback
3
http://127.0.0.1:4321/auth/github/callback

本機桌面或 CLI 工具需要 loopback callback 時，GitHub 文件建議使用 127.0.0.1 或 ::1，而不是把 localhost 當成所有環境共用的替代值。port 可以由程式在授權請求中帶入，但 path 和 host 仍要符合文件規則。

應用程式產生授權網址時，將 callback URI 視為目前部署環境的設定，而不是從使用者輸入直接拼接：

1
const callbackUrl = process.env.GITHUB_OAUTH_CALLBACK_URL;
2

3
if (!callbackUrl) {
4
  throw new Error('GITHUB_OAUTH_CALLBACK_URL is not configured');
5
}
6

7
const authorizeUrl = new URL('https://github.com/login/oauth/authorize');
8
authorizeUrl.search = new URLSearchParams({
9
  client_id: process.env.GITHUB_CLIENT_ID ?? '',
10
  redirect_uri: callbackUrl,
11
  scope: 'read:user user:email offline_access',
12
  state,
13
  code_challenge: codeChallenge,
14
  code_challenge_method: 'S256',
15
}).toString();

state 用來防止 CSRF，PKCE 的 code_challenge 和之後的 code_verifier 則要成對保存。它們不是這次新增功能，但多環境 callback 上線時正好要一起重新驗證；不要因為新增 URI 就省略原本的保護。

wildcard 要先關掉，還是可以直接開？#

當 wildcard matching 關閉時，GitHub 會要求 redirect URL 精確符合已登記的 callback URL。這是比較容易審查的預設邊界：staging 不會因為和 production 共用網域片段，就自動取得另一個路徑的授權 code。

wildcard 適合的情境很窄，例如你確實控制所有 tenant subdomain，而且每個相關 path 都有同樣的路由與權限保護。GitHub 文件提醒，wildcard 會讓 authorization code 被送到 callback URL 底下符合規則的子網域或子路徑；如果那些位置會託管使用者內容，就可能放大 redirect 風險。

還有一個既有 App 的檢查點：GitHub Changelog 說明，只有一個 redirect URI 的 App 可能保留過去的 wildcard 行為；文件也特別指出，2026 年 8 月 3 日以前設定單一 callback 的 App，其 wildcard 可能已經開啟。打開每個 OAuth App 的設定，逐一確認這個開關；不需要時主動關閉，不要把歷史行為當成目前的安全決策。

啟用短效 token 後，換 token 請求怎麼接#

GitHub 的 expiring access token 會在八小時後失效，refresh token 在六個月沒有使用時失效。想逐步導入時，可以在授權請求加入 offline_access，先讓單次登入拿到短效 token 和 refresh token，再觀察現有 SDK 與儲存層是否支援。

換 token 時要注意兩件事：

1. 使用 grant_type=refresh_token，並帶上目前仍有效的 refresh token。
2. GitHub 會回傳新的 access token 與 refresh token；使用過的舊 refresh token 和舊 access token 不會繼續有效，應以一次交易更新整組資料。

伺服器端請求可以長這樣，client_secret 只放在後端，不要送到瀏覽器：

1
curl --fail-with-body --silent --show-error \
2
  --request POST \
3
  --url https://github.com/login/oauth/access_token \
4
  --header 'Accept: application/json' \
5
  --data-urlencode "client_id=$GITHUB_CLIENT_ID" \
6
  --data-urlencode "client_secret=$GITHUB_CLIENT_SECRET" \
7
  --data-urlencode 'grant_type=refresh_token' \
8
  --data-urlencode "refresh_token=$GITHUB_REFRESH_TOKEN"

回應中的 access_token、refresh_token、expires_in 和 refresh_token_expires_in 應一起保存。若多個 request 可能同時發現 access token 過期，先在儲存層做 refresh lock 或版本檢查，避免兩個 request 同時消耗同一個 refresh token。

如果 GitHub 回傳 bad_refresh_token，不要無限重試；文件的處理方式是讓使用者重新走 web application flow 或 device flow，取得新的 token pair。這也表示 refresh token 不是永久登入憑證，資料庫應保留重新授權的狀態。

部署前用同一條流程驗證#

多個 callback URI 上線前，我會用每個環境各跑一次的方式檢查，而不是只在 production 點登入按鈕：

1. 確認目前環境的 GITHUB_OAUTH_CALLBACK_URL 是已登記的 URI，且不是由 query string 或使用者輸入覆寫。
2. 授權請求帶出的 redirect_uri 和 callback 實際收到的 host、path、port 對得上。
3. 換 token 時再次帶入同一個 redirect_uri，並驗證 state 與 PKCE 的 code_verifier。
4. 若啟用 offline_access，測試 access token 到期後只用一次 refresh token 完成輪替。
5. 故意使用未登記的 callback 和關閉 wildcard 的子路徑，確認 GitHub 拒絕它們。
6. Business／Enterprise 環境另外確認管理員政策，避免把 OAuth App 的 callback 問題誤判成組織權限問題。

如果你的整合不只是「讓使用者登入」，還要以 App 身分存取 repository，建議另外比較 GitHub App 的細緻權限模型；可以接著看GitHub Agent Apps 上線前的安裝、權限與審核清單，但不要把 Agent App、GitHub App 和 OAuth App 的設定混在同一張表裡。

這次要記住的事#

多個 callback URI 解決的是環境與部署入口，不是把 redirect 驗證變寬。先用精確 URI 支援 dev、staging 和 production，再視資料流與網域控制能力判斷 wildcard；若啟用短效 token，就把 refresh token 視為會輪替的秘密值，讓重新授權成為明確的失敗路徑。

常見問題#