Quick Start

Quick Start

本页帮助你在本地运行 Passkey-Auth，并体验注册、登录、OAuth demo 和 link challenge demo。

环境要求

• Python 3.11+，推荐 Python 3.12
• 支持 WebAuthn 的现代浏览器：Chrome、Edge、Safari、Firefox
• 本地 localhost 或线上 HTTPS

WebAuthn 要求安全上下文。localhost 被浏览器视为安全上下文；线上必须使用 HTTPS。

安装依赖

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

启动服务

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

打开：

http://localhost:5003

如果换端口，PASSKEY_ORIGIN 必须同步换成浏览器实际访问地址。

注册用户

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

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

进入首页后，注册入口是低干扰隐藏入口：

• 右键点击 Logo 5 次：解锁注册面板
• Cmd/Ctrl + Shift + K：切换注册面板
• Alt + R：切换注册面板
• Esc：关闭注册面板

输入用户名，点击注册，浏览器会调用 navigator.credentials.create() 创建 passkey。

生产环境建议保持：

PASSKEY_REGISTRATION_ENABLED=false

登录用户

首页登录入口也是极简隐藏交互：

• 左键点击 Logo 5 次：发起无用户名 passkey 登录
• Cmd/Ctrl + K：发起无用户名 passkey 登录

登录时浏览器会调用：

POST /api/login/options
POST /api/login/verify

后端验证通过后，Flask session 中会保存 signed_in_user_id。

体验 OAuth Demo

http://localhost:5003/demo/oauth

流程：

1. Demo client 生成 state
2. 跳转到 /oauth/authorize
3. Auth WebUI 自动呼出 passkey
4. 成功后回跳 /demo/oauth/callback?code=...&state=...
5. 后端用 code 换 token
6. 页面展示登录结果

体验第三方站点 OAuth Demo

http://localhost:5003/demo/third-party

这是一个模拟第三方网页的完整回跳 demo，会展示 callback 参数、token response 和 userinfo response。

体验 Link Challenge Demo

http://localhost:5003/demo/link-login

流程：

1. 原网站页面输入用户名
2. 后端创建一次性 challenge
3. 浏览器跳到 /oauth/challenge/{challenge}
4. Auth WebUI 用该用户名验证 passkey
5. 成功后回跳 callback，并携带 challenge_result
6. callback 服务端校验签名、state 和一次性 challenge

运行测试

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

当前测试覆盖：

• 配置默认值和环境变量覆盖
• 注册入口默认关闭
• OAuth 第三方回跳
• link challenge 创建、完成、callback 校验、重放拒绝

常见本地问题

现象	原因	处理
Passkey 校验失败	PASSKEY_ORIGIN 和浏览器 URL 不一致	同步端口和 origin
浏览器没有弹 passkey	非安全上下文或浏览器不支持	使用 localhost 或 HTTPS
找不到用户名	尚未注册该用户	临时开启注册并创建用户
callback state 失败	session 丢失或重复打开 callback	重新从 demo 首页发起