WordPress 子比主题接入 Linux.do OAuth 登录完整记录

WordPress · Zibll · OAuth 2.0

子比主题接入 Linux.do 登录

从主题设置、授权回调到 WordPress 用户绑定的一次完整实现记录。

这次接入的目标，是让访客直接使用 Linux.do 论坛账号登录 WordPress，同时保留子比主题原有的登录界面、按钮样式和用户中心。实现遵循 Linux.do Connect 官方 OAuth 2.0 授权码流程，并增加 state、PKCE、等级限制和站内安全跳转。

附件下载与使用

下面的压缩包包含可直接安装的 WordPress 插件、子比主题自动补丁和完整 README，不包含子比主题源码，也不包含任何真实密钥。

下载 Linux.do 子比主题接入包 v1.1.0

• linuxdo-oauth/linuxdo-oauth.php：上传到 WordPress 插件目录并启用。
• tools/patch-zibll-linuxdo.php：在服务器执行一次，将设置和按钮融入子比主题。
• README.md：包含安装、配置、验证、升级和回滚说明。

基本使用顺序：备份站点 → 安装并启用插件 → 执行主题补丁 → 在子比主题设置中填写 Client ID 与 Secret → 将 Linux.do 应用回调设置为 https://你的域名/oauth/linuxdo/callback → 测试登录。

SHA-256：444C7F6D986B01E9A58566BE213D45EC4253CCE4AFEB149DF9A0C4408014CBB9

最终地址

授权流程

1. 用户在子比登录窗口点击“Linux.do 登录”。
2. 站点生成一次性 state 和 PKCE code_verifier，保存 10 分钟。
3. 浏览器跳转到 Linux.do 授权端点，参数包含 client_id、精确回调地址、response_type=code、scope=user 和 PKCE challenge。
4. 用户在 Linux.do 完成登录与授权，服务端携带 code 和 state 返回回调地址。
5. WordPress 校验并立即删除 state，再以表单方式向 Token 端点兑换 access token。
6. 插件使用 Authorization: Bearer 请求用户信息接口。
7. 以不可变的 Linux.do id 查找绑定关系；已有用户直接登录，没有绑定时创建站内账号。
8. WordPress 写入登录 Cookie，并安全返回用户发起登录前的本站页面。

申请和配置

1. 在 Linux.do Connect 创建应用，填写应用名称、主页和说明。
2. 回调地址必须精确填写为 https://7998888.xyz/oauth/linuxdo/callback，包括协议、路径和结尾形式。
3. 复制 Client ID 和 Client Secret。
4. 进入“子比主题设置 → 用户互动 → 社交登录”，开启 Linux.do 登录。
5. 填写 Client ID、Client Secret，按需要选择最低信任等级 0 至 4。
6. 保存后打开站点登录页，检查按钮、授权跳转和回调。

涉及的文件

三个被修改的主题文件旁均保留了 .before-linuxdo 备份。插件源码独立放在插件目录，便于停用、升级和排查。

主题配置数据

主题设置保存在 WordPress 的 zibll_options 选项中，新增两个键：

oauth_linuxdo_s       // 是否启用 Linux.do 登录
oauth_linuxdo_option  // Client ID、Secret、接口地址、最低等级

真实 Secret 不写在主题 PHP 文件、文章或前端 HTML 中，只由 WordPress 服务端在兑换 Token 时读取。

用户字段映射

关键实现片段

生成授权参数

$params = [
    'client_id'             => $client_id,
    'redirect_uri'          => home_url('/oauth/linuxdo/callback'),
    'response_type'         => 'code',
    'scope'                 => 'user',
    'state'                 => $state,
    'code_challenge'        => $challenge,
    'code_challenge_method' => 'S256',
];

读取用户信息

wp_remote_get('https://connect.linux.do/api/user', [
    'headers' => [
        'Authorization' => 'Bearer ' . $access_token,
        'Accept'        => 'application/json',
    ],
]);

安全处理

• state 防 CSRF：随机值只保存 10 分钟，并在回调时一次性删除。
• PKCE S256：即使授权码泄露，没有 verifier 也不能直接兑换 Token。
• 精确 redirect_uri：授权请求与 Token 请求使用完全相同的回调地址。
• 同域返回：登录后的返回地址必须属于本站，外部地址会回退到首页。
• 不按邮箱自动合并：避免第三方邮箱信息变化导致站内账号被错误接管。
• Secret 不下发：浏览器只接触授权地址，Secret 始终留在服务端。

验证清单

• 登录页只出现一个 Linux.do 按钮，链接指向 /oauth/linuxdo。
• 登录入口返回 302，并跳转到 Linux.do 授权页面。
• 授权 URL 中的 scope 为 user。
• 回调地址与 Linux.do 应用后台完全一致。
• 首次登录可以创建 WordPress 用户，再次登录复用同一个用户。
• 低于设定信任等级的账号会得到明确提示。
• 主页、登录页和后台主题设置没有 PHP 语法错误或重复按钮。

升级注意

插件文件不会因子比主题升级而被覆盖，但主题目录中的三个修改文件可能被新版主题替换。升级前应备份，升级后检查 Linux.do 类型、设置字段和用户元数据列表是否仍在。长期维护时，建议把主题改动整理成可重复应用的补丁。