--- title: Runbook — AUTH_JWKS_UNAVAILABLE (JWKS 엔드포인트 장애) category: TRANSIENT_DEPENDENCY error_codes: [AUTH_JWKS_UNAVAILABLE] severity: P1 owner: oncall last_updated: 2026-11-13 status: 초안 --- # Runbook: AUTH_JWKS_UNAVAILABLE (`runbook://auth/jwks-unavailable`) ## 증상 - HTTP 503, `error.code=AUTH_JWKS_UNAVAILABLE`. - ERROR 로그 줄 `security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY method=… path=…` (logger `AuthErrorResponseWriter`). - token을 실은 요청이 모두 이 503으로 답하고, 응답에는 `Retry-After: 30`이 붙는다. ## 진단 - 앱이 읽는 JWKS 주소는 issuer discovery로 정해진다: `app.security.issuer-uri`(`APP_SECURITY_JWT_ISSUER`)의 `/.well-known/openid-configuration`에 있는 `jwks_uri`다. 앱이 도는 곳에서 그 두 주소를 `curl -sf`로 읽는다. - 앱 pod에서 IdP까지 네트워크가 닿는지 확인한다. ## 조치 - 첫 검증에 성공한 뒤에는 키를 라이브러리(Nimbus) 기본 캐시에 두므로, IdP가 잠깐 멈춰도 캐시가 살아 있는 동안은 검증이 된다. 앱에는 캐시 시간·새로 고침 손잡이가 없다. - 첫 검증 전이거나 캐시가 지난 뒤 IdP에 닿지 않으면 이 503이 난다. decoder는 다음 요청에서 다시 시도하므로 IdP가 돌아오면 저절로 회복한다. - IdP 팀과 복구를 맞춘다. ## 에스컬레이션 - P1 호출: JWKS 엔드포인트에 2분 넘게 닿지 않으면 IdP 팀을 바로 부른다. --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.