完成部署，连接产品，并安全运行。

适用对象

该 handbook 包含两个相互独立的流程。operator 无需成为应用开发者即可完成 deployment track；当健康的 OpenProof issuer 可用后，产品团队可直接从 developer track 开始。

第一部分 — 部署与配置

1. 安装已验证的预构建 runtime

curl -fsSL https://genyleap.com/install/openproof | sudo sh

production installer 会检测支持的 Ubuntu/Debian 与 CPU architecture，解析 release，下载匹配的预构建 bundle，并验证其 SHA-256 manifest。它不会安装 compiler，也不会静默回退到 source build。

2. 选择 identity origin

使用稳定的公开 hostname，例如 auth.example.com.。它会成为 OIDC issuer，也是 provider callback 的基础。

issuer:   https://auth.example.com
callback: https://auth.example.com/auth/federated/callback
discovery:https://auth.example.com/.well-known/openid-configuration
jwks:     https://auth.example.com/.well-known/jwks.json

3. PostgreSQL 与 secrets

对于紧凑的 single-host deployment，可选择本地 PostgreSQL，或提供现有 postgres:// / postgresql:// URL。OpenProof 会在打开 listener 前应用带 checksum 的 migration。Installer 会以受限 permission 生成专用 signing、encryption、pepper、audit、metrics 与 delivery secret。

4. 配置 verification delivery

sudo openproof config delivery

5. 配置 sign-in provider

仅选择真实 credential 已准备好的 provider。Google、GitHub、Microsoft、Apple、LinkedIn、Telegram、X、Ethereum 与 Farcaster 都可以稍后配置，而无需重新安装 OpenProof。

sudo openproof config providers

常见 placeholder，例如 0, test, dummy, example and placeholder 会被视为 deferred configuration，而不是真实 provider credential。

6. 配置受保护 application upstream

OpenProof gateway
    ↓
127.0.0.1:3000
    ↓
your product backend

OpenProof 自身的 identity/OAuth plane 变为健康状态并不要求产品 backend 正在运行。使用以下命令修改 gateway/upstream 设置： sudo openproof config main.

7. TLS 与 ingress

真实公开 DNS 名可以使用 Let’s Encrypt，或者提供现有 certificate，或在自己的 ingress/load balancer 终止 TLS。以下保留名称 *.example.com, *.test and *.invalid 默认使用 external/deferred TLS，而不是发起注定失败的公开 certificate 请求。

8. 验证健康状态

sudo openproof status
openproof status --full
sudo openproof doctor

在 trusted-proxy mode 下手动探测 loopback listener 时，请发送本地 forwarded client address：

curl -fsS \
  -H 'X-Forwarded-For: 127.0.0.1' \
  http://127.0.0.1:18443/health/ready

{"status":"ok"}

第二部分 — 使用 OpenProof 开发

产品集成使用 OAuth 2.0/OpenID Connect。应用接收 OAuth/OIDC token，而不会把 OpenProof browser session cookie 复制到自己的 domain。

User
  ↓
your app
  ↓ redirect
OpenProof /oauth/authorize
  ↓ authenticate
your callback ?code=...&state=...&iss=...
  ↓ code + PKCE verifier
OpenProof /oauth/token
  ↓
access_token + id_token + optional refresh_token

1. 注册 application 与 client

活跃的 IAL2 owner 可以使用 /admin/console 或 administration API。请选择与产品匹配的 client kind。

2. 使用 Authorization Code + PKCE

生成高 entropy verifier、PKCE S256 challenge，以及随机 state 以及随机 nonce.。在 callback 中，先验证 state 与返回的 issuer，再进行 code exchange。

curl --fail-with-body https://auth.example.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'code=AUTHORIZATION_CODE' \
  --data-urlencode 'redirect_uri=https://app.example.com/oauth/callback' \
  --data-urlencode 'code_verifier=PKCE_VERIFIER'

3. 验证 OIDC token

不要只 decode ID token。应使用 issuer JWKS 验证 RS256，并验证 iss, aud, exp, iat 以及原始 nonce；同时还应处理 nbf, azp and at_hash （如存在）。

4. 使用你的语言开发

5. 保护 API

注册带 audience 与 scope 的 resource，然后在 backend 中 validate/introspect access token，或将 route 放在 OpenProof gateway 后方。产品 authorization 必须比“token 有效”更严格：检查 audience、scope 与业务 policy。

6. Service 间

使用 service client，并使用 client_credentials.。它只会获得 access token，不会有用户 session 或 refresh token。

生产检查清单

• 真实 DNS 与可信 HTTPS 已就绪。
• PostgreSQL backup 已存在，并已测试 restore drill。
• verification delivery 使用真实 SMTP relay/webhook，而不是示例 hostname。
• 初始 owner 已使用 MFA/TOTP 保护。
• provider callback 与 production identity origin 完全一致。
• OAuth redirect URI 精确无误，并已启用 PKCE/state/nonce validation。
• ID token 已通过 signature/claim validation；access token 根据 audience 与 scope 进行 authorization。
• Refresh-token rotation 以原子方式持久化。
• readiness 会被监控，并且 openproof doctor 在基础设施变更后通过检查。
• provider/client/database/signing secret 永远不会进入 source control、log 或 AI prompt。

参考