Files
clean-architecture-backend-…/docs/runbooks/auth-jwks-unavailable.md
T
DongHyeonka 7ce83b73d9 fix(web): 보안 필터가 5xx 인증 실패를 ERROR로 남긴다
문제: AuthErrorResponseWriter는 보안 필터가 답한 실패를 모두 WARN으로
남긴다. AUTH_JWKS_UNAVAILABLE(503, 키 서버 장애)과
INTERNAL_AUTH_MISCONFIGURATION(500, 인증 설정 오류)은 서버 쪽 고장인데도
WARN이다. 다른 모든 경로는 5xx를 ERROR로 남기므로(ServerFailureLog) 규칙이
갈라져 있고, ERROR로 거르는 운영자는 이 둘을 놓친다.

고른 방법: 응답 상태로 레벨을 고른다. 5xx는 ERROR, 4xx는 WARN이다. 줄의
모양(code·category·method·path, 예외 없음)은 그대로다. 401 서명·issuer·
audience 불일치는 WARN으로 둔다(소유자 결정 3, 2026-11-06). 테스트가 서명
실패 WARN도 고정한다.
버린 대안: 두 코드를 이름으로 나열하기 — 새 5xx 보안 코드가 생기면 조용히
WARN에 남는다. ServerFailureLog 줄로 바꾸기 — 예외를 붙이는 줄이라, 토큰이
섞일 수 있는 실패 메시지를 남기지 않는 이 writer의 계약과 맞지 않는다.

위험·한계: ERROR 수로 경보를 거는 곳에 JWKS 장애와 인증 설정 오류가 새로
잡힌다. upgrade 안내 5절에 적었다. 결정은
docs/superpowers/specs/2026-11-06-error-code-log-level-design.md 10절이다.

검증(desktop, 공유 잠금, 로그는 desktop ~/t3-loglevel-logs/):
- RED: 기준 writer로 EnvelopeAuthenticationEntryPointTest 8건 중 2건 실패
  (aKeyServiceOutageIsLoggedAtError, aDecoderMisconfigurationIsLoggedAtError
  — WARN이 나오고 ERROR를 기대). rc=1, red-web.log
- GREEN: :adapter:inbound:web:check rc=0, 테스트 329건 실패 0.
  green-web-check.log
- :adapter:inbound:web:testQualityCheck rc=0, green-quality.log
2026-11-06 22:17:02 +09:00

1004 B

title, category, error_codes, severity, owner, last_updated, status
title category error_codes severity owner last_updated status
Runbook — AUTH_JWKS_UNAVAILABLE (JWKS 엔드포인트 장애) TRANSIENT_DEPENDENCY
AUTH_JWKS_UNAVAILABLE
P1 oncall 2026-11-06 stub

Runbook: AUTH_JWKS_UNAVAILABLE (runbook://auth/jwks-unavailable)

Symptoms

  • HTTP 503 with error.code=AUTH_JWKS_UNAVAILABLE
  • ERROR log line security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY method=… path=… (logger AuthErrorResponseWriter)
  • All authentication failing; JWKS refresh attempts failing

Diagnosis

  • Check IdP JWKS endpoint health: curl -sf https://<idp-host>/.well-known/jwks.json
  • Check network connectivity from app pods to IdP

Action

  • Enable cached JWKS fallback if available
  • Coordinate with IdP team for restoration

Escalation

  • P1 page: IdP team immediately if JWKS endpoint unreachable > 2 minutes

Stub: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)