MKCert와 비공식 도메인으로 로컬 HTTPS 개발환경 구축하기

Prologue

개발/테스트 환경에서 HTTPS가 필요한 경우가 있다.

• Prod 환경과 유사한 환경을 구축하기 위해서
• 브라우저 정책에 의해 (Security 옵션, SSO 등)

그러나 공식적인 도메인과 인증서가 없을때 HTTPS를 적용하기란 쉽지않다. 이를 위해 비공식 도메인 + MKcert + NginX를 활용해 HTTPS를 적용하려고 한다.

localhost를 사용하지 않는 이유는?

로컬에서 서비스/어플리케이션을 실행하고 접근한다고 하면, localhost 도메인으로도 충분히 가능하다. 하지만, 서버에 배포한 후 접근하려고한다면 localhost로는 불가능하고 직접적인 IP와 연결된 도메인으로 접근해야한다.

따라서 이런 상황에서 HTTPS를 사용하기 위함이니, 만약 로컬 환경만 사용중이라면 비공식 도메인에 관한 절차는 수행하지 않고 localhost를 사용해도 된다.

비공식 도메인 등록 (Host 파일 수정)

브라우저에서 도메인으로 접속하려고 하면, 공인 DNS에 등록되어있어야한다.

하지만 이번 테스트 환경에서 사용할 도메인은 임시로 사용할, 공인 DNS에 등록되지 않은 비공식 도메인을 사용하려고 한다.

localhost의 실제 동작 원리

로컬 환경에서 자주 사용하는 "localhost"가 실제로 어떻게 동작되는지 생각해보자.

운영체제는 먼저 host파일을 조회하여 도메인 이름에 매핑된 IP가 있는지 확인한 뒤, 없다면 DNS 질의를 시도한다.

127.0.0.1   localhost
::1         localhost

이 원리를 그대로 적용하면, 내가 사용할 임시 도메인을 대상 서버 IP에 매핑하여 임시 도메인으로 접속할 수 있다.

host 파일 수정

host파일 경로

• Linux, macOS
  • /etc/hosts
• Windows
  • C:\Windows\System32\drivers\etc\hosts

각 운영체제에 맞게 경로에 접근해서 host파일에 아래와 같이 추가하면 된다.

vi /etc/host

''' 맨 하단에 추가
<IP 주소> <도메인 이름>
'''

그리고 아래 명령어로 접속 검증이 가능하다.

ping <등록한 도메인>

MKcert로 비공식 CA/인증서 만들기

HTTPS를 사용하려면 CA로 부터 발급받은 TLS 인증서가 필요하다. 이를 발급받기 위한 방법으로는 일반적으로 Certbot을 사용하곤 한다. 하지만 Certbot은 인증서 발급 절차가 복잡하고 공인 도메인이 필요하기 때문에, 더욱 간편한 MKcert를 사용한다.

MKcert 설치

certutil 도구 설치

sudo yum install -y nss-tools

MKcert 소스 빌드

# === 방법 A: Git clone ===
git clone https://github.com/FiloSottile/mkcert
# === 방법 B: 바이너리 직접 다운로드 (Git으로 안되는 경우) ===
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"

# ls로 실제 파일명 확인 후 실행권한 부여 (예: mkcert-v1.4.4-linux-amd64)
chmod +x mkcert-v*-linux-amd64
sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert
sudo chmod +x /usr/local/bin/mkcert

설치 확인

# 3) 설치 확인
which mkcert
mkcert -version

로컬 루트 CA 설치

mkcert -install

Pem key 생성

HTTPS 통신에 필요한 인증서, 개인 키 생성

mkcert -key-file key.pem -cert-file cert.pem <도메인> *.shjung.com

# 예시
mkcert -key-file key.pem -cert-file cert.pem wooing.com *.wooing.com

Nginx로 리버스 프록시

HTTPS로 접근하고자 하는 대상 서버에는 웹서버가 실행되고있어야한다. Tomcat 등에 직접 등록하여 적용할 수 있지만, 이번 예시에서는 이를 Nginx가 대체하여 HTTPS요청을 수신하고, 대상 서비스/어플리케이션에 요청을 리버스 프록시한다.

Nginx 설치

sudo yum install -y nginx

sudo systemctl start nginx
sudo systemctl status nginx

방화벽 설정 

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

 

Config 작성 및 적용

Config파일 작성

<Nginx 설치 경로>/conf.d 폴더 안에 .conf확장자로 파일을 생성 후 아래 내용 작성한다.

server {
    listen 443 ssl;
    server_name <도메인>;

    ssl_certificate     /app/certs/cert.pem;
    ssl_certificate_key /app/certs/key.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://<IP주소>:8080/;

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-Port  443;

        proxy_redirect off;
    }
}

server {
    listen 80;
    server_name <도메인>;
    return 301 https://$server_name$request_uri;
}

설정 적용

sudo nginx -s reload

인증서 신뢰 등록

로컬 CA 설치 및 TLS인증서 등록으로 HTTPS 사용이 가능해졌다. 그럼에도 브라우저에서 접속해본다면 신뢰하지 않는 인증기관 오류가 발생할 것이다. 이는 MKcert로 발급한 CA는 공인된 신뢰 기관이 아니기때문이다.

이를 해결하기 위해 MKcert로 생성한 rootCA를 운영체제의 로컬 신뢰 저장소에 등록해야한다.

MKcert rootCA위치

아래 명령어로 rootCA의 위치를 찾을 수 있다. 해당 경로의 rootCA.pem파일을 신뢰 저장소에 등록하면 된다.

등록할때는 HTTPS를 적용하려는 서버의 rootCA.pem 파일을 찾아, 클라이언트에서 다운로드 받아 등록하면 된다. (sftp 사용)

mkcert -CAROOT
# 예: /root/.local/share/mkcert

Windows Client에 등록하기

windows에서는 .crt파일을 더블클릭하여 인증서 마법사를 통해 간편하게 설치 가능하다. 서버의 rootCA.pem파일을 다운로드 한 후, .crt로 확장자만 변경하여 더블클릭하면 된다.

Linux Client에 등록하기

# CentOS
sudo cp rootCA.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust extract

# Ubuntu/Debian
sudo cp rootCA.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates

MacOS Client에 등록하기

sudo security add-trusted-cert -d -r trustRoot \
-k /Library/Keychains/System.keychain rootCA.pem

JRE keytool 등록

로컬 신뢰 저장소에 등록하더라도 Java에서는 자체적인 저장소인 keytool을 사용하기때문에 여기에도 등록해야한다.

아래 명령어를 통해 rootCA를 신뢰하도록 등록할 수 있다.

keytool의 기본 비밀번호는 changeit이며, 만약 변경한 경우 -storepass의 값에 입력하면 된다.

/usr/local/java/jdk-17.0.16/bin/keytool -importcert \
  -keystore /usr/local/java/jdk-17.0.16/lib/security/cacerts \
  -storepass changeit \
  -alias <CA 구분하기 위한 이름> \
  -file /root/.local/share/mkcert/rootCA.pem \
  -noprompt