设置 GitHub 社交登录（通过 GitHub App）

集成 GitHub App，可启用“使用 GitHub 登录”、账户绑定，并通过细粒度权限和刷新令牌 (Refresh token) 安全访问 GitHub API。

提示:

本指南假设你对 Logto 连接器 (Connectors) 有基本的了解。对于不熟悉的人，请参考 连接器 (Connectors) 指南以开始了解。

GitHub App 与 OAuth App 的区别

GitHub 提供两种用于认证 (Authentication) 和 API 访问的应用类型：GitHub App 和 OAuth App。以下对比可帮助你选择：

功能	GitHub App	OAuth App
权限 (Permissions)	细粒度权限——仅请求特定资源的访问权限	广泛权限——通常授予超出实际需求的访问权限
权限管理	仅在 GitHub 控制台配置；Logto 的 Scope 字段可为空	通过 Logto 连接器中的权限 (Scopes) 配置
刷新令牌 (Refresh tokens)	OAuth 流程中始终颁发	不支持——令牌不会过期，除非被撤销
令牌过期	访问令牌 (Access token) 8 小时后过期；刷新令牌 (Refresh token) 有效期 6 个月	访问令牌 (Access token) 永不过期
用户控制	用户可选择应用可访问的仓库	可访问用户有权限的所有仓库
速率限制	更高的速率限制，随安装数量扩展	速率限制较低（每用户每小时 5,000 次请求）
安装方式	安装在账户 / 组织上，可细粒度控制仓库访问	由用户授权，权限范围较广
Webhook	内置集中式 Webhook 支持	需为每个仓库单独配置
独立操作	可独立代表自身操作（服务器到服务器）	始终代表用户操作

适合使用 GitHub App 的场景：

• 你需要对权限 (Permissions) 和仓库访问进行细粒度控制
• 你希望获得刷新令牌 (Refresh token)，以便长期安全访问 API
• 你需要更高的 API 速率限制
• 你希望执行与用户会话无关的自动化任务

适合使用 OAuth App 的场景：

• 仅需简单登录集成，对 API 访问要求极低
• 你需要不会过期的令牌（用于遗留集成）
• 你需要访问企业级资源（GitHub App 目前尚不支持企业级权限）

提示:

GitHub 推荐在大多数场景下优先使用 GitHub App，因为其安全性更高且权限 (Permissions) 更细粒度。了解更多 GitHub App 与 OAuth App 的区别。

开始使用

GitHub App 连接器支持 OAuth 2.0 集成，让你的应用可以：

• 添加“使用 GitHub 登录”认证 (Authentication)
• 将用户账户与 GitHub 身份关联
• 从 GitHub 同步用户资料信息
• 通过 Logto Secret Vault 安全存储的令牌访问 GitHub API，实现自动化任务（如在你的应用中创建 GitHub issue、管理仓库等）
• 使用 刷新令牌 (Refresh token)（GitHub App 始终颁发）维持长期 API 访问，无需用户反复认证 (Authentication)

要设置这些认证 (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：输入你的应用主页 URL。
   • Callback URL：从你的 Logto GitHub 连接器复制 Callback URI 并粘贴到此处。如有需要，你可以添加多个回调 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? 下，选择 Any account，如果你希望任何 GitHub 账户的用户都能用你的应用进行认证 (Authentication)。
6. 点击 Create GitHub App 创建 GitHub App。

备注:

与 OAuth Apps 不同，GitHub Apps 使用细粒度权限而不是广泛的权限 (Scope)。你需要在 GitHub 控制台创建应用时配置权限，用户在授权时会授予对特定仓库的访问权限。

关于设置 GitHub Apps 的更多细节，请参阅 注册 GitHub App。

步骤 2：在 GitHub 中配置权限

GitHub Apps 使用细粒度权限而不是 OAuth 权限 (Scope)。你必须在GitHub 控制台创建或编辑 GitHub App 时配置权限。这些权限决定了你的应用可以访问哪些数据。

理解 GitHub App 权限

权限分为三类：

• 仓库权限：访问仓库级资源（代码、议题、拉取请求等）
• 组织 (Organization) 权限：访问组织级资源（成员、团队、项目等）
• 账户权限：访问用户账户数据（邮箱、资料、关注者等）

对于每个权限，你可以选择：

• No access：应用无法访问该资源
• Read-only：应用只能读取该资源，不能修改
• Read & write：应用可以读取和修改该资源

认证 (Authentication) 推荐权限

对于基础的“使用 GitHub 登录”功能，配置以下最小账户权限：

权限	访问级别	用途
Email addresses	只读	获取用户邮箱地址用于账户创建

提示:

GitHub Apps 在代表用户操作时默认可以读取公开资料信息。你无需显式请求用户名、头像和公开资料 URL 等基础资料权限。

访问 API 的额外权限

如果你的应用需要在认证 (Authentication) 之外访问 GitHub API，请在 GitHub 控制台添加相应权限。以下是一些常见示例：

权限类型	权限	访问级别	用例说明
仓库	Contents	只读 / 读写	访问仓库文件和代码
仓库	Issues	读写	创建和管理议题
仓库	Pull requests	读写	创建和管理拉取请求
仓库	Metadata	只读	访问仓库元数据（许多操作所需）
组织 (Organization)	Members	只读	列出组织成员
账户	Followers	只读	访问用户的关注者和关注列表

这不是完整列表——GitHub Apps 支持更多细粒度权限。完整列表请参阅 GitHub Apps 所需权限。

与 OAuth Apps 的关键区别:

与在 Logto 连接器中配置权限 (Scope) 的 OAuth Apps 不同，GitHub App 权限完全在 GitHub 控制台管理。你可以在 Logto GitHub 连接器中将 Scope 字段留空——因为 GitHub Apps 不使用传统的 OAuth 权限 (Scope)。

只需在 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（标注为“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) 获取新的访问令牌，确保最长 6 个月的 API 不间断访问。

