Kurun. Ürününüzü bağlayın. Güvenle işletin.

Bu el kitabı kimler için

Bu el kitabında iki bağımsız yol vardır. Operatörler uygulama geliştiricisi olmadan deployment yolunu tamamlayabilir. Ürün ekipleri sağlıklı bir OpenProof issuer oluştuğunda geliştirici yolundan başlayabilir.

Bölüm I — Kurulum ve yapılandırma

1. Doğrulanmış hazır runtime’ı kurun

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

Production installer desteklenen Ubuntu/Debian ve CPU mimarisini algılar, release’i belirler, eşleşen hazır bundle’ı indirir ve SHA-256 manifestini doğrular. Compiler kurmaz ve sessizce source build’e dönmez.

2. Identity origin seçin

Şunun gibi stabil, herkese açık bir hostname kullanın: auth.example.com. Bu değer OIDC issuer ve provider callback’lerinin temeli olur.

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 ve secret’lar

Kompakt tek host deployment için yerel PostgreSQL seçin veya mevcut bir postgres:// / postgresql:// URL sağlayın. OpenProof listener’ı açmadan önce checksum’lu migration’ları uygular. Installer kısıtlı izinlerle signing, encryption, pepper, audit, metrics ve delivery secret’ları üretir.

4. Verification delivery’yi yapılandırın

sudo openproof config delivery

5. Giriş provider’larını yapılandırın

Yalnızca gerçek credential’ları hazır olan provider’ları seçin. Google, GitHub, Microsoft, Apple, LinkedIn, Telegram, X, Ethereum ve Farcaster daha sonra OpenProof yeniden kurulmadan yapılandırılabilir.

sudo openproof config providers

Şu gibi yaygın placeholder’lar 0, test, dummy, example and placeholder gerçek provider credential’ı yerine ertelenmiş yapılandırma olarak değerlendirilir.

6. Korumalı application upstream’ini yapılandırın

OpenProof gateway
    ↓
127.0.0.1:3000
    ↓
your product backend

OpenProof’un kendi identity/OAuth plane’inin sağlıklı olması için ürün backend’inin çalışması gerekmez. Gateway/upstream ayarlarını şu komutla değiştirin: sudo openproof config main.

7. TLS ve ingress

Gerçek herkese açık DNS adı için Let’s Encrypt kullanın, mevcut sertifika sağlayın veya TLS’i kendi ingress/load balancer’ınızda sonlandırın. Şu gibi rezerve adlar: *.example.com, *.test and *.invalid başarısız olacak public certificate isteği yerine varsayılan olarak external/deferred TLS kullanır.

8. Sağlığı doğrulayın

sudo openproof status
openproof status --full
sudo openproof doctor

Trusted-proxy modunda loopback listener’ı manuel test ederken yerel forwarded client adresini gönderin:

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

{"status":"ok"}

Bölüm II — OpenProof ile geliştirme

Ürün entegrasyonu OAuth 2.0/OpenID Connect kullanır. Uygulamalar OAuth/OIDC token’ları alır; OpenProof tarayıcı session cookie’sini kendi domain’lerine kopyalamaz.

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 ve client kaydedin

Aktif bir IAL2 owner şunları kullanabilir: /admin/console veya administration API kullanabilir. Ürününüzle eşleşen client türünü seçin.

2. Authorization Code + PKCE kullanın

Yüksek entropy’li verifier, PKCE S256 challenge ve rastgele state ve rastgele nonce. üretin. Callback sırasında code exchange öncesinde state ve dönen issuer değerini doğrulayın.

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’larını doğrulayın

ID token’ını yalnızca decode etmeyin. RS256’yı issuer JWKS’ye karşı doğrulayın ve iss, aud, exp, iat ve özgün nonce; ayrıca nbf, azp and at_hash bulunduğunda dikkate alın.

4. Kendi dilinizde çalışın

5. API’leri koruyun

Audience ve scope’larla bir resource kaydedin; ardından access token’ları backend’inizde validate/introspect edin veya route’ları OpenProof gateway arkasına koyun. Ürün authorization’ını “token geçerli” ifadesinden daha dar tutun: audience, scope ve business policy’nizi kontrol edin.

6. Servisten servise

Bir service client ile client_credentials. Yalnızca access token alır — insan session’ı ve refresh token yoktur.

Production kontrol listesi

• Gerçek DNS ve güvenilir HTTPS hazır.
• PostgreSQL backup’ları mevcut ve restore denemesi test edildi.
• Verification delivery örnek hostname’ler yerine gerçek SMTP relay/webhook kullanıyor.
• İlk owner MFA/TOTP ile korunuyor.
• Provider callback’leri production identity origin ile tam eşleşiyor.
• OAuth redirect URI’leri kesin ve PKCE/state/nonce doğrulaması etkin.
• ID token’ları signature/claim açısından doğrulanıyor; access token’lar audience ve scope ile authorize ediliyor.
• Refresh-token rotation atomik olarak persist ediliyor.
• Readiness izlenir ve openproof doctor altyapı değişikliklerinden sonra başarıyla geçiyor.
• Provider/client/database/signing secret’ları source control, log veya AI prompt’larına asla girmez.

Referans