跳至主要內容

設定 GitHub App 社交登入

整合 GitHub App 以啟用「使用 GitHub 登入」、帳號連結，以及以細緻權限和重新整理權杖 (Refresh tokens) 安全存取 GitHub API。

提示:

本指南假設你已對 Logto 連接器 (Connectors) 有基本了解。若不熟悉，請參閱 連接器 (Connectors) 指南以開始使用。

GitHub App 與 OAuth App 比較​

GitHub 提供兩種應用程式類型用於驗證 (Authentication) 與 API 存取：GitHub Apps 和 OAuth Apps。以下比較協助你選擇：

功能GitHub AppOAuth App
權限 (Permissions)細緻權限 — 僅請求特定資源存取權廣泛權限範圍 — 通常給予超出需求的存取權
權限管理僅能在 GitHub 控制台設定；Logto 的 Scope 欄位可留空透過 Logto 連接器中的權限範圍 (Scopes) 設定
重新整理權杖 (Refresh tokens)OAuth 流程中一律發放不支援 — 權杖除非撤銷否則永不過期
權杖過期時間存取權杖 (Access tokens) 8 小時後過期；重新整理權杖有效 6 個月存取權杖永不過期
使用者控制使用者可選擇 App 可存取哪些儲存庫可存取使用者有權限的所有儲存庫
速率限制安裝數量越多速率限制越高速率限制較低（每使用者每小時 5,000 次請求）
安裝方式安裝於帳號／組織，並可細緻設定儲存庫存取權由使用者授權，存取權較廣
Webhook內建集中式 Webhook 支援每個儲存庫需分別設定 Webhook
獨立運作可獨立代表自己行動（伺服器對伺服器）一律代表使用者行動

適合使用 GitHub App 的情境：

  • 你需要細緻控制權限與儲存庫存取
  • 你希望獲得重新整理權杖 (Refresh tokens) 以長期安全存取 API
  • 你需要更高的 API 速率限制
  • 你想執行不依賴使用者會話的自動化任務

適合使用 OAuth App 的情境：

  • 僅需簡單登入整合且 API 存取需求極少
  • 你需要永不過期的權杖（舊系統整合）
  • 你需要存取企業級資源（GitHub Apps 目前尚未支援企業級權限）
提示:

GitHub 建議大多數情境優先使用 GitHub Apps，因其安全性更高且權限更細緻。詳見 GitHub Apps 與 OAuth Apps 差異。

開始使用​

GitHub App 連接器支援 OAuth 2.0 整合，讓你的應用程式可以：

  • 新增「使用 GitHub 登入」驗證 (Authentication)
  • 將使用者帳號與 GitHub 身分連結
  • 從 GitHub 同步使用者個人資訊
  • 透過 Logto Secret Vault 安全儲存權杖存取 GitHub API，實現自動化任務（如建立 GitHub 問題、從你的應用程式管理儲存庫）
  • 使用 重新整理權杖 (Refresh tokens)（GitHub Apps 一律發放）以維持長期 API 存取，無需使用者重複驗證

要設定這些驗證功能，請先在 Logto 建立 GitHub 連接器：

  1. 前往 Logto 控制台 > 連接器 > 社交連接器。
  2. 點擊 新增社交連接器，選擇 GitHub App，點擊 下一步，並依照教學步驟完成整合。

步驟 1：建立 GitHub App​

在你能將 GitHub 作為驗證 (Authentication) 提供者之前，必須先在 GitHub 上建立一個 GitHub App，以取得 OAuth 2.0 憑證。

  1. 前往 GitHub 並使用你的帳號登入，或如有需要註冊新帳號。
  2. 導航至 Settings > Developer settings > GitHub Apps。
  3. 點擊 New GitHub App 註冊新應用程式：
    • GitHub App name：輸入你的應用程式唯一名稱。名稱不得超過 34 個字元，且需在 GitHub 上全域唯一。
    • Homepage URL：輸入你的應用程式首頁網址。
    • Callback URL：從 Logto GitHub 連接器複製 Callback URI 並貼上於此。若有需要可新增多個 callback URL。使用者透過 GitHub 登入後，將被導向此處並帶有 Logto 用於完成驗證 (Authentication) 的授權碼。
    • Expire user authorization tokens：請保持勾選（建議）。這將啟用權杖過期與重新整理權杖 (Refresh token)，提升安全性。
    • Request user authorization (OAuth) during installation：可選擇勾選，讓使用者在安裝時授權你的應用程式。
    • Webhook：若不需要 webhook 事件，請取消勾選 Active。僅用於驗證 (Authentication) 的情境通常不需 webhook。
  4. 在 Permissions 區段，設定你的應用程式所需權限（詳見下方步驟 2）。
  5. 在 Where can this GitHub App be installed?，若希望任何 GitHub 帳號的使用者都能用你的應用程式進行驗證 (Authentication)，請選擇 Any account。
  6. 點擊 Create GitHub App 建立 GitHub App。
