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
39 lines
2.0 KiB
Markdown
39 lines
2.0 KiB
Markdown
---
|
|
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 설정을 본다. 앱이 도는 곳에서 `<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에
|
|
맞춘다.
|