시크릿 키 베스트 프랙티스

2024년 6월 3일 ・ 읽는 시간 8분

토스페이먼츠를 비롯해 클라우드, 캐싱 애플리케이션 등 다른 회사에서 제공하는 소프트웨어를 사용한다면 시크릿 키라는 개념을 한 번쯤은 들어봤을 거예요. 시크릿 키는 이름 그대로 비밀로 유지되어야 되는 값인데요. 오늘은 시크릿 키가 정확히 어떤 역할을 하는지, 또 어떻게 안전하게 사용할 수 있는지 알려드릴게요.

이메일에 로그인할 때 비밀번호를 입력하듯이, API를 호출할 때 인증 정보를 입력해야 돼요. API는 서버에서 서버로 통신하기 때문에 비밀번호를 입력하는 UI가 따로 없죠. 대신 Authorization HTTP 헤더를 사용해서 API를 호출하는 클라이언트를 인증할 수 있어요.

그럼 '인증 정보'로 뭘 사용해야 될까요? 바로 시크릿 키를 사용하면 됩니다. 시크릿 키는 API를 호출하는 클라이언트의 신원을 보장하고 보호된 데이터나 리소스에 접근하는 요청을 확인해요. 마치 비밀번호가 이메일 계정을 보호하듯이, 시크릿 키는 API로 요청하는 리소스를 보호해요.

예를 들어 토스페이먼츠에서는 결제 내역을 조회하는 API를 제공하는데요. 아무나 내 상점의 결제 내역을 들여다볼 수 있으면 안 되겠죠. 그렇기 때문에 토스페이먼츠 결제 조회 API는 꼭 시크릿 키로 인증된 요청에만 올바른 응답을 돌려준답니다.

시크릿 키는 이런 중요한 역할을 하기 때문에 다른 사람의 손에 들어가면 큰 문제가 됩니다. 특히 결제 영역에서는 실제 돈이 왔다 갔다 하기 때문에 시크릿 키를 더욱더 조심히 보호해야겠죠.

그래서 오늘은 시크릿 키를 안전하게 보관할 수 있는 팁 다섯 개를 공유드리려고 해요.

GitHub 같은 레포지토리에 시크릿 키를 보관하면 안 됩니다. 비공개 레포지토리는 괜찮다고 생각할 수도 있는데요. 클론 및 포크될 수 있어서 언제 어떻게 공유되는지 추적하기 어려워요. 시크릿 키와 같은 민감 정보를 소스 코드에 보관하는 경우가 많기 때문에 해킹의 타깃이 되기도 합니다. 또 시크릿 키를 실수로 레포지토리에 하드코딩했다면 히스토리가 계속 남아있을 수 있어요.

안전하게 레포지토리를 사용하려면 시크릿 키와 같은 민감한 정보는 별도의 파일로 관리하고 .gitignore에 해당 파일을 반드시 추가하세요.

해당 API를 사용하는 개발자 및 서비스 기획자에게만 권한을 부여해주세요. 예를 들어 토스페이먼츠 결제 연동을 하고 있다면, 실제로 결제를 담당하고 있는 팀 한해서만 API 키 권한을 주세요. 외주사를 통해서 결제 연동을 하고 있다면, 개발이 끝난 이후에는 API 키 조회 권한을 다시 회수하세요.

토스페이먼츠 API 키는 개발자센터에서 조회할 수 있는데요. 개발자센터 메뉴의 왼쪽 하단에 있는 '사용자 추가하기'를 눌러서 새로운 사용자에게 API 키 권한을 줄 수 있어요.

슬랙, 이메일 등 안전하지 않은 메시지 채널로 시크릿 키를 공유하지 마세요. 시크릿 키를 평문으로 전송하면 유출 위험이 항상 있어요. 메시지 및 이메일 서비스 모두 안전하게 설계되어 있지만, 민감한 데이터를 주고받기 위해 설계되어 있지는 않습니다. 올바른 권한 설정으로만 API 키를 조회할 수 있도록 운영하세요.

* 토스페이먼츠 관계자가 시크릿 키를 요청하는 경우는 없습니다.

API 로그를 모니터링하면서 직접 보내지 않은 API 요청이 없는지 확인하세요. 만약 수상한 API 요청을 탐지한다면 발견 즉시 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com) 또는 실시간 문의 채널를 찾아주세요.

또 테스트 환경에서는 반드시 테스트 키를 사용하세요. 라이브 키는 실제 운영 환경에서만 사용해서 노출 위험을 최소화하세요. 테스트 시크릿 키는 노출되어도 큰 문제가 없지만 노출 시 토스페이먼츠로부터 새로운 키를 발급받는 것을 추천드려요.

외부에서 쉽게 접근할 수 있는 클라이언트 도구, SDK, 모바일 앱과 같은 애플리케이션에 시크릿 키를 직접 넣으면 안 됩니다. 클라이언트 코드에 시크릿 키를 사용하지 않는 것을 권장해요. 비교적 쉽게 접근하기 어려운 서버 코드에서만 시크릿 키를 사용해서 API를 호출하세요.

시크릿 키 유출이 의심된다면 발견 즉시 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com) 또는 실시간 문의 채널를 찾아주세요. 새로운 시크릿 키를 발급받을 수 있습니다. 새로운 키를 발급받으면 기존 시크릿 키는 더 이상 사용할 수 없어요.

토스페이먼츠에서도 유출된 시크릿 키를 발견하면 조치를 요청하는 이메일을 발송합니다. 시크릿 키가 유출됐다는 이메일을 받으면 빠르게 조치를 취해주세요. 하지만 토스페이먼츠가 모든 유출 건을 발견할 수 없기 때문에 직접 시크릿 키를 조심히 관리하는 게 중요합니다.