Troubleshooting

Troubleshooting

本页收集 Passkey-Auth 常见问题、原因和处理方式。

Passkey 校验失败

常见原因：

• PASSKEY_ORIGIN 和浏览器地址不一致
• PASSKEY_RP_ID 配错
• 本地换了端口但没同步 origin
• 线上没有 HTTPS
• 使用了旧 passkey 或浏览器中已有测试 credential

处理：

PORT=5003 PASSKEY_ORIGIN=http://localhost:5003 .venv/bin/python -m passkey_demo.app

线上确认：

PASSKEY_RP_ID=xxxxx
PASSKEY_ORIGIN=https://auth.xxxxx

当前浏览器不支持 WebAuthn / passkey

原因：

• 浏览器版本太旧
• 非安全上下文
• 嵌入环境限制了 WebAuthn

处理：

• 使用 Chrome、Edge、Safari、Firefox 最新版
• 本地使用 localhost
• 线上使用 HTTPS

注册功能未启用

注册默认关闭。临时开启：

PASSKEY_REGISTRATION_ENABLED=true \
PORT=5003 \
PASSKEY_ORIGIN=http://localhost:5003 \
.venv/bin/python -m passkey_demo.app

生产环境不要长期开放注册。

没有找到这个用户名

原因：

• 用户未注册
• 输入用户名和注册用户名不一致
• 测试数据库换了路径

处理：

• 临时开启注册并创建用户
• 检查 PASSKEY_DATABASE
• 检查用户名大小写和空格

OAuth client 或 redirect_uri 无效

原因：

• client_id 不匹配
• redirect_uri 不在允许列表
• URL 编码前后不一致

处理：

PASSKEY_OAUTH_DEMO_CLIENT_ID=your-client-id
PASSKEY_OAUTH_DEMO_REDIRECT_URI=https://login.xxxxx/callback

注意 callback 必须完全一致，包括 scheme、host、path、端口。

invalid_state

原因：

• callback session 丢失
• 重复刷新 callback
• 从旧页面发起登录
• 多 tab 混用 state

处理：

• 重新从登录入口开始
• 确保业务站点 session cookie 正常
• 不要复用 state

invalid_grant

原因：

• authorization code 已使用
• code 已过期
• redirect_uri 和发起授权时不一致
• client id 不一致

处理：

• 重新发起 OAuth flow
• 检查 callback URL 完全匹配
• 缩短用户停留在 Auth 页面外的时间

access token 无效或已过期

原因：

• token 超过 TTL
• FLASK_SECRET_KEY 变化
• token 被篡改

处理：

• 固定 FLASK_SECRET_KEY
• 重新登录
• 检查部署是否多实例密钥不一致

challenge 不存在或已过期

原因：

• link challenge 超过 TTL
• challenge 已完成或已消费
• URL 中 challenge id 错误

处理：

• 重新从 /demo/link-login 或原网站登录页发起
• 调整 PASSKEY_OAUTH_CHALLENGE_TTL_SECONDS

challenge_result 签名无效

原因：

• URL 参数被篡改
• FLASK_SECRET_KEY 不一致
• token 来自另一个环境

处理：

• 拒绝登录
• 检查生产多实例密钥
• 重新发起 flow

passkey 用户和原网站用户名不匹配

原因：

• 原网站输入 username 为 A
• 浏览器使用了用户 B 的 passkey

处理：

• 提示用户确认账号
• 使用用户名绑定 challenge flow 限制 credential

测试失败

运行：

.venv/bin/python -m unittest discover -s tests -v

如果缺依赖：

.venv/bin/pip install -r requirements.txt

如果误用了系统 Python，可能出现：

ModuleNotFoundError: No module named 'webauthn'

请改用 .venv/bin/python。