前言
TrueNAS 上的应用陆续接入 Authentik 后,继续处理 iStoreOS 上的 Lucky。原来使用独立的管理员账号密码,希望增加 DoraTiger Auth 登录,同时保留原登录方式作为维护入口。
目前 Lucky 已升级到 3.8.1,使用原生 OIDC,HTTPS 入口继续由 Nginx Proxy Manager(NPM)管理。环境为 iStoreOS 24.10.6、Authentik 2026.8.5 和 NPM 2.14.0。
本文复用 统一认证实践(2)Authentik DoraTiger 自建流程与默认配置清理 中已经测试的登录、授权和 Provider 退出流程。关于 OIDC 应用与本地用户的关系,也可以参考 统一认证实践(5)Authentik 接入 Gitea 统一登录与账号关联。
一、认证结构
1.1 Lucky 原生 OIDC
Lucky 支持原生 OIDC。这里先将应用商店安装的核心升级到 3.8.1,再配置 Authentik 登录。
Lucky 的接入分为三个配置位置:
| 位置 | 作用 |
|---|---|
| Web 服务中的 OAuth 子规则 | 提供回调接口,保存客户端密钥,处理令牌交换 |
| 第三方认证管理 | 配置授权端点、Client ID、回调 URI,并登记授权用户 |
| 设置中的第三方后台登录 | 决定哪些已登记用户可以登录管理后台 |
只填 OIDC 参数,并不等于已经授予后台管理权限。授权用户保存成功以后,还需要加入后台登录名单。
text123456789浏览器 → NPM → Lucky 管理页面 ↓ 发起 OIDC 登录 云端 Authentik ↓ 登录、MFA、应用访问组检查 浏览器 → NPM 的 /oauth/callback → Lucky OAuth 子规则 ↓ 换取令牌、识别用户 Lucky 管理员登录名单 ↓ 管理后台
Lucky 原生处理 OIDC,不使用 Proxy Outpost。NPM 在这里负责 HTTPS 和路径转发,没有为 Lucky 配置 auth_request。浏览器和 Lucky 服务端都需要能访问云端 Authentik;后台的临时码生成还依赖配置的回调服务可达。
1.2 示例地址与命名
以下 192.0.2.0/24 地址仅用于文档示例,部署时替换为实际局域网地址。
| 对象 | 示例 |
|---|---|
| 云端身份服务 | https://auth.example.com |
| NPM 所在主机 | 192.0.2.10 |
| iStoreOS 主机 | 192.0.2.20 |
| Lucky HTTPS 入口 | https://lucky.example.com/lucky/ |
| Lucky 管理端口与安全入口 | 16601、/lucky |
| OAuth 回调监听端口 | 16602,本次选用的空闲端口 |
| 完整回调 URI | https://lucky.example.com/oauth/callback |
| Authentik 应用 Slug | istoreos-site-a-lucky |
| 应用访问组 | istoreos-site-a-lucky-admins |
site-a 用于区分部署位置,实际可替换为自己的命名。服务运行在 iStoreOS,NPM 部署在另一台主机;应用命名仍按服务所在位置划分。
二、Lucky 升级与入口准备
2.1 应用商店安装
先在 iStoreOS 应用商店安装 Lucky,装好后在管理界面停止服务,确认处于停止状态,再替换核心文件。这样可以沿用应用商店安装的管理界面和启动服务。
如果已经用过 Lucky,先导出配置,并保留旧二进制,方便需要时恢复。这台设备是 ARM64,从 Lucky 官方 Releases 下载对应架构的安装包,解压出 lucky 二进制;这里使用的版本是 3.8.1。
2.2 替换核心
通过 SSH 登录 iStoreOS,查找 Lucky 的文件位置:
bash1which lucky
这台设备返回的是:
text1/usr/bin/lucky
保持服务停止,将解压出的新版 lucky 上传到 /usr/bin/lucky,替换原文件。上传完成后,在 iStoreOS 终端赋予执行权限:
bash1chmod 755 /usr/bin/lucky
随后回到 iStoreOS 的 Lucky 管理界面,启动或重启服务。打开 Lucky 后台,确认核心版本为 3.8.1,再检查原账号、Web 服务规则和监听端口。
直接替换二进制后,应用商店或 opkg 中的包版本可能仍是旧值,运行版本以 Lucky 后台显示的核心版本为准。以后通过应用商店更新时,也留意核心文件是否被覆盖。
2.3 NPM HTTPS 管理入口
先将 lucky.example.com 解析到 NPM 主机,并准备覆盖该域名的证书。在 NPM 的“Hosts → Proxy Hosts”中新建站点:
| Details 字段 | 示例值 |
|---|---|
| Domain Names | lucky.example.com |
| Scheme | http |
| Forward Hostname / IP | 192.0.2.20 |
| Forward Port | 16601 |
| Websockets Support | 开启 |
SSL 中选择对应证书并开启 Force SSL。保存后访问 https://lucky.example.com/lucky/,应能使用原账号密码登录。
本例的 /lucky 是既有安全入口。若希望裸域名也能打开,在此站点 Advanced 中加入:
nginx123location = / { return 302 /lucky/; }
已有 Advanced 内容时合并保存,不覆盖其他规则。仅重定向根路径,不移除 Lucky 的安全入口。
三、Authentik 应用配置
3.1 应用访问组
在 Authentik 的“目录 → 组”中创建 istoreos-site-a-lucky-admins,不启用组的超级用户权限。保存后打开成员管理,将准备使用 Lucky 的现有 Authentik 管理员身份加入,例如 admin-user。
这个组控制谁能使用 Lucky 的 OIDC 应用,Lucky 自己的后台登录名单还要单独配置。两处都通过,才能使用该身份进入管理后台。
3.2 OAuth2/OpenID Connect Provider
进入“应用程序 → 提供者 → 创建”,类型选择 OAuth2/OpenID Connect:
| 字段 | 配置与作用 |
|---|---|
| Name | doratiger-istoreos-site-a-lucky |
| Authentication flow | doratiger-authentication,已有登录及 MFA 流程 |
| Authorization flow | doratiger-provider-authorization-implicit-consent,免逐次同意页面 |
| Invalidation flow | doratiger-provider-invalidation |
| Client type | Confidential,由 Lucky 服务端保存密钥 |
| Client ID / Client Secret | 使用生成值,分别保存供后续填写 |
| Grant types | Authorization code |
| Signing key | 选择已有签名证书 |
| Subject mode | 本次保留 hashed_user_id |
在 Redirect URIs 新增一条,匹配方式选 Strict,URI 类型选 Authorization,地址填写:
text1https://lucky.example.com/oauth/callback
Scope mappings 选择提供 openid、email、profile 的标准映射,保存 Provider。已经绑定身份后,不要随意修改 Subject mode,否则应用看到的用户标识可能改变。
3.3 应用与组绑定
在“应用程序 → 应用程序”中新建,选择 with existing provider:
| 字段 | 示例值 |
|---|---|
| Name | iStoreOS Site A · Lucky |
| Slug | istoreos-site-a-lucky |
| Provider | doratiger-istoreos-site-a-lucky |
| Launch URL | https://lucky.example.com/lucky/ |
保存后,在该应用的“策略/组/用户绑定”中创建绑定:选择 istoreos-site-a-lucky-admins,Order 为 0,启用绑定,Negate 关闭,然后保存。
应用建立后,发现文档地址为:
text1https://auth.example.com/application/o/istoreos-site-a-lucky/.well-known/openid-configuration
这里的路径包含应用 Slug。授权端点则为 https://auth.example.com/application/o/authorize/,两者用途不同。Authentik OAuth2 Provider
四、Lucky OAuth 回调服务
4.1 内部 TLS 证书
Lucky 的 OAuth Web 服务要求启用 TLS,因此浏览器到 NPM、NPM 到 Lucky 回调端口这两段连接都使用 HTTPS。
本次为这段内部连接使用独立自签名证书,并在 NPM 显式信任它,不关闭后端证书校验。浏览器仍使用 NPM 原有的公开证书。
在有 OpenSSL 的可信管理环境中生成证书,目录只允许管理员访问:
bash123456789umask 077 mkdir -p lucky-oidc-tls openssl req -x509 -newkey rsa:2048 -sha256 -nodes -days 1095 \ -keyout lucky-oidc-tls/oidc-key.pem \ -out lucky-oidc-tls/oidc-cert.pem \ -subj "/CN=lucky.example.com" \ -addext "subjectAltName=DNS:lucky.example.com" \ -addext "basicConstraints=critical,CA:TRUE,pathlen:0" \ -addext "extendedKeyUsage=serverAuth"
生成前替换 CN 和 SAN 中的域名。把私钥和证书通过受保护连接传入 iStoreOS 的 /etc/lucky/tls/,目录设为 700、文件设为 600。
在 Lucky“SSL 证书”中添加证书,来源选择路径,证书路径填 /etc/lucky/tls/oidc-cert.pem,私钥路径填 /etc/lucky/tls/oidc-key.pem,备注可填 DoraTiger OIDC internal TLS,保存并启用。确认域名覆盖回调地址。
另外只把公开证书复制到 NPM 持久化 /data 中的 /data/custom_ssl/lucky-oidc-ca.pem,供 Nginx 读取并校验后端。路径以容器内视角为准;不要把私钥复制到 NPM。证书到期前需要更换 Lucky 端证书与 NPM 信任文件,并重新验证登录。
4.2 Web 服务主规则
在 Lucky 的“Web 服务”中新建主规则。本文保留原有规则,单独创建回调监听:
| 字段 | 配置 |
|---|---|
| 名称 | DoraTiger Auth OIDC |
| 网络 | tcp4 |
| 监听 IP | 192.0.2.20,替换为 iStoreOS 的实际 LAN 地址 |
| 监听端口 | 16602,先确认未被占用 |
| TLS | 开启,使用前面导入的内部证书 |
| 自动防火墙操作 | 本次关闭,不为回调开放 WAN 入站 |
| 主规则开关 | 开启 |
NPM 位于另一台主机,不能把监听地址填成 127.0.0.1。本例回调端口使用 HTTPS,NPM 校验证书和域名。不要把回调端口映射到公网。
4.3 OAuth 子规则
在刚创建的主规则内添加子规则,服务类型选择 OAuth,OAuth 类型选择 OIDC:
| 字段 | 填写内容 |
|---|---|
| 前端域名/路径 | lucky.example.com/oauth/callback |
| OIDC 配置地址 | https://auth.example.com/application/o/istoreos-site-a-lucky/.well-known/openid-configuration |
| Client ID | 前面 Provider 生成的 Client ID |
| Client Secret | 同一 Provider 的 Client Secret |
| Redirect URL | https://lucky.example.com/oauth/callback |
| 接口调用代理 | 本次不启用,服务端可直接访问 Authentik |
| 子规则开关 | 开启 |
保存后返回规则列表,分别确认主规则和子规则都已启用。这里使用显式匹配域名及路径的子规则,不将 OAuth 配置填到默认规则后便结束。
客户端密钥只保存在回调服务端配置,不写入 NPM 配置或公开页面。回调接口本身不能再要求先通过第三方登录,否则授权过程无法开始。
4.4 NPM 回调路径
编辑前面的 Lucky Proxy Host,在 Custom Locations 中增加:
| 字段 | 配置 |
|---|---|
| Location | /oauth/callback |
| Scheme | https |
| Forward Hostname / IP | 192.0.2.20 |
| Forward Port | 16602 |
点击该行齿轮,填写内部 TLS 校验配置:
nginx1234proxy_ssl_server_name on; proxy_ssl_name $host; proxy_ssl_verify on; proxy_ssl_trusted_certificate /data/custom_ssl/lucky-oidc-ca.pem;
proxy_ssl_name 使握手和校验使用外部域名,而不是后端 IP;信任文件使用前面复制的公开证书。该行不增加 auth_request,不添加路径重写。保存后确认 Proxy Host 在线。
主站仍转发到 16601,只有回调路径进入 16602。浏览器看到的始终是同一个 HTTPS 域名,因此 Authentik 中注册的回调 URI 不带内部端口。
五、第三方身份与管理员登录名单
5.1 OIDC 公共参数
进入 Lucky 的“第三方认证管理”,打开配置,填写 OIDC 部分:
| 字段 | 配置 |
|---|---|
| OIDC 授权端点 | https://auth.example.com/application/o/authorize/ |
| OIDC Client ID | 与 Web 服务子规则相同 |
| OIDC 回调 URI | https://lucky.example.com/oauth/callback |
保存后,Lucky 用这组参数发起登录,回调服务使用前面配置的 Client Secret 交换令牌。
5.2 登记授权用户
仍使用原管理员账号登录 Lucky,在“第三方认证管理”中添加用户:
- 备注填写
DoraTiger Auth,类型选择OIDC,用户开关开启。 - 点击“点击授权”,允许浏览器打开授权窗口。
- 在 Authentik 中使用已加入应用访问组的身份完成登录及 MFA。
- 回到 Lucky,确认姓名等资料已返回,再保存用户。
- 返回用户列表,确认该 OIDC 记录存在且处于启用状态。
授权由本人完成,避免把其他人的 Authentik 身份误登记为后台管理员。不要复制完整回调 URL 到聊天或工单,其中可能带有短期授权码。
5.3 后台登录名单
进入 Lucky“设置”,找到第三方登录相关配置:
| 设置 | 本次选择 |
|---|---|
| 开启第三方认证登录 | 开启 |
| 允许所有第三方用户 | 关闭 |
| 第三方登录用户列表 | 选中刚保存的 OIDC 用户 |
保存后重新打开设置,确认名单中确实有该用户。API 中对应的是 EnableThirdAuthLogin、AllowAllThirdAuthUsers 和 ThirdAuthLoginUserList,最后一项引用已保存用户的 Key;从界面操作直接选择用户即可,不需要手填 Key。
名单里的用户可以管理 Lucky 后台,因此这里只加入指定管理员。
5.4 登录验证
使用无痕窗口打开 https://lucky.example.com/lucky/,在登录页选择 OIDC,完成 Authentik 授权后检查能否进入后台。
登记用户时使用的授权与后台登录是不同操作。测试后台登录时从登录页重新发起,不继续使用此前登记窗口里的临时令牌。
六、配置问题与解答
6.1 获取临时码失败
Q:点击授权后出现 get tmp code error,还没有跳转到 Authentik。
本次接口返回的具体错误为 http status code:403。检查发现 Web 服务主规则已启用,但 OAuth 子规则实际仍为禁用状态。通过 Lucky 的子规则启用操作打开后,临时码接口恢复,能够生成指向 Authentik 的授权链接。
排查时先确认主规则和子规则的开关,再检查回调域名解析、NPM 路径、监听端口及访问限制。修改后重新点击授权,检查能否跳转。
6.2 OAuth 令牌无效
Q:用户已经授权并保存,后台登录却提示 OAuth令牌无效(008)。
本次出现该提示时,后台允许名单尚为空。将已保存的 OIDC 用户加入名单,并从登录页重新发起授权后,登录成功。
如果名单已有用户仍然出现 008,继续检查临时令牌是否过期、授权和登录是否使用同一类型及配置,以及回调交换结果。
6.3 主规则正常,回调仍不可用
Q:16602 已监听,为什么回调请求还是失败?
继续检查 OAuth 子规则是否存在、是否启用,域名和路径是否匹配,以及 NPM 是否把该路径送到了 16602。修改后从登录页发起一次完整授权。
6.4 停止服务时维护命令中断
Q:升级时停止 Lucky,为什么连执行替换的 SSH 命令也中断了?
本次启动脚本通过 pgrep -f /usr/bin/lucky 匹配进程,而维护命令行恰好也包含这个完整路径,导致执行命令的进程被误匹配。随后将停止服务与二进制替换分开执行,完成升级并恢复服务。
遇到类似中断,可以先检查启动脚本如何匹配进程。
6.5 回调返回 503
Q:创建 OAuth 临时码失败,回调接口返回 503。
检查 OAuth 规则的初始化信息。如果提示“OAuth 服务需要启用 TLS”,说明内部回调服务仍在使用 HTTP。按第四节配置内部证书、启用规则 TLS,并将 NPM 回调 location 改为 HTTPS,然后重新初始化服务。
6.6 自动化登录提示密码错误
Q:浏览器可以登录,维护脚本却提示密码错误。
Lucky 3.x 前端先获取登录挑战,再加密提交登录数据,直接提交账号密码的旧版 JSON 请求会报错。维护脚本需要适配当前登录协议;更新核心后,浏览器也应刷新页面,加载新版前端资源。
七、验证与维护
以后更新核心,仍按第二节的方法停止服务、备份并替换二进制。更新后用原账号确认后台可用,再从无痕窗口走一次 OIDC 登录,同时检查非成员访问限制和退出行为。
增加管理员时,依次配置 Authentik 访问组、Lucky 用户登记和后台登录名单。撤销权限时,也要处理 Lucky 中已有的登录会话。
回退时关闭 Lucky 第三方后台登录,停用新增 OAuth Web 服务规则,并删除 NPM 回调 location,原账号密码入口可继续使用。若需要回退核心,连同该旧版本生成的配置备份一起恢复,避免旧核心读取新版配置时出错。
参考
支付宝
微信