استقرار دهید. محصول را متصل کنید. ایمن بهره‌برداری کنید.

این راهنما برای چه کسانی است

این راهنما دو مسیر مستقل دارد. اپراتورها می‌توانند مسیر استقرار را بدون توسعه‌دهندهٔ برنامه بودن تکمیل کنند. تیم‌های محصول نیز پس از آماده شدن یک issuer سالم OpenProof می‌توانند از مسیر توسعه‌دهنده شروع کنند.

بخش اول — استقرار و پیکربندی

۱. runtime ازپیش‌ساخته و تأییدشده را نصب کنید

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

نصب‌کنندهٔ محیط عملیاتی Ubuntu/Debian و معماری CPU پشتیبانی‌شده را تشخیص می‌دهد، release مناسب را پیدا می‌کند، bundle ازپیش‌ساختهٔ منطبق را دانلود و manifest نوع SHA-256 آن را بررسی می‌کند. این نصب‌کننده compiler نصب نمی‌کند و به‌صورت پنهانی به build از source برنمی‌گردد.

۲. identity origin را انتخاب کنید

از یک hostname عمومی و پایدار مانند auth.example.comاستفاده کنید. این hostname به OIDC issuer و مبنای callbackهای provider تبدیل می‌شود.

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

۳. PostgreSQL و secrets

برای استقرار فشرده روی یک میزبان، PostgreSQL محلی را انتخاب کنید یا یک postgres:// / postgresql:// URL موجود وارد کنید. OpenProof پیش از باز کردن listener، migrationهای checksummed را اعمال می‌کند. نصب‌کننده secrets اختصاصی signing، encryption، pepper، audit، metrics و delivery را با permission محدود ایجاد می‌کند.

۴. delivery مربوط به verification را پیکربندی کنید

sudo openproof config delivery

۵. providerهای ورود را پیکربندی کنید

فقط providerهایی را انتخاب کنید که credential واقعی آن‌ها آماده است. Google، GitHub، Microsoft، Apple، LinkedIn، Telegram، X، Ethereum و Farcaster را می‌توان بعداً بدون نصب مجدد OpenProof پیکربندی کرد.

sudo openproof config providers

placeholderهای متداول مانند 0, test, dummy, example و placeholder به‌عنوان پیکربندی deferred در نظر گرفته می‌شوند، نه credential واقعی provider.

۶. upstream برنامهٔ محافظت‌شده را پیکربندی کنید

OpenProof gateway
    ↓
127.0.0.1:3000
    ↓
your product backend

برای سالم شدن plane مربوط به identity/OAuth خود OpenProof لازم نیست بک‌اند محصول در حال اجرا باشد. تنظیمات gateway/upstream را با sudo openproof config main.

۷. TLS و ingress

برای یک نام DNS عمومی واقعی از Let’s Encrypt استفاده کنید، certificate موجود ارائه دهید یا TLS را در ingress/load balancer خود terminate کنید. نام‌های رزروشده مانند *.example.com, *.test و *.invalid به‌جای درخواست ناموفق certificate عمومی، به‌صورت پیش‌فرض external/deferred TLS در نظر گرفته می‌شوند.

۸. سلامت را بررسی کنید

sudo openproof status
openproof status --full
sudo openproof doctor

هنگام بررسی دستی listener روی loopback در trusted-proxy mode، آدرس local forwarded client را ارسال کنید:

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 دریافت می‌کنند؛ کوکی نشست مرورگر OpenProof به دامنهٔ برنامه کپی نمی‌شود.

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

۱. application و client را ثبت کنید

یک owner فعال IAL2 می‌تواند از /admin/console یا API مدیریت استفاده کند. نوع client متناسب با محصول را انتخاب کنید.

۲. از Authorization Code + PKCE استفاده کنید

یک verifier با entropy بالا، challenge نوع PKCE S256 و مقدار تصادفی state و مقدار تصادفی nonceتولید کنید. در callback، پیش از exchange کردن code، 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'

۳. توکن‌های OIDC را اعتبارسنجی کنید

ID token را فقط decode نکنید. RS256 را در برابر JWKS متعلق به issuer بررسی و iss, aud, exp, iat و مقدار اصلی nonce؛ همچنین nbf, azp و at_hash را در صورت وجود رعایت کنید.

۴. با زبان موردنظر خود کار کنید

۵. از APIها محافظت کنید

یک resource با audience و scopeها ثبت کنید، سپس access tokenها را در بک‌اند validate/introspect کنید یا routeها را پشت OpenProof gateway قرار دهید. authorization محصول باید دقیق‌تر از «توکن معتبر است» باشد: audience، scope و policy کسب‌وکار را بررسی کنید.

۶. سرویس‌به‌سرویس

از یک service client با client_credentialsاستفاده کنید. فقط access token دریافت می‌شود؛ نشست انسانی و refresh token وجود ندارد.

چک‌لیست محیط عملیاتی

• DNS واقعی و HTTPS قابل‌اعتماد برقرار است.
• backupهای PostgreSQL وجود دارند و فرایند restore به‌صورت آزمایشی تست شده است.
• delivery مربوط به verification از SMTP relay/webhook واقعی استفاده می‌کند، نه hostname نمونه.
• owner اولیه با MFA/TOTP محافظت می‌شود.
• callbackهای provider دقیقاً با identity origin محیط عملیاتی مطابقت دارند.
• OAuth redirect URIها دقیق هستند و اعتبارسنجی PKCE/state/nonce فعال است.
• ID tokenها از نظر signature/claim اعتبارسنجی می‌شوند؛ access tokenها بر اساس audience و scope مجاز می‌شوند.
• rotation مربوط به refresh token به‌صورت atomic ذخیره می‌شود.
• readiness مانیتور می‌شود و openproof doctor پس از تغییرات زیرساخت با موفقیت اجرا می‌شود.
• secrets مربوط به provider/client/database/signing هرگز وارد source control، log یا promptهای AI نمی‌شوند.

مرجع