统一认证实践(6)Authentik 接入 Immich 统一登录与账号关联
创建于 2026-11-15
更新于 2026-11-16
科技
truenas
docker
immich
authentik
oidc
6112 字 · 约 21 分钟

前言

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 文档

text
1
2
3
4
5
6
7
网页/手机 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 名称。对应发现文档为:

text
1
https://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 原账号绑定

不要一开始就在无痕窗口尝试创建新账号。先用原密码进入已有照片库,再执行:

  1. 打开“用户设置 → OAuth”。
  2. 点击“关联账号/Link account”。
  3. 跳转到 DoraTiger Auth 后,确认使用的是准备绑定的 Authentik 用户,完成登录和 MFA。
  4. 返回 Immich,确认 OAuth 关联成功,当前仍为原账号。
  5. 检查原照片库及管理员入口是否正常。

关联由已登录的 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 开启并保存。其他登录选项保持不变。

本次最终状态为:

text
1
2
3
4
OAuth Enabled: true Auto Register: true Auto Launch: false Password Login: true

保存后重新打开设置,检查自动注册和密码登录开关。

5.2 新账号开通顺序

后续用户的处理方式与 Gitea 一致:

  1. 管理员在 Authentik 邀请或创建用户。
  2. 将用户加入 truenas-immich-users。
  3. 用户打开 Immich,选择 DoraTiger Auth。
  4. Authentik 完成认证和应用授权,Immich 收到身份后按自动注册配置创建用户。
  5. 用户开始管理自己的照片;需要共享时,再配置 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、完整授权跳转及真实登录。旧版本接口路径或网上示例不可直接作为当前服务的故障判据。

参考

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