배포하고, 제품을 연결하고, 안전하게 운영하세요.

대상 독자

이 handbook에는 두 개의 독립된 track이 있습니다. operator는 애플리케이션 개발자가 아니어도 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 요청 대신 기본적으로 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를 사용합니다. 애플리케이션은 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하는 데 그치지 마세요. issuer JWKS를 기준으로 RS256을 검증하고 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는 예시 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은 원자적으로 persist됩니다.
• readiness를 모니터링하고 openproof doctor 인프라 변경 후에도 통과합니다.
• provider/client/database/signing secret은 source control, log, AI prompt에 절대 들어가지 않습니다.

레퍼런스