Lucky Passkey 上手教程

本教程帮助你理解 RP ID、允许的来源地址、对外录入地址，以及原生与中转 Passkey 的区别，并完成首次配置。

一、开始之前

本教程默认你已经掌握 Lucky 的 Web 服务和 SSL 证书功能，能够配置域名访问、HTTPS 服务及证书。

如果你是首次使用 Lucky，请先熟悉这两项功能，再继续配置 Passkey。

你需要准备一个长期使用的 HTTPS 认证入口，例如：

https://auth.example.com

请提前确认：

• 域名已经正确解析。
• 已配置 HTTPS Web 服务和有效证书。
• 用户设备能够正常访问该地址，浏览器没有证书警告。
• 如使用端口映射或反向代理，相关配置已经完成。

添加 RP 配置不会自动完成域名解析、证书申请或端口转发。

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

二、Passkey 是什么？

Passkey（通行密钥）是一种通过设备指纹、面容、解锁 PIN 或安全密钥完成身份验证的方式。

首次使用时，需要为用户录入 Passkey。以后登录时，由浏览器和设备调用已保存的凭据完成验证。

配置流程为：

准备 HTTPS 域名 → 配置认证服务 → 添加 RP → 配置中转入口 → 为用户录入 Passkey → 验证登录。

三、原生 Passkey 与中转 Passkey 有什么区别？

Lucky 会根据当前访问环境，自动判断能否直接使用原生 Passkey；不满足直接认证条件时，会回退到中转 Passkey 模式。

原生 Passkey：直接在当前页面完成认证

日常部署中，需要通过具有有效、受信任证书的 HTTPS 域名地址访问，并且：

• 当前页面域名符合 RP ID 的范围。
• 当前页面来源已被该 RP 的允许来源规则覆盖。
• 浏览器和设备支持 Passkey。

中转 Passkey：通过专用 HTTPS 入口完成认证

通过 HTTP、IP 地址访问，或者当前地址不满足原生 Passkey 条件时，Lucky 会通过配置好的中转认证入口完成验证。

自动回退的前提是已经配置可用的“默认中转登录入口”。如果没有配置中转入口，当前环境又不支持直接认证，就无法通过 Passkey 完成登录。

中转模式仍要求浏览器和设备支持 Passkey，并能正常访问认证入口。它不能绕过认证入口的浏览器证书检查。

以上针对日常部署环境。localhost 等本机开发环境存在安全上下文例外，不作为本教程的常规配置方式。

四、先理解三个关键配置

下面这组配置展示了一个常见用法：以 example.com 为 RP ID，允许其可信子域名使用原生 Passkey，并使用 auth.example.com 作为录入和中转入口。

这里的 https://*.example.com 是允许来源的匹配规则，不是可以直接打开的网址。对外录入地址必须填写具体地址，不能使用通配符。

1. RP 和 RP ID 是什么？

RP 是 Relying Party 的缩写，通常译为“依赖方”。这里可以理解为接收并验证 Passkey 的服务，也就是你的 Lucky。

RP ID 是这个服务在 Passkey 体系中的域名标识。

录入 Passkey 时，凭据会绑定到 RP ID。以后认证时，浏览器会检查网页域名是否符合该 RP ID 的要求，避免无关网站使用这份凭据。

RP ID 只填写域名，不能包含协议、端口、路径或通配符。

也不能将 com、co.uk 等公共后缀作为 RP ID。

2. 允许的来源地址是什么？

允许的来源地址，就是允许通过哪些访问地址打开页面时，使用这条 RP 配置进行原生 Passkey 注册和认证。

例如，RP ID 为：

example.com

允许的来源地址为：

https://*.example.com

表示允许以下来源使用这条 RP 配置：

https://auth.example.com
https://lucky.example.com
https://admin.example.com
https://a.b.example.com

即使多个域名最终访问的是同一台服务器、同一个 Lucky，也需要被允许来源规则覆盖。

最重要的约束：来源地址中的域名必须与 RP ID 相同，或者属于 RP ID 的子域名。

例如，RP ID 为 example.com 时：

如果 RP ID 填写的是 auth.example.com，则：

