-
[Supabase][보안] secret API key rotation과 JWT signing key rotation을 같은 작업으로 보면 안 되는 이유와 점검 순서기타개발지식/풀스택개발 2026. 8. 10. 09:21
IT 리서치 노트
[Supabase][보안] secret API key rotation과 JWT signing key rotation을 같은 작업으로 보면 안 되는 이유와 점검 순서
Supabase incident를 다루다 보면 secret API key rotation과 JWT signing key rotation을 같은 작업으로 오해하기 쉽다. 하지만 2026년 8월 9일 기준 Supabase 공식 문서를 다시 보면 API key는 애플리케이션 컴포넌트를 식별하는 자격 증명이고, signing key는 JWT 서명과 검증 체계에 속한다. 이 글은 두 rotation을 같은 작업으로 보면 어디서 꼬이는지와, 무엇부터 어떤 순서로 점검하는 편이 안전한지 정리한 것이다.
1. 개요
결론부터 말하면 secret API key rotation은 서버 측 caller 교체 순서의 문제이고, JWT signing key rotation은 토큰 서명과 검증 경계의 문제다. 둘을 같은 작업으로 뭉개면 backend caller는 이미 새 key로 바꿨는데도 JWT 검증 cache를 괜히 건드리거나, 반대로 JWT signing key 문제인데 secret key 교체만 반복하는 상황이 생긴다.
실무 순서는 먼저
노출된 것이 secret key인지 signing key인지를 자르고, secret key면 caller inventory를 줄이고, signing key면 verifier inventory와 전환 창을 따로 잡는 편이 맞다. 이미 publishable·secret key·service_role 분리 글과 backend별 secret key rotation 글을 읽었다면, 이번 글은 그 다음 단계인 API key 층과 JWT signing key 층을 분리하는 정리다.2. 어디서 실제로 막히는가
현장에서 가장 흔한 실패는 세 가지다. 첫째, secret key leak이 났는데 JWT signing key까지 즉시 바꿔 검증자와 세션 경로를 넓게 흔든다. 둘째, 반대로 JWT signing key 전환이 필요한데 API key 교체만 반복하고 verifier inventory를 안 본다. 셋째, Edge Functions와 SSR처럼 secret key를 쓰는 서버 경로와, JWT를 검증하는 gateway·backend 경로를 같은 표에 적지 않는다.
Supabase API keys 문서는 secret key rotation을 새 키 생성, 교체, 기존 키 삭제 순서로 설명하고, migration 문서는 Edge Functions 같은 서버 경로 교체를 별도 단계로 적는다. 반면 signing keys 문서는 legacy system과 새 signing keys system, standby 같은 상태를 통해 JWT 서명 체계를 관리한다고 설명한다. 이 두 문서를 같이 읽으면 rotation 단위가 애초에 다르다는 점이 분명해진다.
- 증상: secret key 사고인데 JWT signing key 전환까지 한 번에 묶는다.
- 실패: Edge Functions와 backend caller 교체를 signing key 작업으로 오해한다.
- 막힘: verifier inventory와 caller inventory를 같은 메모에 섞는다.
- 누락: JWKS와 세션 검증 경로는 건드려야 하는지 여부를 따로 판단하지 않는다.
질문 먼저 볼 것 짧은 해석 서버 credential이 새야 했나 secret key caller inventory API key rotation branch부터 연다 JWT 검증 체계가 흔들렸나 signing key 상태와 verifier inventory signing key branch를 별도 ticket으로 본다 둘 다 만져야 하나 노출 지점과 영향 범위 원인 증거가 쌓이기 전엔 같이 굴리지 않는다 3. 실무에서 적용하는 순서
점검 순서는 다섯 단계가 가장 실용적이다. 먼저 노출되거나 교체하려는 값이 secret API key인지 signing key인지 분리한다. 두 번째로 secret key면 backend caller inventory를 만들고 새 key로 cutover한다. 세 번째로 signing key branch가 필요한지 verifier inventory를 기준으로 따로 판단한다. 네 번째로 signing key branch가 필요할 때만 standby·전환 상태와 JWKS 캐시를 같이 검토한다. 마지막으로 기존 key 삭제나 상태 전환은 cutover 완료 증거가 모인 뒤에만 실행한다.
- API key 문제인지 signing key 문제인지 먼저 자른다.
- secret key면 Edge Functions와 backend caller부터 교체한다.
- JWT verifier inventory는 별도 줄로 적는다.
- signing key 전환은 필요할 때만 standby와 cache를 같이 본다.
- 기존 key 삭제나 상태 전환은 마지막에 한다.
실제 운영에서는 Dashboard Settings 메뉴를 열고, API Keys 탭을 클릭하고, Edge Functions 설정 화면과 secrets 파일을 확인하고, 새 값을 입력하고, 저장하고, 배포를 다시 실행한 뒤, 응답과 로그와 오류 상태를 조회해 cutover가 끝났는지 확인하는 편이 좋다. JWT signing key branch가 필요할 때는 verifier 콘솔 경로, JWKS 조회 결과, 세션 검증 로그, 상태 비교 표를 별도로 저장하고 같은 ticket 안에서도 분리해 적는 편이 안전하다.
이 순서를 지키면 incident 범위를 불필요하게 넓히지 않는다. secret key 사고라면 사용자 세션 검증 체계까지 흔들지 않고 caller 교체에 집중할 수 있고, signing key 문제라면 RLS·Authorization header 쪽을 괜히 건드리지 않아도 된다. 실제 운영에서는 key 종류, caller 경로, verifier 경로, 삭제 여부를 한 표에 두되 열을 분리하는 편이 가장 안전하다.
rotation_decision: api_key_incident=true signing_key_incident=false edge_functions_cutover=required verifier_inventory_review=not_started old_secret_key_delete=after_cutover이 메모가 있으면 대응이 빨라진다. 다음 담당자가 들어와도 '어떤 키를 왜 바꾸는지'가 먼저 보이고, JWT 검증과 server caller 교체를 한 줄로 오해하지 않게 된다.
4. 공식 문서와 예시 화면으로 확인하기
첫 공식 화면은 Supabase API keys 문서의 secret key rotation 구간이다. 여기서는 새 secret key를 만들고, 사용하는 컴포넌트를 교체한 뒤, 마지막에 기존 key를 지우는 순서를 분명히 적고 있다.
이 문장만 봐도 rotation 대상이 브라우저가 아니라 서버 측 컴포넌트라는 점이 드러난다. secret key rotation은 backend caller 교체 순서 문제지, JWT 서명 체계를 바로 뒤집는 작업이 아니다.
두 번째 자료는 Supabase의 새 API key migration 문서다. 특히 Step 4는 Edge Functions까지 포함해 secret key를 쓰는 서버 측 경로를 바꾸라고 적는다.
즉 secret key 사고가 났을 때는 브라우저 앱보다 Edge Functions, SSR, 배치, webhook caller inventory를 먼저 닫는 편이 맞다. 이 단계는 JWT signing key와는 여전히 다른 층이다.
세 번째 공식 화면은 Supabase Auth signing keys 문서의 개요다. 여기서는 API key가 아니라 JWT 서명에 쓰는 signing key 체계를 legacy 방식과 새 signing keys 방식으로 나눠 설명한다.
따라서 secret key leak과 JWT signing key 문제는 같은 체크리스트로 닫히지 않는다. 하나는 서버 caller 자격 증명이고, 다른 하나는 사용자 토큰 서명 및 검증 경계다.
네 번째 자료는 Edge Functions secrets 문서다. 이 화면에서는 어떤 기본 secret이 서버 경로에 주입되는지 메뉴와 필드를 확인하고, 어떤 함수 설정 파일이 어떤 값을 읽는지 저장해 두는 편이 좋다.
이 화면은 secret key branch에서 먼저 확인할 콘솔 경로를 보여 준다. 반대로 JWT signing key 전환은 verifier, JWKS, 세션 검증 상태를 따로 확인해야 하므로 같은 설정 탭으로 닫히지 않는다.
실무에서 제일 자주 꼬이는 부분은 secret key leak과 JWT signing key 변경을 같은 incident로 뭉개는 일이다. 분기표를 먼저 두면 어떤 팀이 무엇을 바꾸는지 훨씬 빨리 나뉜다.
이미 publishable·secret key·service_role 분리 글과 backend별 secret key rotation 순서 글이 caller 층을 다뤘다면, 이번 표는 거기서 JWT 서명 층을 따로 떼어내는 후속편이다.
마지막 자료는 incident 메모 예시다. secret key 교체 메모와 signing key 메모를 한 줄에 섞지 않고 두 줄로 나눠 적는 것이 핵심이다.
이 정도만 분리해도 RLS 우회 경로나 JWT 검증 경로를 한 ticket에서 동시에 망가뜨리는 일을 줄일 수 있다. 더 넓은 caller inventory는 Schedule Functions와 pg_net caller inventory 글과 이어 읽기 좋다.
5. 주의사항과 리스크
첫 번째 리스크는 secret key leak을 signing key incident처럼 다뤄 verifier와 세션 경로를 과하게 건드리는 것이다. 두 번째 리스크는 signing key 전환이 필요한데 API key rotation만 끝내고 안심하는 것이다. 세 번째 리스크는 key 종류별 inventory를 분리하지 않아 cutover 완료 증거 없이 기존 키를 지워 버리는 것이다.
운영 전에 확인할 때는 최소한 key 종류, caller inventory, verifier inventory, cutover 완료 증거, 기존 키 삭제 시점을 같은 문서에 남기는 편이 좋다. 그래야 key rotation이 두 개의 다른 작업이라는 사실이 다음 incident에도 유지된다.
- secret key rotation과 signing key rotation은 다른 층의 작업이다.
- Edge Functions와 SSR은 secret key caller inventory에 먼저 넣는다.
- JWT verifier inventory는 signing key branch에서 따로 관리한다.
6. 결론
Supabase에서 secret API key rotation과 JWT signing key rotation을 같은 작업처럼 다루면 대응 범위가 필요 이상으로 커진다. secret key는 backend caller, signing key는 토큰 서명과 검증 경계라는 점을 먼저 분리하고, cutover와 삭제도 다른 순서로 가져가야 incident가 짧아진다.
- 노출된 값이 무엇인지부터 자른다.
- secret key는 caller inventory, signing key는 verifier inventory가 기준이다.
- 기존 key 삭제는 cutover 증거 뒤에 한다.
7. 참고 링크
'기타개발지식 > 풀스택개발' 카테고리의 다른 글
