Deploy it. Connect your product. Operate it safely.

Who this is for

This handbook has two independent tracks. Operators can complete the deployment track without being application developers. Product teams can start at the developer track once a healthy OpenProof issuer exists.

Part I — Deploy and configure

1. Install the verified prebuilt runtime

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

The production installer detects supported Ubuntu/Debian and CPU architecture, resolves a release, downloads the matching prebuilt bundle and verifies its SHA-256 manifest. It does not install a compiler or silently fall back to a source build.

2. Choose the identity origin

Use a stable public hostname such as auth.example.com. This becomes the OIDC issuer and the basis for 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 and secrets

Choose local PostgreSQL for a compact single-host deployment or supply an existing postgres:// / postgresql:// URL. OpenProof applies checksummed migrations before opening the listener. The installer generates dedicated signing, encryption, pepper, audit, metrics and delivery secrets with restricted permissions.

4. Configure verification delivery

sudo openproof config delivery

5. Configure sign-in providers

Select only providers whose real credentials are ready. Google, GitHub, Microsoft, Apple, LinkedIn, Telegram, X, Ethereum and Farcaster can be configured later without reinstalling OpenProof.

sudo openproof config providers

Common placeholders such as 0, test, dummy, example and placeholder are treated as deferred configuration instead of real provider credentials.

6. Configure the protected application upstream

OpenProof gateway
    ↓
127.0.0.1:3000
    ↓
your product backend

The product backend does not need to be running for OpenProof's own identity/OAuth plane to become healthy. Change gateway/upstream settings with sudo openproof config main.

7. TLS and ingress

Use Let's Encrypt for a real public DNS name, provide an existing certificate, or terminate TLS at your own ingress/load balancer. Reserved names such as *.example.com, *.test and *.invalid default to external/deferred TLS rather than a doomed public certificate request.

8. Verify health

sudo openproof status
openproof status --full
sudo openproof doctor

When manually probing the loopback listener in trusted-proxy mode, send the 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 — Build with OpenProof

Product integration uses OAuth 2.0/OpenID Connect. Applications receive OAuth/OIDC tokens; they do not copy the OpenProof browser session cookie into their own 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. Register an application and client

An active IAL2 owner can use /admin/console or the administration API. Choose the client kind that matches your product.

2. Use Authorization Code + PKCE

Generate a high-entropy verifier, PKCE S256 challenge, random state and random nonce. At callback, validate state and returned issuer before exchanging the code.

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. Validate OIDC tokens

Do not merely decode the ID token. Verify RS256 against the issuer JWKS and validate iss, aud, exp, iat and the original nonce; also honor nbf, azp and at_hash where present.

4. Work in your language

5. Protect APIs

Register a resource with an audience and scopes, then either validate/introspect access tokens in your backend or put routes behind the OpenProof gateway. Keep product authorization narrower than “token is valid”: check audience, scope and your business policy.

6. Service-to-service

Use a service client with client_credentials. It receives an access token only — no human session and no refresh token.

Production checklist

• Real DNS and trusted HTTPS are in place.
• PostgreSQL backups exist and a restore drill has been tested.
• Verification delivery uses a real SMTP relay/webhook rather than sample hostnames.
• The initial owner is protected with MFA/TOTP.
• Provider callbacks exactly match the production identity origin.
• OAuth redirect URIs are exact and PKCE/state/nonce validation is enabled.
• ID tokens are signature/claim validated; access tokens are authorized by audience and scope.
• Refresh-token rotation is persisted atomically.
• Readiness is monitored and openproof doctor passes after infrastructure changes.
• Provider/client/database/signing secrets never enter source control, logs or AI prompts.

Reference