• 可以使用 auth.example.com。
• 可以使用 login.auth.example.com 等下级子域名。
• 不能使用上级域名 example.com。
• 不能使用同级域名 admin.example.com。

希望多个可信子域名使用同一条 RP 配置时，应在首次录入前，选择合适的共同上级域名作为 RP ID，例如 example.com。

域名符合 RP ID 范围，不代表已经自动获准使用；仍需被允许来源规则覆盖。

3. 来源地址如何填写？

来源地址（Origin）的格式是：

协议://域名[:端口]

匹配时会同时检查协议、域名和端口，不包含页面路径。

填写时注意：

• 不要包含 Lucky 安全入口，例如 /666。
• 不要包含其他路径、查询参数或 # 后面的内容。
• 非默认端口必须填写，例如 :8443。
• 标准 HTTPS 的 443 端口可以省略。
• 填写浏览器实际访问页面的来源，不是服务器内部地址或后端 API 地址。
• 多条规则每行填写一条。

例如，服务器内部监听 16601，用户通过 https://auth.example.com:8443 访问，应填写外部访问端口 8443。

允许来源也不是访问者的 IP 白名单。

4. 通配符有哪些限制？

规则：

https://*.example.com

匹配一个或多个层级的子域名，但：

• 不包含 https://example.com 本身。
• 不匹配 :8443 等非默认端口。
• 不匹配 HTTP 来源。
• 不能突破 RP ID 的域名范围。

如果需要同时允许主域名、默认 HTTPS 端口的子域名，以及使用 8443 端口的子域名，可以填写：

https://example.com
https://*.example.com
https://*.example.com:8443

只添加实际需要的规则。

只有相关子域名都受你控制并且可信时，才使用通配符。如果只需要少数固定地址，建议逐条填写精确来源：

https://auth.example.com
https://lucky.example.com
https://admin.example.com:8443

通配符只适用于允许来源，RP ID 和对外录入地址都不能填写通配符。

5. 对外录入地址有什么作用？

这个地址同时承担两项用途：

• 录入 Passkey：用户打开一次性录入链接，在这里创建凭据。
• 中转 Passkey 认证：该 RP 被选为“默认中转登录入口”后，用户通过这里完成中转身份验证。

例如：

https://auth.example.com

填写对外录入地址并不代表自动启用中转登录，还需要选择对应 RP 作为默认中转登录入口。

对外录入地址必须：

• 使用有效且受浏览器信任的 HTTPS 证书。
• 能被需要录入或中转登录的用户设备访问。
• 对应共享 Passkey 认证服务的域名。
• 域名与 RP ID 相同，或属于 RP ID 的子域名。
• 被该 RP 的允许来源规则覆盖。
• 使用具体来源地址，不包含通配符、路径或查询参数。

例如，https://auth.example.com 已被 https://*.example.com 覆盖，就无需再重复添加精确来源。

请将它作为长期稳定的认证入口维护。地址无法访问或证书失效，会影响录入，也会影响使用该入口的中转登录。

五、配置共享 Passkey 认证服务

在 Passkey 设置的“服务入口”中：

1. 选择一个正在运行的 HTTPS 主规则。
2. 选择或快速创建“Passkey 认证服务”子规则。
3. 将认证入口域名，例如 auth.example.com，添加为该子规则的前端域名。
4. 保存共享服务绑定。

多条 RP 配置可以共用一个 Passkey 认证服务子规则。

后续增加其他 RP 时，将对应认证入口域名补充到该子规则，同时配置好解析、证书和网络访问。

允许来源中的通配符不会自动为 Web 服务添加域名，也不会自动配置通配符证书。

“服务绑定可用”只表示配置关系符合要求，不代表公网解析、证书和端口转发已经全部验证通过。

六、添加 RP 配置

根据自己的访问方式，选择下面的方案。

方案 A：同一主域名下，多个可信子域名使用原生 Passkey

假设你拥有 example.com，并希望其下多个可信子域名使用同一条 RP 配置：

这组配置允许 auth.example.com、lucky.example.com、admin.example.com 等子域名，在标准 HTTPS 端口下使用该 RP。

如果实际通过 https://lucky.example.com:8443 访问，需要额外添加：

https://lucky.example.com:8443

