[Infra Ops] 써드파티 API와 공공 인프라 연계 실무

# 외부 기관에서 확인해야 할 정보
# - 운영 서버 IP/도메인 및 포트
# - 프로토콜 (HTTP/HTTPS, TCP)
# - 인증 방식 (API Key, 클라이언트 인증서, IP 화이트리스트)
# - 테스트 환경 계정/엔드포인트 별도 제공 여부

# 방화벽 오픈 요청 시 필요한 정보
# - 출발지: 우리 운영 서버 IP (WAS 서버들)
# - 목적지: 외부 API 서버 IP 또는 도메인
# - 목적지 포트: 443 (HTTPS), 80 (HTTP), 22 (SFTP) 등
# - 방향: Outbound (내부 → 외부)
# - 프로토콜: TCP

# -- 1단계: TCP 연결 가능 여부 (nc) --
# 방화벽이 열렸는지, 서버가 포트를 열고 있는지 확인
nc -zv external-api.example.com 443
# 성공: Connection to external-api.example.com 443 port [tcp/https] succeeded!
# 실패: nc: connect to external-api.example.com port 443 (tcp) failed: Connection refused
#      → 방화벽 미오픈 또는 서버가 포트를 닫은 상태

# 1단계 실패 시 → 방화벽 오픈 요청 또는 외부 기관에 서버 상태 확인
# 1단계 성공 시 → 2단계 진행

# -- 2단계: SSL/TLS 인증서 검증 (openssl s_client) --
# SSL 핸드셰이크가 정상인지, 인증서 체인이 완전한지 확인
openssl s_client -connect external-api.example.com:443 2>/dev/null \
  | grep -E "Verify return code|issuer|subject|expire"
# 정상: Verify return code: 0 (ok)
# 실패 예: Verify return code: 21 (unable to verify the first certificate)
#         → 중간 CA 인증서 누락, truststore 업데이트 필요

# 서버 인증서 만료일 확인
openssl s_client -connect external-api.example.com:443 2>/dev/null \
  | openssl x509 -noout -dates
# notAfter=Nov 30 23:59:59 2026 GMT

# 2단계 실패 시 → SSL 인증서 문제 (아래 TroubleCase 참고)
# 2단계 성공 시 → 3단계 진행

# -- 3단계: HTTP 응답 확인 (curl) --
# 실제 API 응답 코드와 내용 확인
curl -m 10 -s -o /dev/null -w "%{http_code}" https://external-api.example.com/health
# 200: 정상
# 403: IP 화이트리스트 미등록 또는 API Key 오류
# 401: 인증 실패
# 000: 연결 자체 실패 (1단계로 되돌아가기)

# 응답 본문까지 확인
curl -m 10 -s https://external-api.example.com/health
# {"status":"ok"} 또는 에러 메시지

# 응답 시간 측정 (timeout 설정 기준)
curl -m 30 -w "\nDNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTotal: %{time_total}s\n" \
  -s -o /dev/null https://external-api.example.com/health

# JKS 파일 내용 확인 (어떤 인증서가 들어있는지)
keytool -list -keystore client-cert.jks -storepass 비밀번호
# 출력: Alias name, Entry type, Certificate fingerprint

# PEM 인증서를 JKS로 변환 (외부 기관에서 PEM 발급 시)
# 1단계: PEM + 개인키 → PKCS12 변환
openssl pkcs12 -export \
  -in client.crt \
  -inkey client.key \
  -out client.p12 \
  -name myalias \
  -passout pass:임시비밀번호

# 2단계: PKCS12 → JKS 변환
keytool -importkeystore \
  -srckeystore client.p12 \
  -srcstoretype PKCS12 \
  -srcstorepass 임시비밀번호 \
  -destkeystore client.jks \
  -deststoretype JKS \
  -deststorepass jks비밀번호

# TrustStore에 외부 CA 인증서 추가 (사설 CA 또는 중간 CA)
keytool -importcert \
  -keystore truststore.jks \
  -storepass trustpass \
  -alias external-ca \
  -file external-ca.crt \
  -noprompt

# Java 앱 실행 시 JKS 사용 설정
java \
  -Djavax.net.ssl.keyStore=/etc/ssl/client.jks \
  -Djavax.net.ssl.keyStorePassword=비밀번호 \
  -Djavax.net.ssl.trustStore=/etc/ssl/truststore.jks \
  -Djavax.net.ssl.trustStorePassword=trustpass \
  -jar app.jar

[우리 서버]  callExternalApi(payload)
   │
   ① 요청 준비           (URL·메서드·헤더 / 인증 토큰·API 키·서명 부착)
   │
   ② 호출               (connectTimeout 내 TCP·TLS 수립 → 요청 전송)
   │
   ③ 응답 처리           (상태코드 분기 2xx/4xx/5xx, 페이징·부분 결과 조립)
   │    → readTimeout 내 본문 수신
   │
   ④ 재시도·레이트리밋 대응  (5xx·타임아웃만 backoff 재시도, 429는 Retry-After 존중)
   │
   ⑤ 장애 격리           (연속 실패율 임계 초과 → Circuit Breaker OPEN → 즉시 fallback)
   ▼
[우리 서버]  결과 반환 또는 fallback (외부 장애가 우리로 전파되지 않음)

# 잘못된 예: timeout 없음 → 스레드 무기한 대기
curl https://external-api.example.com/payment

# 올바른 예: 적절한 timeout 설정
curl -m 10 https://external-api.example.com/payment
# 10초 내 응답 없으면 포기

# Java HttpClient timeout 설정 예시
# connection-timeout: 3초 (TCP 연결 수립)
# read-timeout: 10초 (응답 본문 수신)

# application.yml
resilience4j:
  circuitbreaker:
    instances:
      smsService:
        failure-rate-threshold: 50          # 50% 실패 시 OPEN
        wait-duration-in-open-state: 30s    # 30초 후 HALF-OPEN 시도
        sliding-window-size: 10             # 최근 10개 요청 기준
        permitted-number-of-calls-in-half-open-state: 3