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
This commit is contained in:
@@ -95,4 +95,4 @@ Gradle·Docker는 desktop에서 돈다(`docs/work/operate.md` 4.1절). 명령은
|
||||
- `docs/jpa/security.md`, `docs/httpclient/security.md`, `docs/fileserver/security.md`, `docs/notification/security-privacy.md`
|
||||
- `.github/dependency-vulnerability-policy.md` — 심각도별 처리와 기한, KEV 대조.
|
||||
- `docs/work/reference/decisions.md` 2.6절(JWT audience·role, `fixture-` 거부, 파일 서버 인가, redirect 헤더, 오류 디스패치)·2.7절(취약 의존성).
|
||||
- runbook: `docs/runbooks/auth-public-path-misconfiguration.md`, `docs/runbooks/management-actuator-forbidden.md`, `docs/runbooks/authz-cross-tenant-violation.md`
|
||||
- runbook: `docs/runbooks/auth-decoder-misconfiguration.md`, `docs/runbooks/management-actuator-forbidden.md`, `docs/runbooks/authz-cross-tenant-violation.md`
|
||||
|
||||
@@ -192,7 +192,7 @@ errors:
|
||||
|
||||
# source: feature-security-operational-baseline L93 — "public path misconfiguration ... | 500 + P1 alert | INTERNAL_AUTH_MISCONFIGURATION | INTERNAL"
|
||||
# 지금 이 코드는 JWT decoder를 만들지 못할 때(issuer discovery 4xx·issuer 불일치·jwks_uri 없음) 나온다. 공개 경로
|
||||
# 설정 오류는 이 코드를 내지 않는다(runbook auth-public-path-misconfiguration.md).
|
||||
# 설정 오류는 이 코드를 내지 않는다(runbook auth-decoder-misconfiguration.md).
|
||||
- code: INTERNAL_AUTH_MISCONFIGURATION
|
||||
category: INTERNAL
|
||||
http_status: 500
|
||||
@@ -201,7 +201,7 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: crosscut
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
runbook_link: "runbook://auth/public-path-misconfiguration"
|
||||
runbook_link: "runbook://auth/decoder-misconfiguration"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
|
||||
|
||||
+7
-7
@@ -5,10 +5,10 @@ error_codes: [INTERNAL_AUTH_MISCONFIGURATION]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
status: 운영
|
||||
---
|
||||
|
||||
# Runbook: INTERNAL_AUTH_MISCONFIGURATION (`runbook://auth/public-path-misconfiguration`)
|
||||
# Runbook: INTERNAL_AUTH_MISCONFIGURATION (`runbook://auth/decoder-misconfiguration`)
|
||||
|
||||
## 증상
|
||||
|
||||
@@ -16,23 +16,23 @@ status: 초안
|
||||
- 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`).
|
||||
- 공개 경로를 의심하면 CI의 `verifyPublicPathSnapshot` 결과와 공개 경로 목록(`config/security.yml`의 `public-paths`, `SECURITY_PUBLIC_PATHS`)의 최근 변경을 본다.
|
||||
|
||||
## 조치
|
||||
|
||||
- `APP_SECURITY_JWT_ISSUER`를 IdP discovery의 `issuer`와 같게 고쳐 다시 배포한다. 설정은 기동 때 읽는다.
|
||||
- 잘못된 공개 경로 변경을 되돌린다. 저장소 루트에서 `./gradlew verifyPublicPathSnapshot`을 돌려 스냅숏과 비교한다.
|
||||
|
||||
## 에스컬레이션
|
||||
|
||||
- P1 즉시: token을 싣는 모든 요청이 500이다. 공개 경로를 잘못 열어 인증을 건너뛸 수 있을 때도 P1이다.
|
||||
- P1 즉시: token을 싣는 모든 요청이 500이다.
|
||||
|
||||
---
|
||||
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
이 runbook은 템플릿의 JWT decoder(`JwtDecoderConfig`)가 내는 신호만 다룬다. 서비스가 decoder를 바꾸면 진단 절을 그 decoder에
|
||||
맞춘다.
|
||||
@@ -18,7 +18,7 @@ status: 초안
|
||||
## 진단
|
||||
|
||||
- 검증기가 비교하는 값은 `app.security.issuer-uri`(env `APP_SECURITY_JWT_ISSUER`)다(`config/security.yml` → `JwtDecoderConfig`). 같은 env가 `spring.security.oauth2.resourceserver.jwt.issuer-uri`도 채우지만 decoder는 그 키를 읽지 않는다.
|
||||
- 거부된 token의 `iss`를 클라이언트 쪽에서 디코딩해 `APP_SECURITY_JWT_ISSUER`와 견준다. 흔한 원인은 hostname(내부·외부 주소), realm 이름, 끝의 `/` 차이다. IdP discovery의 `issuer`와 설정값이 다르면 이 401이 아니라 decoder를 만들지 못한 500 `INTERNAL_AUTH_MISCONFIGURATION`이다(`docs/runbooks/auth-public-path-misconfiguration.md`).
|
||||
- 거부된 token의 `iss`를 클라이언트 쪽에서 디코딩해 `APP_SECURITY_JWT_ISSUER`와 견준다. 흔한 원인은 hostname(내부·외부 주소), realm 이름, 끝의 `/` 차이다. IdP discovery의 `issuer`와 설정값이 다르면 이 401이 아니라 decoder를 만들지 못한 500 `INTERNAL_AUTH_MISCONFIGURATION`이다(`docs/runbooks/auth-decoder-misconfiguration.md`).
|
||||
- 토큰, `Authorization` 헤더, JWT payload는 로그에 남지 않고 남겨서도 안 된다.
|
||||
|
||||
## 조치
|
||||
|
||||
@@ -39,7 +39,7 @@ status: 초안
|
||||
- 가능한 원인:
|
||||
- 직전 deploy의 회귀 버그 → rollback
|
||||
- JVM OOM (메모리 leak 또는 부하 증가) → heap dump 분석(`runtime-jvm-oom.md`)
|
||||
- JWT decoder 설정 오류 (`INTERNAL_AUTH_MISCONFIGURATION`) → issuer 설정과 discovery(`auth-public-path-misconfiguration.md`)
|
||||
- JWT decoder 설정 오류 (`INTERNAL_AUTH_MISCONFIGURATION`) → issuer 설정과 discovery(`auth-decoder-misconfiguration.md`)
|
||||
- thread starvation (pool 고갈) → thread dump (`jstack <pid>`)
|
||||
|
||||
## 4. Mitigation
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
# 업그레이드 안내 — 2026-11 GraphQL 관측 tag·안 쓰는 헤더 상수·인증 설정 runbook 이름
|
||||
|
||||
- 범위: 2026-11-12 전체 리뷰를 고친 뒤 남은 후속. GraphQL resolver·DataLoader 지표가 플랫폼 tag를 달고, GraphQL 지표가 요청마다 같은 tag key를 달고, 쓰는 곳 없는 `ApiHeaders` 상수 둘을 지웠다.
|
||||
- 범위: 2026-11-12 전체 리뷰를 고친 뒤 남은 후속. GraphQL resolver·DataLoader 지표가 플랫폼 tag를 달고, GraphQL 지표가 요청마다 같은 tag key를 달고, 쓰는 곳 없는 `ApiHeaders` 상수 둘을 지웠고, `INTERNAL_AUTH_MISCONFIGURATION`의 runbook 이름을 내용에 맞췄다.
|
||||
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 관측·인증 묶음을 고칠 때 범위 밖으로 남긴 후속
|
||||
|
||||
## 1. 누가 읽나
|
||||
|
||||
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 GraphQL을 켜고 그 지표로 대시보드를 만든 서비스, web `ApiHeaders` 상수를 부르는 서비스다.
|
||||
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 GraphQL을 켜고 그 지표로 대시보드를 만든 서비스,
|
||||
web `ApiHeaders` 상수를 부르는 서비스, 오류 코드의 runbook 링크로 경보를 만든 서비스다.
|
||||
|
||||
## 2. 할 일
|
||||
|
||||
@@ -16,6 +17,7 @@
|
||||
| 3 | `graphql.dataloader` timer의 tag가 Spring 기본값(`graphql.loader.name`, `graphql.error.type`, `graphql.outcome`)에서 `graphql.dataloader.name`, `graphql.outcome`, `graphql.batch.size.bucket`(`1`·`2-10`·`11-100`·`100+`)으로 바뀌었다. loader 이름은 등록한 이름이거나 Spring이 `@BatchMapping` loader에 붙이는 schema 좌표(`Book.author`)다. 클래스 이름으로 등록한 loader(`forTypePair`)와 이름 문법 밖의 loader는 `unknown` 하나로 묶인다. `error` tag는 그대로 있다 | `graphql.loader.name`으로 거른 패널·경보를 `graphql.dataloader.name`으로 바꾼다. 클래스 이름 loader를 따로 보려면 이름을 주어 등록한다(`BatchLoaderRegistry`의 `forName(…)`이나 `forTypePair(…).withName(…)`) | 그 패널이 비고, 클래스 이름 loader가 `unknown`에 섞인다 | DataLoader를 쓰는 GraphQL 서비스 |
|
||||
| 4 | `GraphQlResolverObservationConvention`이 내는 무게 tag 이름이 `graphql.operation.type`에서 `graphql.resolver.weight`로, `GraphQlDataLoaderObservationConvention`의 batch 크기 tag가 `graphql.complexity.bucket`에서 `graphql.batch.size.bucket`으로 바뀌었다. 두 convention은 이제 `DataFetcherObservationConvention`·`DataLoaderObservationConvention` bean(adapter)으로 Spring observation에 붙는다 | 두 convention의 `tags(...)`를 직접 불러 옛 key를 읽던 코드를 새 key로 바꾼다. 자기 `DataFetcherObservationConvention`·`DataLoaderObservationConvention` bean을 둔 서비스는 그 bean이 쓰이고 위 2·3번 tag가 붙지 않는다 | 옛 key를 찾는 코드가 빈 값을 본다 | 두 convention을 직접 쓰거나 바꾼 서비스 |
|
||||
| 5 | web `ApiHeaders.DEPRECATION`·`ApiHeaders.DATE` 상수를 지웠다. 운영 코드가 쓰지 않았다 | 그 상수를 부르던 코드는 자기 상수나 Spring `HttpHeaders.DATE`로 바꾼다(마지막으로 있던 커밋은 `docs/capability-status.md` 제거 표) | 컴파일이 실패한다 | 그 상수를 부르던 서비스 |
|
||||
| 6 | `INTERNAL_AUTH_MISCONFIGURATION`의 `runbook_link`가 `runbook://auth/public-path-misconfiguration`에서 `runbook://auth/decoder-misconfiguration`으로, 파일이 `docs/runbooks/auth-public-path-misconfiguration.md`에서 `docs/runbooks/auth-decoder-misconfiguration.md`로 바뀌었다. 그 runbook은 `status: 운영`이라 `RunbookCoverageContractTest`의 `LEGACY_STUB_DEBT`(초안 runbook 목록)에서 빠졌다 | 옛 링크·파일 이름을 가리키는 경보·대시보드·문서를 새 이름으로 바꾼다. 옛 파일을 자기 쪽에서 고쳐 두었으면 그 내용을 새 파일로 옮기고 옛 파일을 지운다 | 경보의 runbook 링크가 없는 파일을 가리킨다. 옛 파일이 `status: 초안`으로 남으면 목록과 맞지 않아 `RunbookCoverageContractTest`가 실패한다 | 그 runbook을 쓰거나 고친 서비스 |
|
||||
|
||||
## 3. 바뀌지 않은 것
|
||||
|
||||
|
||||
-1
@@ -82,7 +82,6 @@ class RunbookCoverageContractTest {
|
||||
"auth-issuer-mismatch.md",
|
||||
"auth-jwks-unavailable.md",
|
||||
"auth-kid-unknown.md",
|
||||
"auth-public-path-misconfiguration.md",
|
||||
"auth-token-expired.md",
|
||||
"auth-token-invalid-signature.md",
|
||||
"auth-token-malformed.md",
|
||||
|
||||
Reference in New Issue
Block a user