--- title: Runbook — INTERNAL_AUTH_MISCONFIGURATION (JWT decoder 설정 오류) category: INTERNAL error_codes: [INTERNAL_AUTH_MISCONFIGURATION] severity: P1 owner: oncall last_updated: 2026-11-13 status: 운영 --- # Runbook: INTERNAL_AUTH_MISCONFIGURATION (`runbook://auth/decoder-misconfiguration`) ## 증상 - HTTP 500, `error.code=INTERNAL_AUTH_MISCONFIGURATION`. - ERROR 로그 줄 `security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL method=… path=…` (logger `AuthErrorResponseWriter`). - 이 코드는 JWT decoder를 만들 수 없을 때 나온다: issuer metadata가 망가졌거나 네트워크 문제가 아닌 이유로 decoder 초기화가 실패했다(`JwtDecoderConfig` → `SecurityErrorClassifier`). decoder는 첫 token을 검증할 때 만들어지므로 기동은 성공하고, token을 실은 요청마다 이 500이 난다. - 공개 경로 설정 오류는 이 코드를 내지 않는다. 잘못 연 공개 경로는 오류 없이 열리므로 CI의 `verifyPublicPathSnapshot` (공개 경로 목록을 스냅숏과 비교하는 검사)으로만 잡힌다. 이 runbook의 대상이 아니다. ## 진단 - 먼저 issuer 설정을 본다. 앱이 도는 곳에서 `/.well-known/openid-configuration`을 받는다. 이 500은 discovery 후보 주소가 모두 4xx(없는 realm, 틀린 경로)이거나, 응답의 `issuer`가 `APP_SECURITY_JWT_ISSUER`와 글자까지 다르거나(끝의 `/` 포함), `jwks_uri`가 없을 때다. - 연결 실패·5xx·JSON이 아닌 응답이면 이 코드가 아니라 503 `AUTH_JWKS_UNAVAILABLE`이다(`docs/runbooks/auth-jwks-unavailable.md`). ## 조치 - `APP_SECURITY_JWT_ISSUER`를 IdP discovery의 `issuer`와 같게 고쳐 다시 배포한다. 설정은 기동 때 읽는다. ## 에스컬레이션 - P1 즉시: token을 싣는 모든 요청이 500이다. --- 이 runbook은 템플릿의 JWT decoder(`JwtDecoderConfig`)가 내는 신호만 다룬다. 서비스가 decoder를 바꾸면 진단 절을 그 decoder에 맞춘다.