跳到主要内容

设置 GitHub 社交登录

集成 GitHub OAuth 应用以启用“使用 GitHub 登录”、账户关联，以及安全访问 GitHub API。

提示:

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

开始使用​

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

  • 添加“使用 GitHub 登录”认证 (Authentication)
  • 将用户账户与 GitHub 身份关联
  • 从 GitHub 同步用户资料信息
  • 通过 Logto Secret Vault 安全存储令牌访问 GitHub API，实现自动化任务（如从你的应用创建 GitHub issue、管理仓库等）

要设置这些认证 (Authentication) 功能，首先需要在 Logto 中创建一个 GitHub 连接器：

  1. 前往 Logto 控制台 > 连接器 > 社交连接器。
  2. 点击 添加社交连接器，选择 GitHub，点击 下一步，并按照分步教程完成集成。

步骤 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：输入你的应用主页 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）定义了你的应用向用户请求的权限，并控制你的应用可以从他们的 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：后续按需请求增量权限范围​

  • 用户登录后，你可以通过重新发起联合社交授权 (Authorization) 流程并更新用户的存储令牌集，按需请求额外权限范围。
  • 这些额外权限范围无需填写在 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 Apps 与 OAuth Apps 的区别。

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

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

  1. 在 Logto 开发租户中使用该连接器。
  2. 验证用户是否可以通过 GitHub 登录。
  3. 检查是否请求了正确的权限范围。
  4. 如果你存储了令牌，测试 API 调用。

GitHub OAuth 应用可立即与任何 GitHub 用户账户配合使用——无需像其他平台那样设置测试用户或应用审核。

使用 GitHub 连接器​

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

启用“使用 GitHub 登录”​

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

了解更多关于社交登录体验。

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

提示:

你可以仅为账户关联和 API 访问启用 GitHub 连接器，而不启用社交登录。

访问 GitHub API 并执行操作​

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

管理用户的 GitHub 身份​

用户关联 GitHub 账户后，管理员可以在 Logto 控制台管理该关联：

  1. 前往 Logto 控制台 > 用户管理 并打开用户资料。
  2. 在 社交关联 下找到 GitHub 项，点击 管理。
  3. 在此页面，管理员可以管理用户的 GitHub 关联，查看所有从 GitHub 账户授权并同步的资料信息，以及检查访问令牌 (Access token) 状态。
备注:

GitHub 的访问令牌 (Access token) 响应不包含具体的权限 (Scope) 信息，因此 Logto 无法直接显示用户授权的权限 (Permissions) 列表。但只要用户在授权时同意了所请求的权限 (Scopes)，你的应用在访问 GitHub API 时就会拥有相应的权限 (Permissions)。

参考资料​

GitHub 开发者文档 - 关于应用

GitHub 开发者文档 - 创建 OAuth 应用

GitHub OAuth 应用权限 (Scopes) 文档