백엔드 API 키 회전 실패 모드: 해시 저장, 중첩 유효기간, 권한 범위와 폐기 전파

백엔드 API 키 회전의 핵심은 새 키 발급 이 아니라 발급 → 배포 → 구·신 키의 제한적 병행 사용 → 구 키 폐기 → 폐기 확인 을 하나의 수명주기로 구현하는 것이다. 평문 보관, 중첩 기간 없는 교체, 과도한 권한, 폐기 상태를 늦게 반영하는 인증 캐시가 각각 유출·장애·피해 확대·폐기 후 사용이라는 실패 모드를 만든다. 아래 구현안은 공개 지침을 조합한 설계 제안이며, 특정 제품의 보장 사항은 아니다. (docs.gitlab.com)

Summary#

백엔드 API 키 회전의 핵심은 새 키 발급이 아니라 발급 → 배포 → 구·신 키의 제한적 병행 사용 → 구 키 폐기 → 폐기 확인을 하나의 수명주기로 구현하는 것이다. 평문 보관, 중첩 기간 없는 교체, 과도한 권한, 폐기 상태를 늦게 반영하는 인증 캐시가 각각 유출·장애·피해 확대·폐기 후 사용이라는 실패 모드를 만든다. 아래 구현안은 공개 지침을 조합한 설계 제안이며, 특정 제품의 보장 사항은 아니다. (docs.gitlab.com)

Key Points#

키 해시 저장: 서버가 요청 키를 대조하기만 한다면 평문 대신 해시를 저장한다. 키의 식별자와 비밀값을 구분하고, 레코드에는 해시와 함께 소유 주체·권한·생성 시각·만료 시각·폐기 상태를 관리한다. 반대로 서버가 원래 비밀값을 다시 사용해야 하는 용도라면 해시만으로는 불가능하므로 암호화된 비밀 저장소가 필요하다. GitLab의 보안 지침도 ‘비교만 할 때의 해시 저장’과 ‘원문 재사용이 필요할 때의 암호화’를 구분한다. (docs.gitlab.com)
중첩 유효기간: 정상 회전에서는 새 키를 먼저 발급·배포하고 작동을 확인한 뒤, 정해진 전환 기간 동안만 구·신 키를 함께 허용한다. 이어 구 키를 폐기하고 구 키를 사용하는 요청이 더 이상 성공하지 않는지 검사한다. Stripe는 회전 시 구 키를 즉시 만료시키거나 만료 시점을 지정할 수 있게 한다. 따라서 ‘회전’이라는 명령만으로 무중단 전환이 보장된다고 가정하면 안 된다. (docs.stripe.com)
권한 범위: 교체 키가 기존의 광범위한 권한을 무심코 이어받으면 회전해도 유출 시 피해 범위가 줄지 않는다. 서비스·환경·작업별로 필요한 권한을 검토하고, 구·신 키가 동시에 살아 있는 동안에도 각 키의 권한을 명시적으로 관리한다. Stripe의 제한된 API 키는 지정한 접근 수준만 허용하는 사례다. (docs.stripe.com)
폐기 전파: 관리 DB에서 revoked로 표시하는 것과 모든 인증 서버가 구 키를 거부하는 것은 별개다. 로컬 캐시, 복제 지연, 장기 실행 프로세스가 있다면 폐기 상태의 최대 반영 지연을 설계·측정하고, 각 인증 경로에서 폐기된 키가 거부되는지 시험한다. 이는 배포·캐시 구조에 따른 구현상 추론이며, 조사한 자료가 특정 전파 시간을 보장하지는 않는다. (cheatsheetseries.owasp.org)
관측과 사고 대응: 키 원문은 로그에 남기지 말고 키 식별자 기준으로 발급·권한 변경·사용·만료·폐기 및 인증 실패를 추적한다. 정상 교체에는 짧고 계획된 중첩 기간을 쓰되, 유출이 의심되는 키를 가용성 때문에 계속 허용하는 절차와는 구별한다. OWASP는 비밀의 사용·변경·만료와 인증 오류에 대한 감사를, 잠재적으로 침해된 비밀의 폐기를 권고한다. (docs.gitlab.com)

Cautions#

‘짧은 중첩 기간’과 ‘허용 가능한 폐기 전파 지연’에 적용할 보편적인 분·초 단위 수치는 확인하지 못했다. 실제 값은 클라이언트 배포 시간, 캐시 정책, 위협 모델을 바탕으로 정하고 시험해야 한다. (docs.stripe.com)
해시 저장은 발급자 서버의 검증용 저장소에 관한 설계다. API를 호출하는 클라이언트는 요청에 비밀값을 제시해야 하므로 클라이언트 측 비밀 보관·전송 보호가 별도로 필요하다. 해시만 저장했다는 사실로 키 유출 위험 전체가 해소되지는 않는다. (docs.gitlab.com)
Stripe의 회전·제한 키 기능은 구현 사례이지 모든 API 제공자의 공통 동작이나 폐기 즉시성에 대한 보증이 아니다. (docs.stripe.com)

Sources#

Sagwan Revalidation 2026-10-07T10:00:46Z#

verdict: ok
note: 핵심 권장안이 현재도 유효하며, 수치와 제품별 동작의 한계도 명시돼 있다.

Sagwan Revalidation 2026-10-10T07:15:49Z#

verdict: ok
note: 핵심 권장안이 여전히 유효하고, 제품별 동작과 수치의 한계도 명시돼 있다.

Sagwan Revalidation 2026-10-13T00:32:37Z#

verdict: ok
note: 해시 저장·제한적 병행 사용·최소 권한·폐기 전파 검증은 여전히 유효한 설계 원칙이다.

Sagwan Revalidation 2026-10-15T21:46:58Z#

verdict: ok
note: 해시 저장·제한적 병행 사용·최소 권한·폐기 전파 검증은 여전히 유효하며, 제품별 한계도 명시돼 있다.

Sagwan Revalidation 2026-10-18T17:41:47Z#

verdict: ok
note: 해시 저장·제한적 병행 사용·최소 권한·폐기 전파 검증 원칙이 여전히 유효하다.