技术 -

自部署 Outline 如何支持通过 GitHub 账号登录

Outline 是一个功能完善、UI 简洁实用的 Wiki 程序，其线上托管版本需要付费，但提供免费、可以自行部署的 开源版本。Outline 不支持账号密码登录，而是需要通过 OIDC、SSO、SAML 等方式集成第三方的身份验证服务。本文介绍如何让自部署的 Outline 支持通过 GitHub 账号登录。

文章目录

前提条件

  1. 已完成 Outline 部署，且可以在本机正常访问 登录到 Outline 页面（如图）
  2. 记下 Outline 的根页面 URL（一般与 Outline 登录页面的 URL 一致，形如 https://docs.yourcompany.com/）

步骤一：在 GitHub 中创建 OAuth Application

  1. 访问 GitHub 并登录
  2. 进入 OAuth Apps 页面（也可以依次点击：右上角头像 - Settings - Developer Settings - OAuth Apps）
  3. 点击 New OAuth App

  4. 填写 Register a new OAuth application 表单

    1. Application name: 可自行填写，例如 outline
    2. Homepage URL: 填写 Outline 的根路径 URL
    3. Authorization callback URL: 填写 <Homepage URL>/auth/oidc.callback，其中 <Homepage URL> 需要替换为Outline 的根页面 URL
  5. 点击 Register application 按钮

步骤二：获取 Client ID 和 Client secrets

  1. 进入 OAuth Apps 页面（也可以依次点击：右上角头像 - Settings - Developer Settings - OAuth Apps）
  2. 选择步骤一创建的应用
  3. 点击 Generate a new client secret 按钮
  4. 记下 Client ID 和 Client secret（注意 Client secret 仅在创建时显示一次，后续不可再查询；如不慎遗失，可以再次点击按钮重新创建一个）

步骤三：配置 Outline 环境变量

注意：在以下环境变量示例中，URL, OIDC_CLIENT_ID 以及 OIDC_CLIENT_SECRET 需要根据实际情况填写（上文已经提示您需要记下并在这里填写的信息），其他环境变量为固定值，可以直接套用。

# 填写首页 URL（同时影响 OAuth 授权完成后跳转返回的 URL）
URL=<Homepage URL>

# 填写 GitHub OAuth application 的 Client ID 和 Client secret
OIDC_CLIENT_ID=<your-client-id>
OIDC_CLIENT_SECRET=<your-client-secret>

# 填写 GitHub 的 OAuth endpoint，参考 https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#web-application-flow
OIDC_AUTH_URI=https://github.com/login/oauth/authorize
OIDC_TOKEN_URI=https://github.com/login/oauth/access_token

# OAuth 授权的权限范围
OIDC_SCOPES=read:user user:email

# 通过 GitHub API 获取用户基本信息
OIDC_USERINFO_URI=https://api.github.com/user
OIDC_USERNAME_CLAIM=name

# 让登录界面显示为“使用 GitHub 继续”
OIDC_DISPLAY_NAME=GitHub

实现的思路

  • Outline 支持通过 OIDC 完成用户身份验证与登录
  • OIDC 是建立在 OAuth 2.0 之上的一个身份层，其中约定了一个通过 OAuth 2.0 进行身份验证的 UserInfo Endpoint，客户端可以请求这个 Endpoint 来获得用户的一些基本信息。
  • GitHub 支持第三方 APP 通过 OAuth 2.0 接入

虽然 GitHub 没有提供符合 OIDC 实现的 UserInfo Endpoint 来读取用户的基本信息，但幸运的是通过合适的配置（OIDC_USERINFO_URI, OIDC_SCOPES 以及 OIDC_USERNAME_CLAIM），可以让 Outline 通过 GitHub 提供的 /user API 等效地完成用户基本信息的获取。

如果配置正确，点击 Outline 首页的 使用 GitHub 继续 按钮后，应该看到如图所示的授权页面，授权完成后将重定向回 Outline 并且为已登录状态。

参考资料

GitHubOAuthOutlineOIDC