Configuration and Deployment

Configuration and Deployment

本页说明配置项、环境变量、部署建议和生产前检查。

配置入口

配置集中在：

passkey_demo/config.py

AppConfig 字段和值写在一起，环境变量通过 from_env() 覆盖。ServerConfig 管开发服务器启动参数。

环境变量表

变量	默认值	说明
FLASK_SECRET_KEY	随机生成	Flask session、access token、challenge result 签名密钥
PASSKEY_RP_ID	localhost	WebAuthn RP ID
PASSKEY_RP_NAME	Passkey Demo	passkey 弹窗显示名称
PASSKEY_ORIGIN	空	WebAuthn expected origin，空时使用当前请求 origin
REGISTER_UNLOCK_TTL_SECONDS	120	注册面板解锁有效期
PASSKEY_REGISTRATION_ENABLED	false	是否允许注册
PASSKEY_SERVER_API_TOKEN	空	服务端 session verify API token
PASSKEY_OAUTH_DEMO_CLIENT_ID	passkey-demo-client	demo OAuth client id
PASSKEY_OAUTH_DEMO_CLIENT_SECRET	passkey-demo-secret	demo OAuth client secret
PASSKEY_OAUTH_DEMO_REDIRECT_URI	空	额外允许的 callback
PASSKEY_OAUTH_CODE_TTL_SECONDS	300	authorization code 有效期
PASSKEY_OAUTH_ACCESS_TOKEN_TTL_SECONDS	3600	access token 有效期
PASSKEY_OAUTH_CHALLENGE_TTL_SECONDS	300	link challenge 有效期
PASSKEY_DATABASE	instance/passkeys.sqlite3	SQLite 数据库路径
HOST	localhost	开发服务器监听地址
PORT	5003	开发服务器端口
FLASK_DEBUG	false	Flask debug 模式

本地开发配置

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

需要注册用户：

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

生产配置示例

FLASK_SECRET_KEY=<strong-random-secret>
PASSKEY_RP_ID=xxxxx
PASSKEY_ORIGIN=https://auth.xxxxx
PASSKEY_RP_NAME="Passkey Auth"
PASSKEY_DATABASE=/var/lib/passkey-auth/passkeys.sqlite3
PASSKEY_REGISTRATION_ENABLED=false
PASSKEY_SERVER_API_TOKEN=<strong-server-token>
PASSKEY_OAUTH_DEMO_CLIENT_ID=<client-id>
PASSKEY_OAUTH_DEMO_CLIENT_SECRET=<client-secret>
PASSKEY_OAUTH_DEMO_REDIRECT_URI=https://login.xxxxx/callback
PASSKEY_OAUTH_CODE_TTL_SECONDS=300
PASSKEY_OAUTH_ACCESS_TOKEN_TTL_SECONDS=3600
PASSKEY_OAUTH_CHALLENGE_TTL_SECONDS=300

RP ID 和 Origin

如果 Auth WebUI 部署在：

https://auth.xxxxx

推荐：

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

注意：

• PASSKEY_ORIGIN 必须等于浏览器地址栏里的 scheme + host + port。
• 如果本地端口变化，必须同步修改 PASSKEY_ORIGIN。
• 线上必须 HTTPS。

反向代理

Nginx 示例：

location / {
    proxy_pass http://127.0.0.1:5003;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

建议显式设置 PASSKEY_ORIGIN，减少代理 Host 推断导致的 WebAuthn origin mismatch。

数据库

默认 SQLite：

instance/passkeys.sqlite3

生产建议：

• 指定持久化路径：PASSKEY_DATABASE=/var/lib/passkey-auth/passkeys.sqlite3
• 定期备份
• 不要提交数据库文件
• 如果并发量增加，迁移到 PostgreSQL 或 MySQL，并保留相同数据模型

多 client 扩展

当前 _oauth_client(...) 是 demo client 配置。生产多业务系统建议改为数据库或配置文件：

oauth_clients
- client_id
- client_secret_hash
- client_name
- redirect_uris
- allowed_flows
- created_at
- disabled_at

不要明文存储生产 client secret。

生产前检查

• HTTPS 已启用
• FLASK_SECRET_KEY 固定且强随机
• PASSKEY_RP_ID 和 PASSKEY_ORIGIN 正确
• PASSKEY_REGISTRATION_ENABLED=false
• PASSKEY_OAUTH_DEMO_CLIENT_SECRET 已替换
• PASSKEY_SERVER_API_TOKEN 已替换
• callback 使用精确白名单
• 数据库路径持久化
• 测试全部通过
• 没有提交 .env、SQLite、.venv、.DS_Store
• 已选择 LICENSE