Bereitstellen. Produkt anbinden. Sicher betreiben.

Für wen dieses Handbuch gedacht ist

Dieses Handbuch hat zwei unabhängige Pfade. Operatoren können den Bereitstellungspfad abschließen, ohne Anwendungsentwickler zu sein. Produktteams können mit dem Entwicklerpfad beginnen, sobald ein funktionsfähiger OpenProof-Issuer vorhanden ist.

Teil I — Bereitstellen und konfigurieren

1. Verifizierte vorgefertigte Runtime installieren

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

Der Produktions-Installer erkennt unterstütztes Ubuntu/Debian und die CPU-Architektur, löst ein Release auf, lädt das passende vorgefertigte Bundle herunter und prüft dessen SHA-256-Manifest. Er installiert keinen Compiler und fällt nicht stillschweigend auf einen Source-Build zurück.

2. Identity Origin wählen

Verwenden Sie einen stabilen öffentlichen Hostnamen wie auth.example.com. Dieser wird zum OIDC-Issuer und zur Grundlage für Provider-Callbacks.

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 und Secrets

Wählen Sie lokales PostgreSQL für eine kompakte Single-Host-Bereitstellung oder geben Sie eine vorhandene postgres:// / postgresql:// URL an. OpenProof wendet vor dem Öffnen des Listeners prüfsummenbasierte Migrationen an. Der Installer erzeugt dedizierte Signing-, Encryption-, Pepper-, Audit-, Metrics- und Delivery-Secrets mit eingeschränkten Berechtigungen.

4. Verifizierungszustellung konfigurieren

sudo openproof config delivery

5. Anmeldeprovider konfigurieren

Wählen Sie nur Provider aus, deren reale Zugangsdaten bereitstehen. Google, GitHub, Microsoft, Apple, LinkedIn, Telegram, X, Ethereum und Farcaster können später ohne Neuinstallation von OpenProof konfiguriert werden.

sudo openproof config providers

Übliche Platzhalter wie 0, test, dummy, example and placeholder werden als aufgeschobene Konfiguration statt als echte Provider-Zugangsdaten behandelt.

6. Geschützten Application-Upstream konfigurieren

OpenProof gateway
    ↓
127.0.0.1:3000
    ↓
your product backend

Das Produkt-Backend muss nicht laufen, damit die eigene Identity-/OAuth-Ebene von OpenProof gesund wird. Ändern Sie Gateway-/Upstream-Einstellungen mit sudo openproof config main.

7. TLS und Ingress

Verwenden Sie Let’s Encrypt für einen echten öffentlichen DNS-Namen, stellen Sie ein vorhandenes Zertifikat bereit oder terminieren Sie TLS an Ihrem eigenen Ingress/Load-Balancer. Reservierte Namen wie *.example.com, *.test and *.invalid verwenden standardmäßig externes/aufgeschobenes TLS statt eines zum Scheitern verurteilten öffentlichen Zertifikatsantrags.

8. Zustand prüfen

sudo openproof status
openproof status --full
sudo openproof doctor

Senden Sie beim manuellen Prüfen des Loopback-Listeners im Trusted-Proxy-Modus die lokal weitergeleitete Client-Adresse:

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

{"status":"ok"}

Teil II — Mit OpenProof entwickeln

Die Produktintegration verwendet OAuth 2.0/OpenID Connect. Anwendungen erhalten OAuth/OIDC-Token; sie kopieren das OpenProof-Browser-Sitzungscookie nicht in ihre eigene 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. Anwendung und Client registrieren

Ein aktiver IAL2-Owner kann /admin/console oder die Administrations-API verwenden. Wählen Sie den Client-Typ, der zu Ihrem Produkt passt.

2. Authorization Code + PKCE verwenden

Erzeugen Sie einen Verifier mit hoher Entropie, eine PKCE-S256-Challenge und zufällige Werte für state und einen zufälligen nonce. Validieren Sie beim Callback State und den zurückgegebenen Issuer, bevor der Code ausgetauscht wird.

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 validieren

Dekodieren Sie das ID-Token nicht nur. Prüfen Sie RS256 gegen das JWKS des Issuers und validieren Sie iss, aud, exp, iat und den ursprünglichen nonce; berücksichtigen Sie außerdem nbf, azp and at_hash sofern vorhanden.

4. In Ihrer Sprache arbeiten

5. APIs schützen

Registrieren Sie eine Resource mit Audience und Scopes. Validieren bzw. introspektieren Sie anschließend Access-Token im Backend oder platzieren Sie Routen hinter dem OpenProof-Gateway. Produkt-Autorisierung muss enger sein als „Token ist gültig“: Prüfen Sie Audience, Scope und Ihre Geschäftsrichtlinie.

6. Service-to-Service

Verwenden Sie einen service Client mit client_credentials. Er erhält ausschließlich ein Access Token — keine menschliche Sitzung und kein Refresh Token.

Produktions-Checkliste

• Echtes DNS und vertrauenswürdiges HTTPS sind eingerichtet.
• PostgreSQL-Backups sind vorhanden und ein Restore-Test wurde durchgeführt.
• Die Verifizierungszustellung verwendet ein echtes SMTP-Relay/einen Webhook statt Beispiel-Hostnamen.
• Der initiale Owner ist mit MFA/TOTP geschützt.
• Provider-Callbacks entsprechen exakt dem produktiven Identity Origin.
• OAuth-Redirect-URIs sind exakt und PKCE-/State-/Nonce-Validierung ist aktiviert.
• ID-Token werden auf Signatur/Claims validiert; Access-Token werden anhand von Audience und Scope autorisiert.
• Refresh-Token-Rotation wird atomar persistiert.
• Readiness wird überwacht und openproof doctor besteht nach Infrastrukturänderungen.
• Provider-/Client-/Datenbank-/Signing-Secrets gelangen niemals in Source Control, Logs oder AI-Prompts.

Referenz