跳至主要內容

設定 GitHub 社交登入 (Set up social login with GitHub)

整合 GitHub OAuth app 以啟用「使用 GitHub 登入」、帳號連結，以及安全存取 GitHub API。

提示:

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

開始使用​

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

  • 新增「使用 GitHub 登入」驗證 (Authentication)
  • 將使用者帳號與 GitHub 身分連結
  • 從 GitHub 同步使用者個人資料資訊
  • 透過 Logto Secret Vault 安全儲存權杖，存取 GitHub API 以自動化任務（例如：從你的應用程式建立 GitHub 問題、管理儲存庫）

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

  1. 前往 Logto 控制台 > 連接器 (Connector) > 社交連接器 (Social connector)。
  2. 點擊 新增社交連接器 (Add social connector)，選擇 GitHub，點擊 下一步 (Next)，並依照分步教學完成整合。

步驟 1：在 GitHub 建立 OAuth 應用程式​

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

  1. 前往 GitHub，使用你的帳號登入，或如有需要註冊新帳號。
  2. 導航至 Settings > Developer settings > OAuth apps。
  3. 點擊 New OAuth App 註冊新應用程式：
    • Application name：輸入你的應用程式描述性名稱。
    • Homepage URL：輸入你的應用程式首頁網址。
    • Authorization callback URL：從 Logto GitHub 連接器複製 Callback URI，並貼到此欄位。使用者以 GitHub 登入後，會被導向此處，並帶有 Logto 用於完成驗證 (Authentication) 的授權碼。
    • Application description：（選填）新增應用程式簡要描述。
  4. 點擊 Register application 建立 OAuth 應用程式。
備註:

建議不要勾選 Enable Device Flow，因為使用者若在行動裝置上以 GitHub 登入，需在 GitHub 行動應用程式中確認初始登入動作。許多 GitHub 使用者並未在手機安裝 GitHub 行動應用程式，這可能會阻礙登入流程。僅當你預期終端使用者會透過 GitHub 行動應用程式確認登入流程時才啟用此選項。詳情請參閱 device flow。

更多 GitHub OAuth 應用程式設定細節，請參閱 Creating an OAuth App。

步驟 2：設定你的 Logto 連接器​

在 GitHub 建立 OAuth 應用程式後，你會被導向詳細頁面，可在此複製 Client ID 並產生 Client secret。

  1. 從 GitHub OAuth 應用程式複製 Client ID，貼到 Logto 的 clientId 欄位。
  2. 在 GitHub 點擊 Generate a new client secret 產生新密鑰，然後複製並貼到 Logto 的 clientSecret 欄位。
  3. 在 Logto 點擊 Save and Done，將你的身分系統與 GitHub 連接。
注意:

請妥善保管你的 Client secret，切勿在前端程式碼中暴露。若遺失 GitHub client secret 將無法復原，必須重新產生。

步驟 3：設定權限範圍 (Scopes)（選填）​

權限範圍 (Scopes) 定義你的應用程式向使用者請求的權限，並控制可從其 GitHub 帳號存取哪些資料。

在 Logto 的 Scopes 欄位中可向 GitHub 請求額外權限。根據需求選擇下列其中一種方式：

選項 1：不需額外 API 權限範圍​

  • 保持 Logto GitHub 連接器的 Scopes 欄位為空。
  • 預設會請求 read:user 權限範圍，確保 Logto 能正確取得基本使用者資訊（如電子郵件、名稱、大頭貼）。

選項 2：登入時請求額外權限範圍​

  • 瀏覽所有 GitHub OAuth 應用程式可用權限範圍，僅新增應用程式所需的權限範圍。
  • 在 Scopes 欄位輸入所有所需權限範圍，以空格分隔。
  • 此處列出的權限範圍會覆蓋預設值，因此請務必包含驗證 (Authentication) 權限範圍：read:user。
  • 常見額外權限範圍包含：
    • repo：完全控制私人儲存庫
    • public_repo：存取公開儲存庫
    • user:email：存取使用者電子郵件地址
    • notifications：存取通知
  • 請確保所有權限範圍拼寫正確且有效。錯誤或不支援的權限範圍會導致 GitHub 回傳「Invalid scope」錯誤。

選項 3：後續請求增量權限範圍​

  • 使用者登入後，可隨時重新啟動聯邦社交授權流程並更新使用者儲存的權杖組，來請求額外權限範圍。
  • 這些額外權限範圍無需填寫在 Logto GitHub 連接器的 Scopes 欄位，可透過 Logto 的 Social Verification API 實現。

依照這些步驟，Logto GitHub 連接器僅會請求應用程式所需的權限，不多也不少。

提示:

若你的應用程式請求這些權限範圍以存取 GitHub API 並執行操作，請務必在 Logto GitHub 連接器啟用 Store tokens for persistent API access。詳情請見下一節。

步驟 4：一般設定​

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

同步個人資料資訊​

在 GitHub 連接器中，你可以設定同步個人資料資訊（如使用者名稱與大頭貼）的政策。可選擇：

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

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

若你希望在取得使用者授權後（無論是社交登入或帳號連結）存取 GitHub API 並執行操作，Logto 需取得特定 API 權限範圍並儲存權杖。

  1. 依照上述說明新增所需權限範圍。
  2. 在 Logto GitHub 連接器啟用 Store tokens for persistent API access。Logto 會將 GitHub 存取權杖安全儲存在 Secret Vault。
備註:

如本教學所述，使用 GitHub OAuth App 時，無法從 GitHub 取得重新整理權杖 (Refresh token)，因為其存取權杖 (Access token) 不會過期，除非使用者手動撤銷。因此，無需在 Scopes 欄位新增 offline_access，否則可能導致錯誤。

若你希望存取權杖 (Access token) 會過期或使用重新整理權杖 (Refresh token)，請考慮改用 GitHub App。瞭解 GitHub App 與 OAuth App 的差異。

步驟 5：測試你的整合（選填）​

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

  1. 在 Logto 開發租戶中使用該連接器。
  2. 驗證使用者能以 GitHub 登入。
  3. 檢查是否請求正確的權限範圍。
  4. 若有儲存權杖，請測試 API 呼叫。

GitHub OAuth 應用程式可立即與任何 GitHub 使用者帳號配合使用——不需像其他平台一樣申請測試使用者或應用程式審核。

運用 GitHub 連接器 (Connector)​

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

啟用「使用 GitHub 登入」​

  1. 在 Logto 控制台，前往 登入體驗 (Sign-in experience) > 註冊與登入 (Sign-up and sign-in)。
  2. 在 社交登入 (Social sign-in) 區塊新增 GitHub 連接器 (Connector)，讓使用者能以 GitHub 驗證 (Authentication)。

深入瞭解 社交登入體驗 (social sign-in experience)。

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

提示:

你可以僅啟用 GitHub 連接器 (Connector) 以供帳號連結與 API 存取，而不啟用社交登入。

存取 GitHub API 並執行操作​

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

管理使用者的 GitHub 身分​

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

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

GitHub 的存取權杖 (Access token) 回應不包含具體權限範圍 (Scope) 資訊，因此 Logto 無法直接顯示使用者授權的權限清單。不過，只要使用者在授權時同意所請求的權限範圍 (Scopes)，你的應用程式在存取 GitHub API 時就會擁有相應權限。

參考資料​

GitHub 開發者文件 - 關於 Apps

GitHub 開發者文件 - 建立 OAuth App

GitHub OAuth App 權限範圍 (Scopes) 文件