跳到主要内容

设置 GitHub 社交登录

集成 GitHub OAuth app 以启用“使用 GitHub 登录”、账户绑定，以及安全访问 GitHub API。

提示:

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

开始使用​

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

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

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

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

第一步：在 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。

第二步：配置你的 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 丢失后无法找回——你需要重新生成一个新的。

第三步：配置权限范围（可选）​

权限范围（Scopes）定义了你的应用从用户处请求的权限，并控制你的应用可以访问其 GitHub 账户的哪些数据。

在 Logto 的 Scopes 字段中，可以向 GitHub 请求额外权限。根据你的需求选择以下方式之一：

方案一：无需额外 API 权限范围​

  • 保持 Logto GitHub 连接器中的 Scopes 字段为空。
  • 默认会请求 read:user 权限范围，以确保 Logto 能正确获取基本用户信息（如邮箱、姓名、头像）。

方案二：登录时请求额外权限范围​

  • 浏览所有可用的 GitHub OAuth 应用权限范围，仅添加你的应用所需的权限范围。
  • 在 Scopes 字段中输入所有需要的权限范围，使用空格分隔。
  • 你在此处填写的权限范围会覆盖默认值，因此请务必包含认证 (Authentication) 权限范围：read:user。
  • 常见的额外权限范围包括：
    • repo：完全控制私有仓库
    • public_repo：访问公共仓库
    • user:email：访问用户邮箱地址
    • notifications：访问通知
  • 请确保所有权限范围拼写正确且有效。拼写错误或不支持的权限范围会导致 GitHub 返回 “Invalid scope” 错误。

方案三：后续按需请求增量权限范围​

  • 用户登录后，你可以通过重新发起联合社交授权流程并更新用户存储的令牌集，按需请求额外权限范围。
  • 这些额外权限范围无需在 Logto GitHub 连接器的 Scopes 字段中填写，可以通过 Logto 的 Social Verification API 实现。

按照上述步骤操作后，你的 Logto GitHub 连接器只会请求你的应用所需的权限——不多也不少。

提示:

如果你的应用请求这些权限范围以访问 GitHub API 并执行操作，请确保在 Logto GitHub 连接器中启用 Store tokens for persistent API access。详见下一节。

第四步：常规设置​

以下是一些不会阻止与 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 的区别。

第五步：测试你的集成（可选）​

在正式上线前，测试你的 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 并自动化后端任务（例如，创建问题、管理仓库或自动化工作流）。请参考关于检索存储令牌以访问 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) 文档