统一认证实践(7)Authentik 接入 Lucky 统一登录与管理员授权
创建于 2026-11-15
更新于 2026-11-16
科技
authentik
oidc
nginx
lucky
openwrt
7597 字 · 约 26 分钟

前言

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 参数,并不等于已经授予后台管理权限。授权用户保存成功以后,还需要加入后台登录名单。

text
1
2
3
4
5
6
7
8
9
浏览器 → 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 的文件位置:

bash
1
which lucky

这台设备返回的是:

text
1
/usr/bin/lucky

保持服务停止,将解压出的新版 lucky 上传到 /usr/bin/lucky,替换原文件。上传完成后,在 iStoreOS 终端赋予执行权限:

bash
1
chmod 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 中加入:

nginx
1
2
3
location = / { 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,地址填写:

text
1
https://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 关闭,然后保存。

应用建立后,发现文档地址为:

text
1
https://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 的可信管理环境中生成证书,目录只允许管理员访问:

bash
1
2
3
4
5
6
7
8
9
umask 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 校验配置:

nginx
1
2
3
4
proxy_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,在“第三方认证管理”中添加用户:

  1. 备注填写 DoraTiger Auth,类型选择 OIDC,用户开关开启。
  2. 点击“点击授权”,允许浏览器打开授权窗口。
  3. 在 Authentik 中使用已加入应用访问组的身份完成登录及 MFA。
  4. 回到 Lucky,确认姓名等资料已返回,再保存用户。
  5. 返回用户列表,确认该 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,原账号密码入口可继续使用。若需要回退核心,连同该旧版本生成的配置备份一起恢复,避免旧核心读取新版配置时出错。

参考

手机扫码阅读
本文作者: 有次元袋的 tiger
本文链接: https://www.superheaoz.top/2026/11/62481/
版权声明: 本站点所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 我的个人天地!