--- title: Runbook — AUTH_KID_UNKNOWN (키 ID 미인식) category: AUTH error_codes: [AUTH_KID_UNKNOWN] severity: P2 owner: oncall last_updated: 2026-11-13 status: 초안 --- # Runbook: AUTH_KID_UNKNOWN (`runbook://auth/kid-unknown`) ## 증상 - HTTP 401, `error.code=AUTH_KID_UNKNOWN`, `retryable=true`, `Retry-After: 5`. - WARN 로그 줄 `security failure: code=AUTH_KID_UNKNOWN category=AUTH method=… path=…`(logger `AuthErrorResponseWriter`). - token 헤더의 `kid`가 앱이 읽은 JWKS에 없다. ## 진단 - 최근에 IdP 키 교체가 있었는지 확인한다. - JWKS는 issuer discovery의 `jwks_uri`에서 읽는다(`app.security.issuer-uri`, `APP_SECURITY_JWT_ISSUER`). 그 주소에 새 kid가 있는지 본다. 앱에는 JWKS 캐시 TTL·새로 고침 손잡이가 없다(라이브러리 기본 캐시). ## 조치 - 새 키가 IdP JWKS에 게시됐는지 확인한다. - 모르는 kid가 오면 decoder가 JWKS를 다시 받으므로, 새 키가 게시되면 재시작 없이 다음 요청부터 통과한다. 게시됐는데도 계속 이 401이면 앱이 읽는 `jwks_uri`가 IdP가 키를 게시한 곳과 같은지(앞단 캐시·다른 realm) 본다. ## 에스컬레이션 - 10분이 지나도 새 kid가 JWKS에 나타나지 않으면 IdP 팀에 넘긴다. --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.