mkcert: 로컬 개발 환경에서 신뢰할 수 있는 인증서 설정

mkcert는 로컬 개발 환경에서 신뢰할 수 있는 인증서를 설정 없이(zero-config) 간단하게 생성해 주는 도구입니다.

주로 로컬에서 https 환경을 테스트하거나, localhost와 같은 로컬 주소에 대해 브라우저 경고 없이 안전하게 통신하기 위해 사용됩니다.

---

왜 mkcert가 필요한가

로컬 환경(예: localhost, 127.0.0.1 등)에서 개발할 때, 실제 인증 기관(CA)에서 발급한 인증서를 사용하는 것은 불가능하거나 보안상 위험할 수 있습니다. 기존에 많이 쓰던 자체 서명 인증서(Self-signed certificate)를 사용하면 브라우저에서 '신뢰할 수 없는 인증서' 경고(보안 오류)를 필연적으로 마주치게 됩니다.

이 문제를 근본적으로 해결하려면 개발자 스스로 로컬 CA(인증 기관)를 구축해야 하지만, 관련 명령어가 난해하고 수동으로 거쳐야 하는 과정이 너무 복잡하다는 단점이 있었습니다.

mkcert는 시스템 루트 저장소에 로컬 개인 CA를 자동으로 생성 및 설치하고, 이 CA를 기반으로 브라우저에서 로컬로 신뢰하는 인증서를 클릭 몇 번(명령어 몇 줄) 수준으로 쉽게 발급해 주어 이러한 스트레스를 없애줍니다.

---

mkcert 설치

운영체제에 맞게 패키지 매니저를 통해 간단히 설치할 수 있습니다. (Firefox를 사용하는 경우 nss 패키지 추가 설치가 권장됩니다)

macOS

brew install mkcert
brew install nss # Firefox를 사용하는 경우

Windows

Chocolatey 또는 Scoop을 이용해 설치합니다.

choco install mkcert
# 또는
scoop bucket add extras
scoop install mkcert

Linux (Ubuntu/Debian 기반)

먼저 인증서 관리를 위한 certutil 관련 도구를 설치해야 합니다.

sudo apt install libnss3-tools

이후 Linux용 Homebrew를 사용하여 설치합니다.

brew install mkcert

---

mkcert 주요 사용법

1. 로컬 CA 시스템에 설치하기

최초 1회만 실행하면 되며, 로컬 인증 기관(CA)을 시스템과 브라우저의 신뢰 저장소(Trust store)에 설치합니다.

mkcert -install

2. 로컬 개발용 인증서 발급

인증서가 필요한 로컬 도메인이나 IP 주소를 지정하여 키 쌍을 생성합니다. (localhost 외에 개발용 가상 도메인도 지정 가능합니다.)

mkcert example.com "*.example.com" example.test localhost 127.0.0.1 ::1

위 명령어를 실행하면 명령어를 실행한 현재 디렉토리에 인증서(.pem)와 개인키(-key.pem) 파일이 생성됩니다.

• example.com+5.pem (인증서)
• example.com+5-key.pem (개인키)

발급이 완료되면 이 인증서 파일 경로를 로컬 웹 서버(Nginx, Apache, Express, Vite 등)의 SSL 설정에 적용하여 사용하시면 됩니다. (서버 내부 설정까지 자동으로 구성해 주지는 않으므로 직접 적용해야 합니다.)

---

⚠️ 커스텀 CA 보안 주의사항

mkcert가 내 컴퓨터 내부에 자동으로 생성한 로컬 CA의 개인키 파일(rootCA-key.pem)은 해당 기기에서 발생하는 보안 요청을 중간에서 가로챌 수 있는 절대적인 권한을 가집니다. 이 키 파일은 절대로 버전 관리 시스템(Git 등)에 올리거나, 다른 사람과 공유해서는 안 됩니다.

---

참고

https://github.com/FiloSottile/mkcert