備註:

與 OAuth Apps 不同，GitHub Apps 採用細緻權限（fine-grained permissions）而非廣泛權限範圍 (Scopes)。你需在 GitHub 控制台於建立應用程式時設定權限，使用者在授權時會授予特定儲存庫的存取權。

更多 GitHub App 設定細節，請參閱 Registering a GitHub App。

步驟 2：在 GitHub 設定權限​

GitHub Apps 採用細緻權限（fine-grained permissions），而非 OAuth 權限範圍 (Scopes)。你必須在建立或編輯 GitHub App 時，於 GitHub 控制台設定權限。這些權限決定你的應用程式能存取哪些資料。

瞭解 GitHub App 權限類型​

權限分為三種類型：

  • 儲存庫權限 (Repository permissions)：存取儲存庫層級資源（程式碼、議題、拉取請求等）
  • 組織權限 (Organization permissions)：存取組織層級資源（成員、團隊、專案等）
  • 帳號權限 (Account permissions)：存取使用者帳號資料（電子郵件、個人檔案、追蹤者等）

每個權限可選擇：

  • No access：應用程式無法存取此資源
  • Read-only：僅可讀取此資源，無法修改
  • Read & write：可讀取並修改此資源

若僅需「以 GitHub 登入」的基本功能，請設定以下最低 帳號權限 (Account permissions)：

權限存取層級用途
Email addressesRead-only取得使用者電子郵件以建立帳號
提示:

GitHub Apps 代表使用者操作時，預設可讀取公開個人檔案資訊。你無需額外請求基本個人資料（如使用者名稱、大頭貼、公開個人頁面網址）的權限。

進階 API 存取權限​

若你的應用程式需存取驗證 (Authentication) 以外的 GitHub API，請在 GitHub 控制台新增對應權限。常見範例如下：

權限類型權限存取層級使用情境
RepositoryContentsRead-only / Read & write存取儲存庫檔案與程式碼
RepositoryIssuesRead & write建立與管理議題
RepositoryPull requestsRead & write建立與管理拉取請求
RepositoryMetadataRead-only存取儲存庫中繼資料（許多操作必需）
OrganizationMembersRead-only列出組織成員
AccountFollowersRead-only存取使用者追蹤者與追蹤名單

這不是完整清單 — GitHub Apps 支援更多細緻權限。完整列表請參閱 Permissions required for GitHub Apps。

與 OAuth Apps 的主要差異:

與 OAuth Apps 需在 Logto 連接器設定權限範圍 (Scope) 不同，GitHub App 權限完全於 GitHub 控制台管理。你可以在 Logto GitHub 連接器的 Scope 欄位留空 — 因為 GitHub Apps 不使用傳統 OAuth 權限範圍。

只需在 GitHub 設定所需權限，使用者授權時會自動提示授權。

步驟 3：設定 Logto 連接器​

建立 GitHub App 後，你會被導向其設定頁面，可在此取得憑證。

  1. 在 GitHub App 設定頁複製 Client ID，貼到 Logto 的 clientId 欄位。
  2. 在 Client secrets 區點擊 Generate a new client secret，複製產生的密鑰並貼到 Logto 的 clientSecret 欄位。
  3. 在 Logto 點擊 Save and Done，即可將你的身分系統與 GitHub 連接。
注意:

請妥善保管 Client secret，切勿在前端程式碼中暴露。若遺失 GitHub client secret 將無法找回，需重新產生。

備註:

GitHub App 的 Client ID 與 App ID 不同。請務必使用設定頁標示為「Client ID」的值，而非 App ID。

步驟 4：一般設定​

以下為一些不會阻礙 GitHub 連線、但可能影響終端使用者驗證 (Authentication) 體驗的通用設定。

