Passkey 登录

目标

说明站点使用 Passkey 登录时，在远程浏览器环境中的准备事项和操作建议。

前置条件

• 目标站点支持 Passkey、WebAuthn 或安全密钥登录。
• 用户已在目标站点绑定 Passkey。
• 远程浏览器访问链路支持目标站点所需的认证交互。

操作步骤

1. 在站点配置中确认 URL、域名和登录流程正确。
2. 用户通过前端进入目标站点。
3. 在目标站点选择 Passkey 登录。
4. 按浏览器提示完成认证。
5. 登录成功后，确认远程浏览器进入目标业务页面。

目标站点 Passkey 本地测试

Passkey 与浏览器看到的域名强绑定。测试目标站点 Passkey 登录时，不能只通过服务器 IP 或临时转发地址访问，需要让本地浏览器以目标站点域名发起 HTTPS 访问，并让该域名被系统识别为可代理的业务域名。

建议按以下步骤准备：

1. 在管理平台进入“系统设置 > 域名管理”，点击“添加域名”，添加目标站点域名，例如 login.example.com。该页面对应管理端 Domains.vue，用于维护允许系统处理的业务域名。
2. 在本地电脑安装 Caddy 根证书。内网或测试环境使用 Caddy 内部证书时，浏览器必须信任该根证书，否则 Passkey/WebAuthn 会因为 HTTPS 不可信而无法正常完成认证。安装方法见内网证书安装。
3. 在本地 hosts 中添加目标站点域名解析，将目标站点域名指向部署服务器 IP。例如：

<SERVER_IP> login.example.com

Windows 通常修改 C:\Windows\System32\drivers\etc\hosts，macOS/Linux 通常修改 /etc/hosts。修改后建议重新打开浏览器，必要时清理 DNS 缓存。

4. 使用目标站点域名访问测试地址：

https://<目标站点域名>/?saas=<...>&_d=<目标站点地址>

其中：

参数	说明
<目标站点域名>	已在“域名管理”中添加，并已在本地 hosts 指向部署服务器 IP 的域名
saas	系统生成或业务场景需要携带的 SaaS 访问参数
_d	目标站点地址，通常为需要实际打开的目标站点 URL

完成以上准备后，浏览器地址栏中的 origin 会是目标站点域名，并且 HTTPS 证书被本地信任，才具备进行目标站点 Passkey 登录测试的基础条件。

结果验证

• 目标站点识别 Passkey 登录方式。
• 用户能完成认证并进入站点。
• 认证失败时，站点提示与远程浏览器日志可用于排查。

常见问题

• Passkey 还是一个alpha阶段的功能，有些站点可能会登录失败。