デプロイする。製品を接続する。安全に運用する。

対象読者

この handbook には 2 つの独立した track があります。operator は application developer でなくても deployment track を完了できます。製品チームは健全な OpenProof issuer が用意できた時点で developer track から始められます。

Part I — デプロイと設定

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 では local 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 は実際の provider credential ではなく deferred configuration として扱われます。

6. 保護対象 application upstream を設定

OpenProof gateway
    ↓
127.0.0.1:3000
    ↓
your product backend

OpenProof 自身の identity/OAuth plane が healthy になるために製品 backend が稼働している必要はありません。gateway/upstream 設定は次で変更します: sudo openproof config main.

7. TLS と ingress

実在する公開 DNS 名では Let’s Encrypt を使用するか、既存 certificate を提供するか、自前の ingress/load balancer で TLS terminate します。次のような reserved name は *.example.com, *.test and *.invalid 失敗する公開 certificate request の代わりに external/deferred TLS がデフォルトになります。

8. ヘルスを確認

sudo openproof status
openproof status --full
sudo openproof doctor

trusted-proxy mode で loopback listener を手動確認する場合は、local forwarded client address を送信してください:

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

{"status":"ok"}

Part II — OpenProof で開発

製品統合では OAuth 2.0/OpenID Connect を使用します。Application は 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 では code exchange 前に state と返された issuer を検証してください。

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 を検証

ID token を decode するだけでは不十分です。RS256 を issuer JWKS に対して検証し、 iss, aud, exp, iat および元の nonce。また、 nbf, azp and at_hash が存在する場合は検証してください。

4. 使用言語で実装

5. API を保護

audience と scope を持つ resource を登録し、backend で access token を validate/introspect するか route を OpenProof gateway の背後に置いてください。製品 authorization は「token が有効」より厳密にし、audience、scope、business policy を確認します。

6. Service 間

次の service client で client_credentials. 受け取るのは access token のみで、人間の session や refresh token はありません。

本番チェックリスト

• 実際の DNS と信頼できる HTTPS が用意されています。
• PostgreSQL backup があり、restore drill がテスト済みです。
• verification delivery は sample hostname ではなく実際の SMTP relay/webhook を使用しています。
• 初期 owner は MFA/TOTP で保護されています。
• provider callback は production identity origin と完全一致しています。
• OAuth redirect URI は正確で、PKCE/state/nonce validation が有効です。
• ID token は signature/claim validation 済みで、access token は audience と scope に基づいて authorize されます。
• Refresh-token rotation は原子的に永続化されます。
• readiness を監視し、 openproof doctor インフラ変更後も成功します。
• provider/client/database/signing secret を source control、log、AI prompt に入れないでください。

リファレンス