统一身份认证

为多个 Halo 站点提供“身份中心 + 接入站”的单点登录能力。一个站点作为身份中心统一承接登录与授权，其它 Halo 站点作为接入站跳转到身份中心完成认证，并在回调后建立本站登录态、绑定本地用户、同步用户资料和映射本地角色。

功能演示

地址	账号/密码
演示站	demo/demo123.

交流群

点击链接加入群聊【halo博客-lywq插件】

插件介绍

halo-plugin-sso 适合一组 Halo 站点共用同一套账号体系的场景，例如主站、文档站、社区站、资源站分别部署，但希望用户只使用一个中心账号登录。

插件采用 Authorization Code + PKCE 的登录闭环：

1. 接入站发起登录。
2. 用户被跳转到身份中心授权端点。
3. 身份中心确认用户登录状态和授权条件。
4. 身份中心向接入站回调授权码。
5. 接入站使用授权码换取 Token，拉取用户身份信息。
6. 接入站绑定或创建本地 Halo 用户，映射角色并建立本地登录态。

当前能力包括：

• 身份中心模式：管理接入站、签发授权码、提供 Token 和 UserInfo、下发中心标准角色。
• 接入站模式：跳转身份中心登录、处理回调、绑定或创建本地用户、同步用户资料、映射本地角色。
• 登录入口控制：接入站可选择自动跳转 SSO 登录，也可保留 Halo 默认登录页并手动选择“统一身份认证”。
• 动态认证提供者信息：接入站登录页展示的 displayName、description、logo、website 会从身份中心站点基础信息同步。
• 角色映射：身份中心下发中心角色，接入站按映射规则转换为本站本地角色。
• 审计日志：记录接入站登录成功、失败、失败原因，并支持筛选、聚合、手动清理和自动清理。
• 用户绑定：记录中心账号与接入站本地用户的绑定关系。

适用环境

• Halo >= 2.25.0
• Java 21+
• 一个可被接入站访问的身份中心站点地址，例如 https://auth.example.com
• 接入站需要有稳定外部访问地址，例如 https://blog.example.com

生产环境建议使用 HTTPS。开发调试时可在插件设置中临时开启“开发环境允许 HTTP localhost”，但别把这个当生产方案，真上生产这么干就有点硬莽了。

快速开始

完整接入至少需要两个 Halo 站点：

• 站点 A：身份中心。
• 站点 B：接入站。

下面用：

• 身份中心：https://auth.example.com
• 接入站：https://blog.example.com

1. 安装插件

在身份中心站点和每个接入站点都安装并启用本插件。

构建插件：

./gradlew build

构建完成后，插件 JAR 位于：

build/libs/

将 JAR 上传到 Halo 后台插件管理并启用。

2. 配置身份中心

进入身份中心站点后台：

控制台 -> 插件 -> 统一身份认证 -> 设置

在“基础设置”中配置：

配置项	建议值	说明
运行模式	身份中心模式	当前站点负责统一登录和授权
中心标准角色	subscriber、author、editor 等	只有选中的中心角色会下发给接入站
要求邮箱已验证	开启	未验证邮箱的中心用户不允许跨站登录

然后进入插件控制台页面：

控制台 -> 系统工具 -> 统一身份认证

在“接入站”区域创建一个接入站：

字段	示例	说明
接入站名称	我的博客	控制台展示用
站点地址	https://blog.example.com	接入站外部访问地址
Redirect URI	https://blog.example.com/apis/public.sso.muyin.site/v1alpha1/client/callback	接入站回调地址
启用状态	开启	关闭后该接入站不能继续登录

创建成功后会得到：

• Client ID
• Client Secret

Client Secret 只展示一次，复制保存好。这个东西丢了就重新生成或重建接入站，别指望页面再掏出来给你看。

3. 配置接入站

进入接入站后台：

控制台 -> 插件 -> 统一身份认证 -> 设置

在“基础设置”中配置：

配置项	示例	说明
运行模式	接入站模式	当前站点负责跳转登录和建立本地登录态
身份中心地址	https://auth.example.com	身份中心站点外部地址
Client ID	从身份中心复制	对应身份中心创建的接入站
Client Secret	从身份中心复制	服务端换取 Token 使用
默认本地角色	guest 或其它低权限角色	未命中角色映射时使用
登录时同步用户资料	按需开启	同步邮箱、用户名、展示名称和头像
自动跳转 SSO 登录	按需开启	开启后访问 /login 自动跳转身份中心

接入站保存配置后，插件会定期从身份中心同步认证提供者信息。同步来源是身份中心 Halo 系统基础设置：

AuthProvider 字段	身份中心来源
displayName	站点标题
description	站点副标题
logo	站点 Logo，未配置时使用 favicon，再未配置时使用插件默认图标
website	站点外部访问地址

如果身份中心临时不可用，接入站会保留上一次同步成功的本地认证提供者信息，不会把登录入口改成空壳。

4. 配置角色映射

进入接入站插件控制台：

控制台 -> 系统工具 -> 统一身份认证 -> 角色映射

创建映射关系：

中心角色	本地角色	说明
subscriber	guest	普通用户
author	contributor	投稿或作者
editor	editor	编辑

规则说明：

• 身份中心只下发“中心标准角色”中允许的角色。
• 接入站只按启用状态的映射规则转换角色。
• 未命中映射时使用“默认本地角色”。
• 已有本地用户登录时，插件会追加缺失角色，不会清空用户已有本地角色。

