Files
clean-architecture-backend-…/docs/runbooks/auth-decoder-misconfiguration.md
T
DongHyeonka 593615b019 docs(runbooks)!: 인증 설정 오류 runbook 이름을 내용에 맞춘다
INTERNAL_AUTH_MISCONFIGURATION의 runbook은 JWT decoder 설정 오류(issuer
discovery 실패, jwks_uri 없음)를 다루지만 파일 이름과 runbook_link는
옛 이름 auth-public-path-misconfiguration이다. 제목만 바꾼 채로 두어
경보에서 링크를 따라온 사람이 공개 경로 문제로 읽는다. 본문이 다
쓰였는데도 status 초안이라 RunbookCoverageContractTest의 임시 목록
LEGACY_STUB_DEBT에 남아 있다.

파일을 auth-decoder-misconfiguration.md로 옮기고 runbook_link를
runbook://auth/decoder-misconfiguration으로 바꾼다. status를 운영으로
올리고 초안 꼬리 문단을 이 runbook이 다루는 범위(템플릿의
JwtDecoderConfig가 내는 신호) 한 줄로 바꾼다. 이 500의 처리로 공개 경로
되돌리기를 안내하던 진단·조치·에스컬레이션 문장은 지우고, 공개 경로
오류는 verifyPublicPathSnapshot이 잡는다는 한 줄만 남긴다. LEGACY_STUB_DEBT에서 빼고,
옛 이름을 가리키던 be-security 스킬·다른 runbook 두 곳을 고친다.

위험: runbook_link 값이 바뀐다. 옛 링크로 경보를 만든 서비스는 upgrade
문서 6행대로 바꾼다.

검증: python3 scripts/check-docs.py·check-work-docs.py OK, desktop
:app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTest,
scripts/verify.sh pr.

BREAKING CHANGE: INTERNAL_AUTH_MISCONFIGURATION의 runbook_link가
runbook://auth/decoder-misconfiguration이다.
Refs: round9 그룹 A 범위 밖 후속 4
2026-11-13 19:30:12 +09:00

2.0 KiB

title, category, error_codes, severity, owner, last_updated, status
title category error_codes severity owner last_updated status
Runbook — INTERNAL_AUTH_MISCONFIGURATION (JWT decoder 설정 오류) INTERNAL
INTERNAL_AUTH_MISCONFIGURATION
P1 oncall 2026-11-13 운영

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 설정을 본다. 앱이 도는 곳에서 <APP_SECURITY_JWT_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에 맞춘다.