API 키 유출 걱정될 때? 맥 환경변수 & .env 설정으로 안전하게

파이썬으로 API를 활용하는 개발자라면 누구나 한 번쯤 API 키를 코드에 직접 넣고는, ‘혹시 이대로 GitHub에 푸시해서 전 세계에 공개되면 어쩌지?’라는 생각에 가슴이 철렁했던 경험이 있을 겁니다. 매번 터미널에서 export 명령어를 입력하는 것도 여간 번거로운 일이 아니었을 테고요.

이러한 걱정은 민감한 인증 정보를 소스코드와 분리하여 안전하게 관리하는 것이 개발 보안의 핵심 원칙이기 때문에 발생합니다.

이 글에서는 macOS 환경에서 API 키를 시스템 환경변수로 영구 설정하는 방법부터, 프로젝트별로 유연하게 관리할 수 있는 .env 파일 활용법까지, 총 3가지 실용적인 해결책을 단계별로 자세히 설명합니다.

왜 API 키를 숨겨야 할까요? 민감 정보 노출의 위험성

수많은 개발 프로젝트에서 외부 API를 사용하기 위해 고유한 API 키를 활용하지만, 이를 코드에 직접 하드코딩하는 경우가 많습니다. 이렇게 되면 프로젝트 코드가 공개 저장소(예: GitHub)에 올라가는 순간 API 키는 전 세계에 노출되어 심각한 보안 위험에 직면하게 됩니다. API 키 유출은 무단 접근, 서비스 남용, 개인 정보 및 결제 정보 탈취 등 돌이킬 수 없는 피해를 초래하므로, 민감한 정보는 절대로 코드에 직접 넣어서는 안 됩니다.

Photo by Rahul Pandit on Pexels

macOS 시스템 환경변수로 API 키 설정하기 (영구 적용)

macOS에서 API 키를 시스템 환경변수로 설정하면, 해당 키는 모든 터미널 세션과 응용 프로그램에서 접근 가능해집니다. 이는 시스템 전반에서 특정 키를 공유해야 할 때 특히 유용하며, 한 번 설정하면 재부팅 후에도 유지되므로 매우 편리합니다.

이 방법은 4단계로 간단하게 적용할 수 있습니다. 주로 사용하는 셸(Zsh 또는 Bash)의 설정 파일을 수정하여 환경변수를 영구적으로 등록하는 방식입니다.

1. 터미널 열기 및 설정 파일 편집 — 터미널을 열고 nano ~/.zshrc (macOS Catalina 이후 기본 셸인 Zsh 사용 시) 또는 nano ~/.bash_profile (Bash 사용 시) 명령어를 입력하여 해당 파일을 엽니다. nano 대신 vi나 code 등의 편집기를 사용해도 무방합니다.
2. API 키 추가 — 파일의 맨 아래에 다음 형식으로 API 키를 추가합니다. export MY_API_KEY=”YOUR_ACTUAL_API_KEY_HERE” 여기서 MY_API_KEY는 당신이 사용할 환경변수 이름이고, 따옴표 안의 내용은 실제 API 키입니다. 여러 개의 키를 추가할 수 있습니다.
3. 변경사항 적용 — 파일을 저장하고 편집기를 종료한 후, 터미널에 source ~/.zshrc 또는 source ~/.bash_profile 명령어를 입력하여 변경사항을 현재 세션에 적용합니다. 이 과정은 새로운 터미널을 열 때마다 자동으로 실행됩니다.
4. 환경변수 확인 — echo $MY_API_KEY 명령어를 입력하여 API 키가 제대로 설정되었는지 확인합니다. 올바르게 설정되었다면, 설정했던 API 키 값이 출력될 것입니다.

Photo by Al Nahian on Pexels

프로젝트별 API 키 관리를 위한 .env 파일 활용