登录教程

自动 SSO 登录

适合希望接入站完全交给身份中心登录的场景。

1. 在接入站插件设置中开启“自动跳转 SSO 登录”。
2. 用户访问接入站 /login。
3. 插件自动跳转到身份中心授权页。
4. 用户在身份中心登录。
5. 登录成功后回到接入站，并建立接入站本地登录态。

如果需要临时访问接入站本地登录页，可以访问：

/login?sso_local=1

手动选择 SSO 登录

适合接入站需要同时保留本地登录和 SSO 登录的场景。

1. 在接入站插件设置中关闭“自动跳转 SSO 登录”。
2. 到 Halo 的认证提供者配置中启用 muyin-sso。
3. 用户访问接入站 /login。
4. 用户在登录页选择“统一身份认证”。
5. 插件跳转身份中心完成登录。

手动入口由插件声明的 AuthProvider 提供：

metadata.name: muyin-sso
authenticationUrl: /apis/public.sso.muyin.site/v1alpha1/client/login

指定登录后返回地址

接入站登录入口支持 return_url 参数：

/apis/public.sso.muyin.site/v1alpha1/client/login?return_url=/archives/demo

登录完成后会回到指定地址。插件会校验返回地址，只允许本站相对路径，避免被拿去做开放重定向。这个地方不校验就等于给钓鱼链接递刀，不能省。

审计日志与清理

插件会记录接入站登录过程中的关键结果：

• 登录成功。
• 登录失败。
• Client 校验失败。
• Token 换取失败。
• UserInfo 拉取失败。
• 用户创建或绑定失败。
• 角色映射结果。

在插件控制台的“审计日志”中可以：

• 按结果筛选：success / failure
• 按 Client ID 筛选。
• 按关键词搜索 subject、email 或 message。
• 查看最近失败原因聚合。
• 按保留天数执行干跑预览或真实清理。
• 查看最近一次清理状态和清理历史。

插件设置中可以开启“自动清理过期审计日志”。默认关闭，开启后后台任务会定期按保留天数清理过期日志。

公共接口

接入站和身份中心之间主要使用以下接口。

身份中心 OAuth API：

方法	路径	说明
GET	/apis/public.sso.muyin.site/v1alpha1/oauth/authorize	OAuth 授权端点
POST	/apis/public.sso.muyin.site/v1alpha1/oauth/token	使用授权码换取 Token
GET	/apis/public.sso.muyin.site/v1alpha1/oauth/userinfo	获取中心用户信息和中心角色
GET	/apis/public.sso.muyin.site/v1alpha1/oauth/notice	授权拒绝提示页

公共辅助 API：

方法	路径	说明
GET	/apis/public.sso.muyin.site/v1alpha1/metadata	获取身份中心认证提供者元信息
GET	/apis/public.sso.muyin.site/v1alpha1/roles/list	获取身份中心可下发角色列表
GET	/apis/public.sso.muyin.site/v1alpha1/client/login	接入站发起 SSO 登录
GET	/apis/public.sso.muyin.site/v1alpha1/client/callback	接入站处理 SSO 回调

Console API 主要由插件后台页面调用，覆盖接入站管理、角色映射、用户绑定、审计日志和设置读取。开发调试时可查看：

api-docs/openapi/v3_0/ssoApis.json

常见问题

接入站登录后回调失败

优先检查身份中心中登记的 Redirect URI 是否和接入站实际地址完全一致。协议、域名、端口、路径都要一致。

标准回调路径为：

https://接入站域名/apis/public.sso.muyin.site/v1alpha1/client/callback

访问接入站 /login 没有跳转身份中心

检查接入站插件设置：

• 运行模式必须是“接入站模式”。
• 身份中心地址、Client ID、Client Secret 必须填写。
• “自动跳转 SSO 登录”必须开启。

如果你关闭了自动跳转，需要在 Halo 认证提供者中启用 muyin-sso，然后在默认登录页手动选择“统一身份认证”。

手动 SSO 登录入口没有展示

检查 Halo 认证提供者配置中是否启用了 muyin-sso。插件声明 AuthProvider 不等于 Halo 一定展示它，展示与否由 Halo 的认证提供者启用状态控制。

接入站登录页展示的名称和 Logo 不对

接入站会从身份中心 /metadata 同步认证提供者信息。请检查：

• 身份中心插件是否为“身份中心模式”。
• 接入站能否访问身份中心地址。
• 身份中心 Halo 系统基础设置中是否配置了标题、副标题、Logo、外部访问地址。
• 身份中心站点外部地址是否正确，尤其是反向代理后的 https 地址。

用户登录成功但角色不符合预期

检查三处：

1. 身份中心“中心标准角色”是否包含该用户角色。
2. 接入站“角色映射”是否配置并启用。
3. 接入站“默认本地角色”是否符合预期。

身份中心退出后接入站没有退出

这是当前设计，不是 bug。插件不做统一退出登录。身份中心退出只影响身份中心本地会话，不会强制接入站本地会话失效。

开发

本地开发依赖：

• Java 21+
• Node.js 18+
• pnpm

启动 Halo 开发服务：

./gradlew haloServer

前端开发：

cd ui
pnpm install
pnpm dev

运行测试：

./gradlew test

构建插件：

./gradlew build

生成的插件 JAR 在：

build/libs/

许可证

GPL-3.0 © Lywq