self-signed certificate in certificate chain 해결 방법, fetch failed만 찍히고 원인이 안 보인 이유
문제 발생
사내망 노트북에서만 API 호출이 실패했습니다. 같은 코드를 집에서 돌리면 잘 됩니다. 로그에는 이 한 줄만 남았습니다.
TypeError: fetch failed
at node:internal/deps/undici/undici:13510:13"fetch failed"가 전부입니다. 상태 코드도, 호스트 이름도, 이유도 없습니다. 네트워크가 끊긴 줄 알고 ping을 해 보니 잘 갑니다. 터미널에서 curl로 같은 주소를 부르니 이번엔 다른 말이 나왔습니다.
curl: (60) SSL certificate problem: unable to get local issuer certificate인증서 문제라는 건 알겠는데, 브라우저에서 같은 주소를 열면 자물쇠가 멀쩡합니다. 사내 PC에는 보안팀이 설치해 둔 회사 인증서가 깔려 있고 OS도 그걸 신뢰하고 있었습니다. 그런데 Node만 모른다고 합니다.
이 글은 Node 22.23에서 사설 CA와 서버 인증서를 직접 만들어 재현했습니다. 사내 프록시가 TLS를 중간에서 다시 서명하는 환경과 같은 구조입니다.
원인 분석
fetch failed는 껍데기입니다. 진짜 이유는 cause에 들어 있습니다. Node의 fetch는 하위 오류를 TypeError: fetch failed로 감싸고, 원래 오류를 error.cause에 넣습니다. 그래서 console.error(e)만 해 두면 아무것도 알 수 없습니다. cause를 같이 찍도록 바꾸자 정체가 바로 나왔습니다.
try {
await fetch(url);
} catch (e) {
console.log(e.name + ': ' + e.message);
if (e.cause) console.log('cause:', e.cause.code, e.cause.message);
}비슷하게 생긴 세 가지 메시지가 서로 다른 상황을 가리킵니다. 서버가 인증서를 어떻게 보내느냐에 따라 코드가 갈립니다. 세 경우를 각각 띄워 확인한 결과입니다.
서버가 리프 인증서만 보냄 → UNABLE_TO_VERIFY_LEAF_SIGNATURE unable to verify the first certificate
서버가 사설 루트까지 체인으로 보냄 → SELF_SIGNED_CERT_IN_CHAIN self-signed certificate in certificate chain
자기서명 인증서 하나만 씀 → DEPTH_ZERO_SELF_SIGNED_CERT self-signed certificate세 줄이 말하는 건 결국 하나입니다. 제시된 인증서를 믿을 만한 뿌리까지 이어 붙일 수 없다는 것입니다. 다만 어디가 끊겼는지가 다릅니다. 첫 번째는 체인이 중간에서 끊겼다는 뜻이라 상대 서버가 중간 인증서를 덜 보내고 있을 가능성을 먼저 봅니다. 두 번째와 세 번째는 뿌리가 공개 CA가 아니라 사설이라는 뜻이라, 그 뿌리를 믿게 해 주는 게 해결입니다.
Node는 OS의 신뢰 저장소를 쓰지 않습니다. 자기가 들고 있는 목록을 씁니다. 이게 "브라우저는 되는데 Node만 안 되는" 이유입니다. node --help의 설명이 그대로입니다. --use-bundled-ca가 번들된 CA 저장소를 사용(기본값), --use-system-ca가 시스템의 CA 저장소를 사용, --use-openssl-ca가 OpenSSL의 기본 CA 저장소를 사용입니다. 기본이 번들이니, 보안팀이 Windows나 macOS 저장소에 설치한 사내 CA는 Node의 시야에 없습니다. 브라우저는 OS 저장소를 보기 때문에 같은 주소가 멀쩡해 보입니다.
openssl s_client로 끊긴 지점을 눈으로 볼 수 있습니다. 애플리케이션 밖에서 확인하는 게 가장 빠릅니다. 재현 환경에서 리프만 보내는 서버에 붙여 보니 이렇게 나왔습니다.
$ echo | openssl s_client -connect localhost:8443 -servername localhost
verify error:num=20:unable to get local issuer certificate
verify error:num=21:unable to verify the first certificate
Verification error: unable to verify the first certificate같은 명령에 -CAfile ca.pem으로 사설 CA를 알려 주자 Verification: OK로 바뀌었습니다. 즉 서버는 정상이고 신뢰 목록만 비어 있던 겁니다. -showcerts를 붙이면 서버가 실제로 보낸 인증서가 몇 장인지도 보입니다. 한 장만 보내는데 공개 CA 발급이 아니라면 서버 설정에서 체인을 다 보내도록 고쳐야 합니다.
해결 방안
-
먼저 원인 코드를 확보합니다.
fetch failed만 보고 네트워크를 뒤지면 시간을 버립니다.e.cause.code를 로그에 남기고, 위openssl s_client한 줄로 서버가 보낸 체인을 확인합니다. 이 두 가지만 있으면 "우리 신뢰 목록 문제"인지 "상대 서버 체인 문제"인지 갈립니다. -
사내 CA 파일을 Node에 알려 줍니다. 가장 흔한 상황이고, 환경변수 하나로 끝납니다.
$ NODE_EXTRA_CA_CERTS=/etc/ssl/certs/company-ca.pem node app.js재현에서 사설 CA를 이렇게 추가하자 UNABLE_TO_VERIFY_LEAF_SIGNATURE와 SELF_SIGNED_CERT_IN_CHAIN 둘 다 바로 200으로 바뀌었습니다. 주의할 점이 두 가지 있습니다.
node --help는 이 변수를 추가 CA 인증서 파일의 경로이며, 프로세스 시작 시 한 번만 읽는다고 설명합니다. 그래서 코드 안에서 process.env.NODE_EXTRA_CA_CERTS = ...로 설정하는 건 아무 효과가 없습니다. 실제로 그렇게 해 봤더니 그대로 실패했습니다. 실행 명령이나 서비스 설정, Dockerfile의 ENV에 넣어야 합니다.
그리고 경로를 틀리면 조용히 넘어가지 않고 경고만 남깁니다. 없는 경로를 줬을 때 나온 문구입니다.
Warning: Ignoring extra certs from `/tmp/nope.pem`, load failed: error:80000002:system library::No such file or directory에러가 아니라 경고라서 "설정했는데 안 된다"로 이어지기 쉽습니다. 설정한 뒤에는 꼭 호출이 실제로 성공하는지로 확인합니다. OS 저장소에 이미 사내 CA가 설치돼 있다면 --use-system-ca로 그 저장소를 쓰게 하는 방법도 있습니다.
- 코드로 해결할 때는 요청 단위로 좁힙니다. 특정 내부 API 하나만 사설 인증서를 쓰는 경우라면, 프로세스 전체의 신뢰 목록을 건드리기보다 그 요청에만 CA를 주는 쪽이 안전합니다.
const https = require("https");
const ca = fs.readFileSync("/etc/ssl/certs/company-ca.pem");
https.get(url, { ca }, (res) => { /* ... */ });재현에서 이 방식만으로 같은 서버에 200을 받았습니다. 영향 범위가 그 요청으로 끝나는 게 장점입니다. axios나 node-fetch처럼 에이전트를 받는 라이브러리는 new https.Agent({ ca })를 넘기면 같습니다.
- 도구마다 CA를 알려 주는 방법이 따로 있습니다. Node만 고쳐 놓고
npm install에서 다시 막히는 일이 흔합니다. npm 설정 문서에 따르면cafile은 하나 또는 여러 개의 CA 서명 인증서가 담긴 파일의 경로이고,ca는 레지스트리와의 SSL 연결에서 신뢰할 CA 서명 인증서입니다.
$ npm config set cafile /etc/ssl/certs/company-ca.pemcurl은 --cacert로 그 전송에만 CA를 지정할 수 있고, CURL_CA_BUNDLE이나 SSL_CERT_FILE 환경변수도 지원합니다. 재현에서 --cacert ca.pem을 주자 (60) 에러 없이 응답이 왔습니다. Java는 또 별도의 신뢰 저장소를 쓰니 keytool로 넣어야 하고, Python requests는 REQUESTS_CA_BUNDLE을 봅니다. 한 번 받은 사내 CA 파일을 팀 문서에 경로와 함께 적어 두면 사람마다 헤매지 않습니다.
- 검증을 끄는 방법은 알아 두고 쓰지 않습니다. 검색하면 가장 먼저 나오는 해결책이고, 실제로 즉시 통과합니다. 재현에서도 그랬습니다. 다만 Node가 경고를 같이 띄웁니다.
Warning: Setting the NODE_TLS_REJECT_UNAUTHORIZED environment variable to '0' makes TLS
connections and HTTPS requests insecure by disabling certificate verification.node --help의 설명도 0으로 설정하면 TLS 인증서 검증을 비활성화한다입니다. 코드 쪽의 rejectUnauthorized: false, npm의 strict-ssl=false, curl의 -k도 모두 같은 일을 합니다. 이걸 켜면 중간에서 누가 트래픽을 가로채 다른 인증서를 내밀어도 그대로 통과합니다. 사내 프록시를 통과하려고 켠 설정이 "누구의 프록시든 통과"가 되는 셈입니다. curl 공식 문서도 검증을 건너뛰는 건 강력히 피하라고 하면서, 프로덕션에서는 절대 하지 말라고 적어 두었습니다.
급할 때 로컬에서 잠깐 쓰는 것까지 막을 필요는 없지만, 그 설정이 커밋되거나 Dockerfile에 들어가면 그때부터는 되돌리기 어렵습니다. 2번과 3번이 몇 분이면 끝나는 작업이니, 그쪽으로 가는 게 거의 항상 낫습니다. 특히 NODE_TLS_REJECT_UNAUTHORIZED=0을 CI나 운영 환경변수에 넣어 두는 건 그 서비스의 모든 외부 호출에서 검증을 끄는 일입니다.
마지막으로, 원인 코드가 UNABLE_TO_VERIFY_LEAF_SIGNATURE이고 상대가 공개 CA 인증서를 쓰는 서비스라면 우리 쪽이 아니라 상대 서버 설정을 알려 주는 게 맞습니다. 중간 인증서를 포함한 체인 파일로 바꾸면 해결되는 문제를, 호출하는 모든 클라이언트가 각자 땜질하고 있을 수도 있습니다.
댓글0
아직 댓글이 없어요. 첫 댓글을 남겨 보세요.
댓글을 남기려면 로그인이 필요해요. 로그인