前言
Gitea 接入以后,继续处理 TrueNAS 上的 Immich。照片库已经在使用,接入时需要保留原账号和照片归属,同时让网页与手机 App 都能通过 DoraTiger Auth 登录。后续内部用户加入,也希望沿用已有的身份账号,在首次登录时自动创建 Immich 用户。
本次使用 Immich 3.3.6、TrueNAS 25.10.8 和 Authentik 2026.8.5。配置顺序是先关闭自动注册,绑定原账号并测试网页、手机登录,确认正常后再开启新用户自动注册。
登录、授权和 Provider 退出流程沿用 统一认证实践(2)Authentik DoraTiger 自建流程与默认配置清理。OIDC 的基本关系可以参考 统一认证实践(5)Authentik 接入 Gitea 统一登录与账号关联。
一、认证结构
1.1 原生 OIDC 与前哨
Immich 原生支持 OIDC,接入结构与 Gitea 相同:浏览器或手机发起登录,云端 Authentik 完成认证,Immich 服务端处理回调、获取令牌,并找到对应的本地用户。Immich OAuth 文档
text1234567网页/手机 App → Immich → 云端 Authentik 登录与 MFA ↓ 应用访问组检查 ↓ 返回 Immich 登录回调 ↓ 使用已有账号关联,或首次登录创建用户
TrueNAS 上已有的 Proxy Outpost 不参与这次接入。它服务于 qBittorrent 的 Forward Auth 方案;Immich 能自己处理 OIDC,因此无需再在 NPM 上添加认证子请求。NPM 保留原来的 HTTPS 反代,照片上传和浏览仍走 Immich,业务数据不通过云端 Authentik 转发。
浏览器、手机和 Immich 服务端都需要能访问云端认证服务。前两者负责交互登录,后者需要读取发现文档、获取令牌和验证身份。配置前也要从 Immich 容器中检查发现文档是否可达。
1.2 账号与照片归属
Authentik 管理登录身份,Immich 用户记录管理照片归属、相册、共享关系及应用权限。已有用户应关联外部身份后继续使用原记录;自动注册面向尚未建立对应关系的新身份。
先从原账号发起关联,后续 OAuth 登录才能继续进入原来的照片库,避免误建新账号。
1.3 对象名称
| 对象或地址 | 示例值 |
|---|---|
| Authentik 域名 | https://auth.example.com |
| Immich 域名 | https://photos.example.com |
| 应用名称 | TrueNAS · Immich |
| 应用 Slug | truenas-immich |
| Provider 名称 | doratiger-truenas-immich |
| 访问组 | truenas-immich-users |
| 登录按钮 | DoraTiger Auth |
后台名称包含部署位置,便于区分以后新增的实例。登录按钮仅用于显示;与 Gitea 不同,Immich 的回调路径不会因为按钮改名而改变。
二、Authentik 应用与访问组
2.1 创建访问组
在 Authentik 管理界面进入“目录 → 组”,创建 truenas-immich-users,保存后在成员列表加入准备关联原 Immich 管理员的 Authentik 用户。
不要启用组的超级用户权限。该组只表示允许进入这个 Immich 的认证入口,不负责授予 Immich 管理员身份,也不自动共享其他人的照片。
2.2 创建 OAuth2/OpenID Connect Provider
进入“应用程序 → 提供者 → 创建”,类型选择 OAuth2/OpenID Connect,按下面的字段填写:
| 字段 | 本次配置 |
|---|---|
| Name | doratiger-truenas-immich |
| Authentication flow | doratiger-authentication,复用登录与 MFA |
| Authorization flow | doratiger-provider-authorization-implicit-consent,免额外同意页面 |
| Invalidation flow | doratiger-provider-invalidation,复用提供者退出流程 |
| Client type | Confidential |
| Client ID / Client Secret | 保留生成值,稍后填写到 Immich |
| Grant types | 启用 Authorization code |
| Signing key | 选择已有签名证书 |
| Subject mode | 保留本次使用的 hashed_user_id |
前文 Gitea 曾因为 grant_types 为空导致授权请求被拒绝,这里明确启用授权码模式。免确认授权流程中的 implicit-consent 是流程用途,不是要求使用 OAuth Implicit grant。
Scope mappings 选择提供 openid、email、profile 的标准映射。保存后记录 Client ID 和 Client Secret,后面填写到 Immich。
2.3 三个回调地址
在 Redirect URIs 中分别添加以下三条,匹配方式均为 Strict,类型均为 Authorization:Authentik 接入说明
| 地址 | 用途 |
|---|---|
https://photos.example.com/auth/login |
网页登录完成后返回 Immich |
https://photos.example.com/user-settings |
从原用户设置发起 OAuth 账号关联 |
app.immich:///oauth-callback |
手机 App 接收认证结果 |
前两条替换为自己的 HTTPS 域名,第三条保留原样。app.immich:///oauth-callback 是 App 的自定义 URI,不是服务器地址,其中的三个斜杠不能按普通 HTTPS 地址自行修改。
有多个访问域名时,分别添加对应的严格匹配回调。
2.4 创建应用并绑定组
进入“应用程序 → 应用程序”,选择 with existing provider 创建应用:
| 字段 | 填写内容 |
|---|---|
| Name | TrueNAS · Immich |
| Slug | truenas-immich |
| Provider | doratiger-truenas-immich |
| Launch URL | https://photos.example.com/ |
保存后打开应用详情,在策略/组/用户绑定中创建组绑定,选择 truenas-immich-users,Order 为 0,启用绑定,Negate 关闭。
保存后,访问组才会作为这个应用的授权条件生效。
三、Immich OAuth 配置
3.1 配置入口
使用原 Immich 管理员账号登录,进入“管理 → 设置 → OAuth 认证”。先确认密码登录仍开启,再填写:
| 字段 | 本次填写 |
|---|---|
| Enabled | 开启 OAuth |
| Issuer URL | https://auth.example.com/application/o/truenas-immich/ |
| Client ID | Authentik Provider 的 Client ID |
| Client Secret | 同一 Provider 的 Client Secret |
| Scope | openid email profile |
| Button Text | DoraTiger Auth |
| Auto Register | 暂时关闭,原账号关联完成后再开启 |
| Auto Launch | 关闭,保留登录方式选择 |
| Mobile Redirect URI Override | 关闭 |
| Mobile Redirect URI | 留空 |
Issuer URL 中使用应用 Slug truenas-immich,不是 Provider 名称。对应发现文档为:
text1https://auth.example.com/application/o/truenas-immich/.well-known/openid-configuration
本次令牌端点认证方式保留 client_secret_post,ID Token 签名算法为 RS256,Userinfo 签名算法为 none,请求超时为 30 秒,未开启不安全请求。高级字段按安装版本核对,不要为了连通而关闭 HTTPS 校验。
保存后,用无痕窗口查看登录页,应出现 DoraTiger Auth 按钮,同时仍能使用原账号密码登录。
3.2 配置保存与备份
这里通过管理界面保存系统配置,数据写入数据库。使用 IMMICH_CONFIG_FILE 管理配置的实例,需要修改对应文件。
操作前先备份 Immich 与 Authentik 数据库,再从管理界面保存 OAuth 配置。已有账号通过下文的“关联账号”操作绑定。
数据库备份应保存在受限目录中,因为其中可能包含客户端凭据、用户和其他应用资料。照片原文件仍需已有的数据备份,数据库备份不能代替照片备份。
四、已有账号关联与登录验证
4.1 原账号绑定
不要一开始就在无痕窗口尝试创建新账号。先用原密码进入已有照片库,再执行:
- 打开“用户设置 → OAuth”。
- 点击“关联账号/Link account”。
- 跳转到 DoraTiger Auth 后,确认使用的是准备绑定的 Authentik 用户,完成登录和 MFA。
- 返回 Immich,确认 OAuth 关联成功,当前仍为原账号。
- 检查原照片库及管理员入口是否正常。
关联由已登录的 Immich 用户发起,再确认 Authentik 身份,两边的用户名和邮箱可以不同。
关联后仍进入原来的管理员账号,照片和视频也都还在。
4.2 网页登录
用无痕窗口打开 https://photos.example.com,点击 DoraTiger Auth,完成认证后应返回原照片库。Authentik 中已有会话时,可能不再重复要求输入密码,应用访问组的检查仍会执行。
关联完成后,原账号已能通过 OAuth 登录网页并访问照片库。
4.3 手机端登录
在 Immich App 中填写原服务器地址,选择 OAuth 登录。系统浏览器完成认证后,应通过 app.immich:///oauth-callback 返回 App,再显示对应用户的照片库。
手机端使用默认回调就能登录。只有自定义 scheme 无法使用时,才需要考虑 Mobile Redirect URI Override。
登录后可以再上传一张测试照片,检查手机备份。
五、新用户自动注册与访问组
5.1 开启自动建号
原账号在网页与手机端登录都正常后,返回“管理 → 设置 → OAuth 认证”,将 Auto Register 开启并保存。其他登录选项保持不变。
本次最终状态为:
text1234OAuth Enabled: true Auto Register: true Auto Launch: false Password Login: true
保存后重新打开设置,检查自动注册和密码登录开关。
5.2 新账号开通顺序
后续用户的处理方式与 Gitea 一致:
- 管理员在 Authentik 邀请或创建用户。
- 将用户加入
truenas-immich-users。 - 用户打开 Immich,选择 DoraTiger Auth。
- Authentik 完成认证和应用授权,Immich 收到身份后按自动注册配置创建用户。
- 用户开始管理自己的照片;需要共享时,再配置 Immich 的共享关系。
这属于首次登录自动建号,不是后台同步。仅创建 Authentik 用户,或仅把用户加入访问组,都不会立即在 Immich 中出现新账号。
这里使用默认角色规则:原管理员保留权限,新注册账号为普通用户,各自管理自己的照片。需要额外分配管理员权限时,再单独配置。
5.3 未加入访问组的效果
未加入 truenas-immich-users 的用户,即使能正常登录 Authentik,仍会在 Immich 的应用授权环节被拒绝。通常会看到无权访问的提示,具体页面文案随流程和版本而异。
授权被拒绝后,Immich 收不到成功的认证结果,也就不会创建用户。
| 状态 | 预期处理 |
|---|---|
| 有 Authentik 账号,但不是访问组成员 | 可登录身份中心,访问 Immich 的授权被拒绝 |
| 已加入组,尚无对应 Immich 用户 | 首次成功登录时自动建号 |
| 已加入组,已有正确账号关联 | 登录原 Immich 用户 |
| 原 Immich 账号尚未关联 | 先从原账号设置完成关联,避免误建或账号冲突 |
自动注册与访问组分别处理不同问题:前者决定 Immich 是否创建用户,后者决定这个身份能否使用该 OIDC 应用。不能只开注册开关而省略组绑定。
5.4 配额与撤销访问
存储配额继续在 Immich 中管理。开放给其他用户前,按 NAS 的可用容量分配配额。
从访问组移除用户,会限制其后续通过该应用发起的认证,但不会自动删除 Immich 用户、照片或共享关系,也不保证已有 App 会话立即失效。保留的密码登录、API Key 等认证方式需要在 Immich 侧分别处理。
停用账号时,还要在 Immich 中处理已有会话、API Key 和照片交接。
六、验证与维护
6.1 登录检查
原账号的网页和手机登录已经正常,管理员权限和照片归属保留。自动注册也已开启,新用户首次建号、非成员拒绝和跨应用退出还留待后续测试。
测试新用户时,使用一个没有现有 Immich 关联的身份,先验证未入组时拒绝,再入组完成首次登录,确认只创建一个普通账号,并检查其不能直接看到原用户的私人照片。第二次登录应回到同一用户,而不是重复建号。
6.2 回退
如果只需暂停新用户注册,在 Immich OAuth 设置中关闭 Auto Register,已有账号关联仍保留。
如果需要暂停整个 OIDC 登录,确认密码登录可用后关闭 OAuth。不要删除原用户、重建照片库或直接恢复整库备份;恢复整库可能覆盖接入后产生的新照片元数据、账号及其他修改。
修改 Provider、Client Secret 或回调地址后,重新验证网页和手机端。已经绑定的 Subject 配置应保持稳定,避免用户标识变化后关联不到原账号。
七、配置问题与解答
7.1 已绑定账号,但新用户不能登录
Q:原管理员登录成功,是不是代表自动注册已经开启?
不是同一个设置。本次首次接入时明确关闭 Auto Register,先完成原账号绑定,网页与手机测试成功后才开启。遇到新用户无法进入,分别检查应用访问组、自动注册开关以及用户资料冲突,不要只重复修改客户端密钥。
7.2 手机回调是否填写 HTTPS 地址
Q:为什么手机回调不是 Immich 的域名?
app.immich:///oauth-callback 用于让系统把认证结果交回 App。网页登录与账号关联使用 HTTPS 回调,三者用途不同。本次三个地址分别登记,手机测试成功,无需追加回调跳转服务。
7.3 前哨是否需要增加 Immich
Q:TrueNAS 已部署前哨,是否还要把 Immich 加入前哨应用列表?
不需要。本例由 Immich 直接与云端 OAuth2/OpenID Connect Provider 通信,前哨中的 Proxy 应用列表不参与。给 NPM 再加 Forward Auth 还可能影响手机 API 请求,不能把网页前置认证当作原生 OIDC 的必需步骤。
7.4 配置检查接口返回 404
Q:访问 /api/system-config/public 返回 404,是否代表 OAuth 配置失败?
本次这个路径在当前版本返回 404,因此没有把它作为有效配置检查入口。实际改用运行版本的配置读取方法核对开关,并测试 /api/oauth/authorize、完整授权跳转及真实登录。旧版本接口路径或网上示例不可直接作为当前服务的故障判据。
参考
支付宝
微信