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
2.0 KiB
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 |
|
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=…(loggerAuthErrorResponseWriter). - 이 코드는 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에
맞춘다.