跳至主要內容

設定 GitHub App 社交登入

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

提示:

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

GitHub App vs OAuth App​

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

功能GitHub AppOAuth App
權限 (Permissions)細緻權限 — 僅請求特定資源存取權廣泛權限範圍 — 通常授予超出所需的存取權
權限管理僅能於 GitHub 控制台設定；Logto 的 Scope 欄位可留空於 Logto 連接器中以權限範圍設定
重新整理權杖 (Refresh tokens)OAuth 流程中一律發放不支援 — 權杖除非撤銷否則永不過期
權杖過期存取權杖 (Access tokens) 8 小時後過期；重新整理權杖 6 個月有效存取權杖永不過期
使用者控制使用者可選擇應用程式可存取哪些儲存庫可存取使用者有權限的所有儲存庫
速率限制依安裝數量擴展的較高速率限制較低速率限制（每使用者每小時 5,000 次請求）
安裝方式安裝於帳號 / 組織，並可細緻設定儲存庫存取權由使用者授權，存取權較廣
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 存取，無需使用者重複驗證

要設定這些驗證 (Authentication) 功能，請先在 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 帳號授權並同步的個人資料資訊，以及檢查存取權杖與重新整理權杖狀態。
備註:

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

參考資料​

GitHub 開發者文件 - 關於 GitHub Apps

GitHub 開發者文件 - 註冊 GitHub App

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

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

GitHub Apps vs OAuth Apps