Lucky ID 上手教程

古大羊

LuckyID 是什么？

LuckyID 是集成在 Lucky 中的轻量级统一登录服务。如果你了解 Pocket ID、Authentik 或 Keycloak，就容易理解它的作用：让多个应用把登录认证交给一个统一的身份服务处理。

例如，你部署了相册、文档系统和其他支持 OIDC 的应用，接入 LuckyID 后，用户可以从这些应用进入 LuckyID 完成验证，再返回原应用。在会话有效且允许复用时，还能减少重复认证。

项目简单理解
Pocket ID以简洁和 Passkey 登录为特色的 OIDC 身份服务。
Authentik功能较全面、接入方式灵活的统一身份认证平台。
Keycloak提供较完整身份与访问管理能力的单点登录平台。
LuckyID主打轻量级，直接集成在 Lucky 中，方便已有 Lucky 用户快速为应用配置 OIDC 登录。

以上项目在“统一登录”这一用途上相似，具体功能范围并不完全相同。

LuckyID 可以复用已有的第三方认证、Passkey 和安全组本地用户，并分别指定哪些用户可以登录哪些应用，无需另外部署一套独立身份服务。

LuckyID 负责确认用户身份和是否允许登录；进入应用后的角色和操作权限，仍由应用自身管理。

一、开始前准备什么？

  • 已经掌握 Lucky 的 Web 服务和 SSL 证书功能。
  • 准备一个可以正常访问、浏览器没有证书警告的 HTTPS 域名，例如 https://id.example.com。
  • 准备至少一个可用用户。
  • 确认后端应用支持 OIDC（OpenID Connect），并允许配置自定义身份提供商。

例如，Immich、Gitea、Grafana 和 Paperless-ngx 都有相关接入说明。具体配置以所用版本的官方文档为准，这不是 LuckyID 已逐一实测的兼容清单。

只有普通账号密码登录，或只有固定的第三方登录按钮，不代表应用支持接入。请先查看应用的登录设置或官方文档。

下文域名均为示例，请替换为自己的域名。

二、配置 LuckyID 服务入口

  1. 打开 LuckyID，进入服务设置 → 服务入口。
  2. 选择一个正在运行的 HTTPS 主规则。
  3. 选择或快速创建 LuckyID 子规则，添加域名，例如 id.example.com。
  4. 设置公开服务地址（Issuer），例如 https://id.example.com。
  5. 保存设置。

公开服务地址填写实际访问的 HTTPS 地址；有外部端口时带上端口，不要包含安全入口、页面路径或查询参数。

后续应用共用这个地址，接入后尽量保持不变。服务绑定成功后，还需确认用户设备和应用服务器都能正常访问。

三、准备允许登录的用户

LuckyID 使用其他模块中已有的用户。选择你需要的一种方式即可，不必全部配置：

登录方式准备工作
第三方认证先在第三方认证模块配置好渠道和用户。
Passkey先在 Passkey 管理中配置 RP，并为用户录入凭据；在 LuckyID 登录设置中选择对应 RP，或沿用默认中转 RP。
安全组本地用户先在安全组创建用户，并启用 2FA。

确认用户处于启用状态。后续还需要在每个 LuckyID 应用中选择允许登录的用户。

使用 Passkey 时，只需选择已有 RP，不需要在 LuckyID 中重新填写 Passkey 认证入口地址。

四、添加一个应用

以接入相册为例，先打开相册程序的 OIDC 登录设置，复制它提供的登录回调地址。回调地址由应用提供，不要自行猜测。

然后在 LuckyID 点击添加应用：

  1. 填写应用名称，例如“家庭相册”。
  2. 粘贴相册提供的完整 HTTPS 回调地址，保留路径，不使用通配符。
  3. 在“登录与用户”中选择允许使用这个应用的用户。
  4. 确认应用已启用。

未选择用户时，任何用户都不能登录此应用。

直接接入相册等外部应用时，关闭“同时创建 Web OIDC 子规则”。退出后返回地址等可选项，没有需求可以留空。

五、授权与安全：一般保持默认

没有特殊需求，以下设置无需修改：

设置默认配置
允许提供的用户信息勾选 openid、profile、email
客户端认证方式client_secret_basic
要求 PKCE（S256）开启

只有接入应用明确要求其他设置，或确认有兼容问题时，再按照应用文档调整。

“每次访问此应用都重新认证”按自己的需求决定：

  • 开启：应用再次发起 LuckyID 登录认证时，需要重新验证身份。
  • 关闭：可以复用有效的 LuckyID 登录会话，减少重复认证。

这不是每次刷新应用页面都要求验证，应用自身的登录状态仍由应用管理。

六、将接入信息填回应用

保存后，打开 LuckyID 的接入信息，按相册程序的要求复制对应内容：

应用要求的内容如何填写
服务地址 / Issuer复制 LuckyID 的公开服务地址。
客户端 ID / Client ID复制当前应用的客户端 ID。
客户端密钥 / Client Secret复制当前应用生成的密钥。
自动发现地址 / Discovery URLLuckyID 自动生成，仅在应用要求时复制；不需要在 LuckyID 中另外填写。
其他字段按应用官方说明填写，从接入信息中复制对应值即可。

客户端密钥只在生成时显示一次，请及时保存。遗失后可以重置，但需同步更新应用中的密钥。

完成后，从相册的 OIDC 登录入口测试：进入 LuckyID、完成认证，再返回相册。应用是否创建账号、分配什么角色，由相册自己的设置决定。

七、Lucky Web OIDC 示例

“同时创建 Web OIDC 子规则”可以让 Lucky Web 作为客户端，方便体验和熟悉 OIDC 登录流程，不是使用 LuckyID 的必做步骤。

同一个 Lucky 的 Web 服务已经可以直接使用第三方认证、Passkey 和安全组本地用户。仅为了保护这些 Web 入口，通常无需额外绕行 LuckyID。

本教程的重点是让支持 OIDC 的外部应用使用 LuckyID 登录。入口认证保护不会自动让不支持 OIDC 的后端应用识别用户，也不一定免除它自己的登录。

八、常见问题

问题先检查什么
没有可选用户先到对应来源模块添加用户，并确认用户和模块可用。
认证成功，但提示没有权限检查是否在该应用中选择了当前用户，同时核对认证来源。
安全组用户无法登录检查用户是否启用、是否配置 2FA，以及是否被应用允许。
回调地址不匹配重新复制应用提供的完整地址，核对协议、域名、端口、路径和末尾斜杠。
浏览器能打开，但应用登录失败检查应用服务器能否访问 LuckyID、是否信任证书，以及客户端 ID 和密钥是否正确。
Passkey 登录不可用检查所选 RP、HTTPS 入口，以及用户是否已录入该 RP 下的凭据。
提示 PKCE 或客户端认证错误按应用文档检查两端配置是否一致；没有特殊需求时先使用默认设置。
密钥遗失在 LuckyID 中重置，并同步更新应用配置。
清除 LuckyID 会话后，应用仍保持登录应用有自己的登录状态，需要在应用侧退出。