或者在确实需要覆盖所有可信子域名的该端口时，添加：

https://*.example.com:8443

RP 显示名称用于帮助用户识别服务，不决定凭据的域名范围。

方案 B：只使用一个固定认证域名

如果只准备通过 auth.example.com 录入和认证，可以缩小范围：

这条 RP 也可以作为中转入口，供通过 HTTP、IP 或其他地址访问的用户完成 Passkey 认证。

请在首次录入前确定 RP ID。修改 RP ID 后，已有 Passkey 不会自动转换到新 RP ID，通常需要重新录入。

方案 C：有多个不同主域名

如果你同时拥有 example.com 和 example.net，希望两者分别提供原生 Passkey 认证，可以添加多条 RP 配置：

上例假设相应子域名均受你控制并可信；否则请使用精确来源。

将两个认证入口域名添加到共享 Passkey 认证服务子规则，并分别配置解析和证书。

需要注意：

• 多个不同主域名可以分别建立多条 RP 配置。
• 不能把 example.net 加入 RP ID 为 example.com 的配置，期待它直接使用原生 Passkey。
• 同一个本地用户可以在不同 RP 下分别录入凭据。
• 凭据按 RP ID 区分，不会因属于同一个 Lucky 或同一个用户而自动跨 RP 通用。

如果其他访问域名只需要使用中转登录，不要求在自身页面直接进行原生认证，也可以共用一个已配置好的中转入口，无需仅为中转登录逐个创建 RP。

七、设置默认中转登录入口

在“中转登录”中，选择一条已启用、服务入口可用的 RP，作为默认中转登录入口。

Lucky 将使用这条 RP 的对外录入地址进行中转认证。后台和 Web 服务共用这个入口，不会根据 RP 排列顺序自动切换。

清空默认中转登录入口后，中转登录会停用，但不影响已配置的凭据录入功能。

中转时应该允许哪个来源？

例如，用户通过：

http://192.168.1.10:16601

访问 Lucky，然后通过：

https://auth.example.com

完成中转认证。

实际执行 Passkey 验证的是 https://auth.example.com，因此应确保它符合所选 RP ID，并被允许来源覆盖。例如：

RP ID：example.com
允许的来源地址：https://*.example.com

不需要将前面的 HTTP/IP 访问地址加入该 RP 的允许来源。

“允许中转服务证书过期”有什么作用？

该开关默认开启，仅影响 Lucky 后端连接中转入口时的证书校验：

• 允许服务器证书过期。
• 仍校验域名、信任链、签名和用途。
• 证书尚未生效或 CA 证书过期时，仍会拒绝连接。

它不能绕过浏览器证书检查。用户浏览器进行 Passkey 录入或中转认证，仍然需要可信、有效的 HTTPS 证书。

“检测后端连接”检查 Lucky 后端到认证入口的连接和 TLS 状态，不代表用户设备一定能访问，也不代表完整登录流程已经验证通过。

八、为用户录入 Passkey

完成服务与 RP 配置后：

1. 新增或选择一个本地用户。
2. 在凭据操作中选择对应的 RP。
3. 创建一次性录入链接。
4. 在准备保存 Passkey 的设备上打开链接，或扫描二维码。
5. 按浏览器和系统提示完成录入。
6. 返回管理页面，确认凭据已经添加。

一次性录入链接能够为指定用户添加凭据，请只交给该用户本人。链接只能使用一次，会自动过期，Lucky 重启后也会失效。

如果有多条 RP，请确认选择的是用户实际需要使用的 RP。需要通过默认中转入口登录的用户，应持有该入口所用 RP 下的凭据。

九、验证一次实际登录

确认以下条件后，尝试登录：

• 对应 RP 已启用。
• 用户已启用，并允许登录。
• 用户具有相应入口的访问权限。
• 用户已录入本次认证所用 RP 下的 Passkey。
• 直接认证时，当前来源符合 RP ID 和允许来源要求。
• 中转认证时，默认中转入口可用。

录入成功不等于自动获得所有入口的访问权限。相应的用户允许名单和权限设置仍然生效。

建议分别验证日常使用的 HTTPS 域名入口，以及需要中转的 HTTP 或 IP 入口。

十、常见问题