单点登录
🔑 单点登录
Media Saber 支持四种登录方式。密码登录是基础,始终可用且永远保留;下面三种增强方式相互独立、完全平级,可以只开一个,也可以都开:
| 登录方式 | 一句话说明 | 需要准备 | 默认状态 |
|---|---|---|---|
| 🔒 密码登录 | 经典账号密码 | 无 | 始终可用 |
| 📷 扫码登录 | 已登录的手机 App 扫码,授权电脑进入 | 无需任何部署 | 默认开启 |
| 🚀 扩展快捷登录 | 已登录浏览器扩展的电脑,登录页一键进入 | 需安装 Media Saber Tools 浏览器扩展 | 默认开启 |
| 🌐 OIDC 单点登录 | 接入 Authentik / Pocket ID 等身份源,一键进入 | 需要一套身份认证服务(IdP) | 默认关闭 |
开关位置:设置 → 安全中心 → 登录方式。三个开关互不影响:关掉任何一个不影响其余方式;都关也不影响密码登录。
两种方式怎么选:
| 📷 扫码登录 | 🌐 OIDC 单点登录 | |
|---|---|---|
| 需要额外部署 | 不需要 | 需要一套 IdP |
| 配置成本 | 开个开关即用 | IdP 建应用 + 回填三项配置 |
| 适合场景 | 家用、手机上已登录 App | 已有身份源,想让多个服务统一登录 |
| 密码复杂度 / 两步验证 / Passkey | 由 Media Saber 管理 | 全部交给 IdP 管理 |
📷 扫码登录
不依赖任何外部服务,装好即用:已登录的 App 用户扫一下电脑屏幕上的二维码,即可授权该浏览器登录自己的账号。
管理员开启
设置 → 安全中心 → 登录方式 → 扫码登录卡 → 打开「启用扫码登录」并保存。
默认开启;关闭后登录页扫码入口立即隐藏、进行中的二维码立即失效。
使用流程
- 电脑浏览器打开登录页,点击右上角折角图标切换到扫码登录(下次进入登录页自动恢复上次的登录方式)
- 屏幕显示二维码(120 秒有效,边框倒计时实时可见)
- 打开手机 App → 个人中心 → 右上角扫一扫图标
- 对准二维码扫描 → App 展示确认页(登录服务器 + 待授权设备)
- 点「确认登录」→ 电脑浏览器自动进入系统
二维码过期后点「刷新二维码」重新生成;手机上点「取消本次授权」或直接退出确认页,电脑端会立即提示已在手机上取消。
授权确认页说明
| 信息 | 含义 |
|---|---|
| 登录服务器 | 发起扫码的 Media Saber 服务器地址,供核对 |
| 待授权设备 | 发起扫码的电脑设备名与类型 |
| 确认按钮倒计时 | 剩余有效时间(秒),与服务器同步 |
安全说明
- 二维码 120 秒有效、一次性使用,过期或使用后立即失效
- 确认登录只能由扫码用户本人操作,扫码后别人无法冒认
- 二维码只在其签发的服务器内有效:扫到其他实例的码无法使用(App 会提示二维码过期)
- 扫码登录的会话在设备管理中标注为「扫码登录」
同一服务器多地址混用
App 走公网域名、电脑走内网地址访问同一个服务器时,扫码授权不受影响——二维码只归属于签发它的那台服务器,与访问时使用的地址无关。
🚀 扩展快捷登录
已安装 Media Saber Tools 浏览器扩展并登录过的电脑,访问登录页时会自动出现你的头像与昵称——点一下「一键登录」,再到扩展弹窗里确认,即可进入系统,全程无需输入密码。
前提条件
- 浏览器已安装 Media Saber Tools 扩展,并在扩展中登录了你的账号
- 访问的登录页属于扩展登录的同一台 Media Saber 服务器(内网地址、公网域名、反代地址均可,认的是同一套程序)
管理员开启
设置 → 安全中心 → 登录方式 → 扩展快捷登录卡 → 打开「启用前端快速登录」并保存。
默认开启;关闭后登录页快捷登录入口立即隐藏。
使用流程
- 打开登录页 → 页面自动检测扩展,展示你的头像与昵称
- 点「一键登录」→ 扩展弹出确认窗,展示账号与发起登录的页面地址
- 核对地址无误后点「确认登录」→ 自动进入系统
- 不想用快捷登录?点「使用其他账号登录」随时回到密码表单
安全说明
- 授权必须在你自己的浏览器扩展中二次确认,网页本身无法跳过这一步;未安装扩展或扩展未登录时,登录页不会有任何变化
- 确认窗展示发起登录的页面地址,首次向某个地址授权时会特别提醒,请务必核对
- 确认请求 300 秒有效、一次性使用;多台电脑、多个浏览器各自的扩展各自确认
- 快捷登录的会话在设备管理中标注为「扩展快捷登录」,安全事件中记录来源页面地址
- 扩展登录的是哪套 Media Saber,就只为那套服务的登录页授权:测试站与生产环境同时使用不会串门
🌐 OIDC 单点登录
这是什么
如果你的 NAS 上已经跑了 Authentik / Authelia / Pocket ID / Keycloak 等身份认证服务(IdP),可以把 Media Saber 接入进去:
- 登录页出现「单点登录」按钮,点一下即可进入(IdP 会话有效时甚至不用再输密码)
- 用户账号与 IdP 身份绑定后,密码的复杂度、两步验证、Passkey 全部交给 IdP 管理
- 密码登录永远保留,两种方式随时切换;IdP 停机不影响已有会话与密码登录
没有部署 IdP?完全不用管这个功能——默认关闭,登录页与以前一模一样。想尝鲜推荐 Pocket ID:Go 单二进制、约 50MB 内存、几分钟部署。
接入三步曲
总流程:1️⃣ IdP 建应用 → 2️⃣ 复制回调地址到 IdP → 3️⃣ 回填配置测试并开启
第一步:在 IdP 中新建应用
在你的 IdP 管理界面新建一个 OIDC 应用(Authentik 叫 Provider,Pocket ID 叫 Client),类型选择 Confidential(机密客户端),需要拿到三样东西:
| 拿什么 | 在哪找 |
|---|---|
| 认证服务地址(issuer) | 以 IdP 展示的 Issuer 原样复制,不同 IdP 形态不同(有的只有域名,有的带应用路径),详见下方各 IdP 示例 |
| 客户端 ID(Client ID) | 创建应用后生成 |
| 客户端密钥(Client Secret) | 创建应用后生成 |
第二步:复制回调地址到 IdP
打开 Media Saber 的 设置 → 安全中心 → 登录方式:
- 页面会展示回调地址(按你当前访问实例的地址自动生成),点复制按钮
- 粘贴到 IdP 应用的「重定向 URI(Redirect URI)」里:
https://nas.example.com/auth/oidc/callback(电脑浏览器和手机 App 都用这一条)
⚠️ 实例有多个访问地址(域名 / IP / 内网穿透)时,回调地址以你访问登录页所用的地址为准——两条回调的域名端口部分必须与之一致。
第三步:回填配置、测试、开启
回到 设置 → 安全中心 → 登录方式 的 OIDC 卡:
- 填入认证服务地址、客户端 ID、客户端密钥
- 点「测试连接」——三项检查(可达性 / 签发者一致 / 必备端点齐全)逐条呈现结果
- 测试通过后打开「启用 OIDC 登录」并保存
立即生效,无需重启。登录页会出现单点登录按钮(文案可在「登录按钮文案」里自定义)。
主流 IdP 配置示例
每家 IdP 的管理界面差异较大,但都要做同样四件事:新建 OIDC 应用 → 填回调地址 → 拿 Client ID/Secret → 查 Issuer 地址。找不到对应入口时优先搜「Applications / Clients / Providers」菜单。
Authentik
- 管理后台 → Applications → Applications → Create:名称随意(如 Media Saber),slug 如
media_saber - 同时创建 Provider:类型选 OAuth2/OpenID Connect,Client type 选 Confidential,Redirect URI 填 Media Saber 的回调地址
- 认证服务地址:
https://<authentik地址>/application/o/<slug>/——在 Provider 详情页的 OpenID Configuration Issuer 原样复制 - Client ID / Secret 在 Provider 详情页直接复制
Authelia
编辑 configuration.yml,在 identity_providers.oidc 下新增客户端后重载配置:
identity_providers:
oidc:
clients:
- id: media_saber
description: Media Saber
secret: '<argon2 哈希>'
redirect_uris:
- https://nas.example.com/auth/oidc/callback
scopes: [openid, profile, email]- 认证服务地址:就是你的 Authelia 站点地址(如
https://auth.example.com,不带路径) - ⚠️ 4.38+ 版本配置文件里放的是口令的 argon2 哈希:用
authelia crypto hash generate argon2生成,生成时的明文口令填进 Media Saber 的「客户端密钥」
Pocket ID
- 管理界面 → OIDC Clients → Add:填名称,Callback URL 填 Media Saber 的回调地址
- 创建后直接复制 Client ID / Client Secret
- 认证服务地址:你的 Pocket ID 站点地址(如
https://idp.example.com)
Casdoor
- 管理后台 → Applications → Add:Redirect URLs 填 Media Saber 的回调地址
- 应用页面直接复制 Client ID / Client Secret
- 认证服务地址:你的 Casdoor 站点地址(如
https://door.example.com,不带路径)
ZITADEL
- 项目里新增应用:类型 Web、协议 OIDC;Auth Method 选 Basic;Redirect URI 填回调地址
- 内网 http 地址需勾选 Dev Mode(否则只接受 https 回调)
- 应用详情复制 Client ID / Client Secret
- 认证服务地址:你的 ZITADEL 实例地址(如
https://auth.example.com)
Keycloak
- 进入目标 Realm → Clients → Create client:Client type = OpenID Connect,Client ID 如
media_saber - Client authentication = On(机密客户端),Standard flow = On,Valid redirect URIs 填回调地址
- Credentials 页复制 Client Secret
- 认证服务地址:
https://<keycloak地址>/realms/<realm名>——Realm Settings → Endpoints 里 OpenID Endpoint Configuration 地址去掉/.well-known/openid-configuration的部分
群晖 SSO Server
- 套件中心安装 SSO Server → 应用程序 → 新增,协议选 OIDC
- 填应用名与 Media Saber 的回调地址,创建后获取 Client ID / Client Secret
- 认证服务地址:以 SSO Server 应用详情展示的端点信息为准(一般是 DSM 的访问地址)
- ⚠️ 需要 https 且证书可信,自签证书可能被浏览器或 IdP 拒绝
通用排错
| 现象 | 原因与处理 |
|---|---|
| 测试连接「签发者不一致」 | 认证服务地址没有原样复制 IdP 展示的 Issuer(注意尾部斜杠与路径),按提示里的「实际」值修正 |
| IdP 提示 redirect_uri 无效 | 回调地址必须与 IdP 里登记的逐字符一致(协议 / 域名 / 端口 / 路径) |
| IdP 拒绝 http 回调 | 多数 IdP 要求 https 回调(localhost 除外);给 Media Saber 配 https,或换较宽松的 IdP(Pocket ID / Casdoor) |
| 测试通过但登录失败 | 客户端密钥的正确性测试连接验证不了,检查密钥是否复制完整 |
账号是怎么对上的
用户首次点「单点登录」时,系统按下面的顺序找账号:
1. 之前绑定过 → 直接进入
2. IdP 用户名与本系统某账号同名 → 跳转"确认绑定"页,
输入该账号的当前密码完成关联(防止恶意抢注同名身份,只此一次)
3. 没有匹配 → 提示"未找到匹配账号",联系管理员在用户管理创建账号- 账号全部由管理员在用户管理创建,系统不会自动创建账号(安全考量)
- 管理员账号永远不会被自动匹配,只能由管理员本人在「我的信息 → 安全配置 → 单点登录」里主动关联
绑定管理
| 操作 | 谁在哪做 | 说明 |
|---|---|---|
| 关联 | 用户本人:我的信息 → 安全配置 → 单点登录 → 关联 OIDC 账户 | 需输入当前密码确认 |
| 解绑 | 用户本人:同一位置 → 解绑 | 需密码确认;当前登录不掉线,仅下次登录改走密码 |
| 清除 | 管理员:用户管理 → 编辑用户 → 清除绑定 | 救援场景(用户 IdP 注销又忘密码);不影响用户当前会话 |
无密码账号的关联 / 解绑按钮会置灰:先由管理员设置密码,否则解绑后谁也进不了该账号。
绑定后,「我的信息 → 安全配置」会出现绑定状态卡:
- 已绑定:显示绑定标签 + 「解绑」按钮(需密码确认)
- 未绑定:显示「关联 OIDC 账户」按钮(需密码确认,确认后跳转 IdP 完成关联)
手机 App 的单点登录
App 登录页点「OIDC 登录」后会拉起系统浏览器完成认证:
- 浏览器打开认证服务授权页,正常登录(支持 Passkey / 二步验证)
- 认证完成后浏览器展示「认证完成」页,并自动尝试拉起 Media Saber App
- 若未能自动拉起,点击页面上的「打开 App」按钮;都不行就手动切回 App——App 会自动完成登录,无需任何额外操作
浏览器打不开 / 拉起失败都不影响登录:App 会在后台自动完成登录流程。等待页还提供授权链接的一键复制,可粘贴到任意浏览器手动打开。
🖥️ 在哪看每次登录用的方式
登录成功后,你可以在以下位置看到每次登录使用的登录方式(密码登录 / OIDC / 扫码登录 / 扩展快捷登录):
| 位置 | 端 | 展示 |
|---|---|---|
| 我的信息 → 安全配置 → 设备管理 | Web | 设备名旁的标签(密码登录 / OIDC / 扫码登录 / 扩展快捷登录) |
| 安全中心 → 安全审计 | Web | 每条登录成功记录的「客户端」列内标注 |
| 个人中心 → 设备管理 | App | 设备副标题「IP · 登录方式」 |
早期产生的登录记录没有登录方式标记,随会话自然过期后自动补全。
❓ 常见问题
扫码登录需要部署什么吗?
不需要。默认开启,只要手机 App 能登录,扫一扫就行。
快捷登录为什么登录页没有出现入口?
需要同时满足四个条件:装了 Media Saber Tools 扩展、扩展里已登录、访问的是扩展登录的那台服务器、管理员开启了「前端快速登录」。任一不满足时登录页保持原样,属于正常设计。
快捷登录和扫码登录同时开会有冲突吗?
不会。两者完全独立,登录页各自有入口,想用哪个用哪个。
扫码和 OIDC 同时开会有冲突吗?
不会。两者完全独立,登录页各自有入口,想用哪个用哪个。
测试连接通过了,但登录还是失败?
测试连接不校验客户端密钥的正确性(协议限制),首次真实登录才会验证。请检查密钥是否复制完整。
提示「签发者不一致」?
认证服务地址末尾的斜杠、大小写要与 IdP 给出的完全一致,以 IdP 展示的原样复制。
IdP 挂了会怎样?
单点登录会提示「认证服务暂不可达」;密码登录、扫码登录、扩展快捷登录与已登录设备完全不受影响。
换 IdP 怎么迁移?
先关闭单点登录开关(已绑定关系保留),到用户管理逐个清除绑定(或让用户自行解绑),配置新 IdP 后重新开启即可。
🛡️ 两步验证(TOTP)
两步验证与「站点验证码」无关:站点验证码是替你填站点登录的 2FA;两步验证保护的是 Media Saber 本身的登录。
- 绑定:我的信息 → 安全配置 → 两步验证 → 启用。四步向导:验证登录密码 → 验证器 App 扫码(或手动输入密钥)→ 输入 6 位验证码 → 保存恢复代码(每张只能用一次,离开页面不再展示,请复制或下载保存)。
- 生效语义:绑定即生效——无论密码、扫码还是单点登录,登录时都需要输入验证码;想免验证码只能关闭两步验证。API Key 调用(如音箱、第三方服务)不受影响。
- 强制模式:管理员在 防护策略 开启「强制所有用户绑定」后,未绑定用户下次登录会先进入绑定向导,完成绑定才能进入。
- 换手机 / 丢失验证器:用恢复代码登录 → 安全配置 → 更换验证器重新扫码;恢复代码用尽可在安全配置重新生成(需密码)。使用恢复代码登录属于异常使用信号:会向你推送安全提醒并计入安全审计,若非本人操作请立即修改密码。
- 全部丢失:联系管理员在用户管理中「重置两步验证」,重置后重新绑定即可。
- 验证码错误处理:与密码错误同口径计入防护——连续输错会按防护策略封禁(标准档 5 次最长 7 天、严格档 3 次永久)。
推荐验证器:Microsoft Authenticator、Google Authenticator、1Password、Aegis。