步骤 5：测试你的集成（可选）

在正式上线前，测试你的 GitHub App 集成：

1. 在 Logto 开发租户中使用该连接器。
2. 验证用户是否可以通过 GitHub 登录。
3. 检查用户在授权时是否被正确提示所需权限。
4. 如果启用了令牌存储，验证访问令牌 (Access token)（和刷新令牌 (Refresh token)）是否正确存储。
5. 使用存储的令牌测试 API 调用，确保权限按预期工作。

GitHub Apps 可立即与任何 GitHub 用户账户配合使用——不像某些平台那样需要测试用户或应用审核。但如果你的应用安装在组织 (Organization) 上，组织所有者可能需要批准安装。

使用 GitHub 连接器

创建并连接 GitHub 连接器后，你可以将其集成到终端用户流程中。根据你的需求选择相应方式：

启用“使用 GitHub 登录”

1. 在 Logto 控制台，前往 登录体验 > 注册与登录。
2. 在 社交登录 区域添加 GitHub 连接器，让用户可通过 GitHub 认证 (Authentication)。

了解更多 社交登录体验。

绑定或解绑 GitHub 账户

使用 Account API 在你的应用中构建自定义账户中心，让已登录用户绑定或解绑 GitHub 账户。参见 Account API 教程

提示:

你可以仅为账户绑定和 API 访问启用 GitHub 连接器，无需启用社交登录。

访问 GitHub API 并执行操作

你的应用可从 Secret Vault 获取已存储的 GitHub 令牌，调用 GitHub API 并自动化后端任务（如创建 issue、管理仓库或自动化工作流）。参考相关指南，了解如何获取存储的令牌以访问 API。

由于 GitHub App 在 OAuth 流程中始终颁发刷新令牌 (Refresh token)，Logto 会同时存储访问令牌 (Access token) 和刷新令牌 (Refresh token)。访问令牌 (Access token) 8 小时后过期，但 Logto 会自动使用有效期 6 个月的刷新令牌 (Refresh token) 获取新访问令牌，确保 API 访问不中断。

管理用户的 GitHub 身份

用户绑定 GitHub 账户后，管理员可在 Logto 控制台管理该连接：

1. 前往 Logto 控制台 > 用户管理 并打开用户资料。
2. 在 社交连接 区域找到 GitHub 项，点击 管理。
3. 在此页面，管理员可管理用户的 GitHub 连接，查看所有已授权并同步的 GitHub 账户资料信息，以及访问令牌 (Access token) 和刷新令牌 (Refresh token) 状态。

备注:

与使用权限 (Scopes) 的 OAuth App 不同，GitHub App 使用在 GitHub 控制台配置的细粒度权限 (Permissions)。用户访问令牌 (Access token) 仅限于你的应用和用户双方都拥有的权限 (Permissions)。Logto 无法直接展示权限列表，但你的应用可根据 GitHub App 设置中配置的权限 (Permissions) 获得相应访问能力。

参考资料

GitHub 开发者文档 - 关于 GitHub App

GitHub 开发者文档 - 注册 GitHub App

GitHub 开发者文档 - 生成用户访问令牌 (Access token)

GitHub 开发者文档 - 刷新用户访问令牌 (Access token)

GitHub App 与 OAuth App 的区别