시스템 환경변수는 전역적으로 적용되지만, 특정 프로젝트에서만 사용하는 API 키나, 팀원마다 다른 키를 사용해야 하는 경우 .env 파일을 활용하는 것이 훨씬 유연하고 효율적입니다. .env 파일은 프로젝트 루트 디렉토리에 위치하며, 해당 프로젝트에서만 사용될 환경변수를 정의하는 데 사용됩니다.

.env 파일의 가장 큰 장점은 프로젝트별로 독립적인 환경을 구축할 수 있고, .gitignore에 추가하여 버전 관리 시스템에서 완벽하게 제외할 수 있다는 점입니다. 이는 API 키 유출 위험을 획기적으로 줄여줍니다.

1. .env 파일 생성 — 프로젝트의 최상위 디렉토리에 .env라는 이름의 파일을 생성합니다. 파일 이름은 반드시 .env여야 합니다.
2. API 키 정의 — .env 파일 내부에 KEY=VALUE 형식으로 API 키를 정의합니다. 예를 들어, MY_PROJECT_API_KEY=another_secret_key_12345 와 같이 작성합니다. 따옴표는 사용하지 않아도 되지만, 공백이나 특수 문자가 포함된 값이라면 따옴표를 사용하는 것이 좋습니다. 각 키-값 쌍은 새 줄에 작성합니다.
3. .gitignore에 추가 — 가장 중요한 단계입니다. 프로젝트의 .gitignore 파일에 .env를 추가하여 이 파일이 Git 저장소에 업로드되지 않도록 합니다. 예를 들어:
   # Environment variables
.env
   만약 이 단계를 건너뛴다면, .env 파일 역시 공개 저장소에 그대로 노출될 위험이 있습니다.

Photo by Sora Shimazaki on Pexels

파이썬 프로젝트에서 API 키 안전하게 불러오기

이제 .zshrc에 등록했거나 .env 파일을 통해 정의한 API 키를 파이썬 프로젝트에서 어떻게 안전하게 불러와 사용할 수 있는지 알아보겠습니다. 파이썬의 os 모듈과 함께 python-dotenv 라이브러리를 사용하면 이 과정을 매우 쉽게 처리할 수 있습니다.

python-dotenv는 .env 파일의 내용을 읽어 시스템 환경변수로 로드하는 역할을 합니다. 만약 시스템 환경변수와 .env 파일에 동일한 이름의 변수가 존재한다면, 시스템 환경변수가 우선적으로 적용됩니다. 이 점을 활용하면 개발 환경과 배포 환경에서 유연하게 API 키를 관리할 수 있습니다.

1. python-dotenv 라이브러리 설치 — 터미널에서 pip install python-dotenv 명령어를 입력하여 필요한 라이브러리를 설치합니다. 이 라이브러리는 3초 이내에 설치가 완료될 것입니다.
2. 파이썬 코드에 적용 — 프로젝트의 파이썬 파일(예: main.py 또는 app.py)에서 다음 코드를 추가하여 API 키를 불러옵니다.

   import os
   from dotenv import load_dotenv
   
   # .env 파일에서 환경변수를 로드합니다.
   # 이 함수는 스크립트 실행 초기에 호출하는 것이 좋습니다.
   load_dotenv()
   
   # 환경변수 'MY_API_KEY'를 불러옵니다.
   api_key = os.getenv("MY_API_KEY")
   
   if api_key:
       print(f"API 키가 성공적으로 로드되었습니다: {api_key[:5]}*****") # 보안상 일부만 출력
       # 이제 api_key 변수를 사용하여 안전하게 외부 API를 호출할 수 있습니다.
   else:
       print("API 키를 찾을 수 없습니다. .env 파일 또는 시스템 환경변수를 확인하세요.")

.env와 시스템 환경변수, 어떤 것을 선택할까?

대부분의 경우, 프로젝트 고유의 API 키는 .env 파일을 통해 관리하고, 개발 환경 전반에 걸쳐 공통적으로 필요한 키(예: AWS 자격 증명)는 시스템 환경변수로 설정하는 이중 전략이 가장 효율적입니다. 이렇게 하면 개발 효율성과 보안을 모두 확보할 수 있습니다.