同步個人檔案資訊​

在 GitHub 連接器中，你可設定如何將 GitHub 使用者資訊同步到 Logto 使用者檔案，包括 name、avatar 與 email。可選擇：

  • 僅於註冊時同步：使用者首次登入時擷取一次個人資訊。
  • 每次登入時皆同步：每次登入時都更新個人資訊。

儲存權杖以存取 GitHub API（選用）​

若你希望存取 GitHub API 並以使用者授權執行操作（無論是社交登入或帳號連結），請在 Logto 啟用權杖儲存：

  1. 在 GitHub App 設定（步驟 2）中設定所需權限。
  2. 在 Logto GitHub 連接器啟用 Store tokens for persistent API access。Logto 會將存取權杖 (Access token) 與重新整理權杖 (Refresh token) 安全儲存於 Secret Vault。
備註:

由於 GitHub Apps 一律發放重新整理權杖 (Refresh token)，Logto 會自動儲存兩種權杖。Access token 有效期為 8 小時，但 Logto 可利用 refresh token 取得新 access token，確保 API 存取不中斷，最長可達 6 個月。

步驟 5：測試整合（選用）​

在正式上線前，請測試你的 GitHub App 整合：

  1. 在 Logto 開發租戶中使用該連接器。
  2. 驗證使用者能否以 GitHub 登入。
  3. 檢查授權時是否正確提示所需權限。
  4. 若啟用權杖儲存，確認存取權杖（與重新整理權杖）儲存無誤。
  5. 使用儲存的權杖測試 API 呼叫，確保權限運作正常。

GitHub Apps 可立即與任何 GitHub 使用者帳號配合使用 — 不像其他平台那樣需要測試帳號或應用程式審核。但若你的應用程式安裝於組織，組織擁有者可能需批准安裝。

使用 GitHub 連接器​

建立 GitHub 連接器並連結至 GitHub 後，你可以將其整合進終端使用者流程。請依需求選擇下列方式：

啟用「使用 GitHub 登入」​

  1. 在 Logto 控制台，前往 登入體驗 > 註冊與登入。
  2. 在 社交登入 區塊新增 GitHub 連接器，讓使用者可用 GitHub 驗證 (Authentication)。

深入瞭解 社交登入體驗。

使用 Account API 在你的應用程式中打造自訂帳號中心，讓已登入使用者連結或解除 GitHub 帳號。參考 Account API 教學

提示:

你可以僅啟用 GitHub 連接器作為帳號連結與 API 存取用途，而不啟用社交登入。

存取 GitHub API 並執行操作​

你的應用程式可從 Secret Vault 取得儲存的 GitHub 權杖，呼叫 GitHub API 並自動化後端任務（如建立 issue、管理儲存庫或自動化工作流程）。請參考相關教學以取得 API 存取所需權杖。

由於 GitHub Apps 在 OAuth 流程中一律發放重新整理權杖 (Refresh tokens)，Logto 會同時儲存存取權杖 (Access tokens) 與重新整理權杖。存取權杖 8 小時後過期，但 Logto 會自動使用有效期 6 個月的重新整理權杖取得新存取權杖，確保 API 存取不中斷。

管理使用者的 GitHub 身分​

使用者連結 GitHub 帳號後，管理員可在 Logto 控制台管理該連結：

  1. 前往 Logto 控制台 > 使用者管理 並開啟該使用者個人檔案。
  2. 在 社交連結 區塊找到 GitHub 項目並點擊 管理。
  3. 在此頁面，管理員可管理使用者的 GitHub 連結，檢視所有從 GitHub 帳號授權並同步的個人資訊，以及檢查存取權杖 (Access token) 與重新整理權杖 (Refresh token) 狀態。
備註:

與使用權限範圍 (Scopes) 的 OAuth Apps 不同，GitHub Apps 採用細緻權限，需在 GitHub 控制台設定。使用者存取權杖僅限於你的 App 與使用者雙方皆有的權限。Logto 無法直接顯示權限清單，但你的應用程式將依 GitHub App 設定的權限存取資源。

參考資料​

GitHub 開發者文件 - 關於 GitHub Apps

GitHub 開發者文件 - 註冊 GitHub App

GitHub 開發者文件 - 產生使用者存取權杖

GitHub 開發者文件 - 重新整理使用者存取權杖

GitHub Apps 與 OAuth Apps 差異