[Java] 사내망에서 Gradle 빌드 시 PKIX 인증서 오류 해결기 (feat. 프록시 & 인증서 등록)

최근 사내 개발 환경에서 Gradle 기반의 Spring Boot 프로젝트를 빌드하는 과정에서 아래와 같은 에러를 겪었다.

Could not resolve org.springframework.boot:spring-boot-gradle-plugin:2.7.14
PKIX path building failed: unable to find valid certification path to requested target

처음에는 단순히 버전 오류나 저장소 설정 문제인 줄 알고 build.gradle과 settings.gradle을 점검했지만, 문제는 훨씬 더 깊은 곳에 있었다. 아래는 내가 이 문제를 해결해 나갔던 순차적인 과정이다.

1. Gradle 설정 점검부터 시작

// settings.gradle
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}
rootProject.name = '프로젝트이름'

// build.gradle
plugins {
    id 'org.springframework.boot' version '2.7.14'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
    id 'java'
}
repositories {
    gradlePluginPortal()
    mavenCentral()
}

위 설정은 완벽했고, Java 11과 Gradle 8.2.1을 사용하는 환경도 문제 없었다. 하지만 여전히 plugin not found 또는 PKIX path building failed 오류가 발생했다.

2. curl 테스트로 확인한 프록시 존재

로컬 환경에서는 웹 브라우저를 통해 외부 Gradle Plugin Portal 접속이 가능했지만, curl 명령어로 접근할 경우 응답이 없었다. 그런데 아래 명령어로 프록시를 지정해주니 정상 응답이 나왔다. (예시: 123.123.123.123:9090)

curl -x http://123.123.123.123:9090 https://plugins.gradle.org

이걸 통해 현재 환경이 프록시를 통해서만 외부와 통신이 가능하다는 것을 확인했고, Gradle에도 프록시 설정이 필요하다는 걸 알게 됐다.

3. Gradle에 프록시 설정

gradle.properties에 다음을 추가했다.

systemProp.http.proxyHost=123.123.123.123
systemProp.http.proxyPort=9090
systemProp.https.proxyHost=123.123.123.123
systemProp.https.proxyPort=9090

Gradle은 이제 외부 요청을 시도했지만, 여전히 SSL 인증서 관련 오류가 발생했다.

4. 문제의 핵심: 사내 프록시 SSL 인증서 미신뢰

프록시를 통과해 HTTPS 요청을 하더라도, Java는 프록시 서버가 제공하는 SSL 인증서를 신뢰하지 않았다. 다음과 같은 에러가 계속 반복되었다.

PKIX path building failed: unable to find valid certification path to requested target

이 문제를 해결하기 위해 프록시에서 사용하는 SSL 인증서를 수동으로 Java의 cacerts 저장소에 등록해야 했다.

5. 인증서 추출 및 등록 (※ 핵심 포인트!)

크롬 브라우저로 https://plugins.gradle.org에 접속한 뒤 자물쇠 아이콘 → 인증서 보기 → 인증 경로 탭에서 프록시가 발급한 인증서들을 모두 하나씩 추출했다. 내 경우 총 2개(중간 + 루트 인증서)였고, 하나만 등록했을 땐 여전히 실패했다.

✅ 모든 계층(중간 + 루트 인증서)을 각각 등록해야 한다는 것이 키 포인트였다.

keytool -import -trustcacerts -keystore "$JAVA_HOME/lib/security/cacerts" \
 -storepass changeit -alias company-root -file root.crt

keytool -import -trustcacerts -keystore "$JAVA_HOME/lib/security/cacerts" \
 -storepass changeit -alias company-intermediate -file intermediate.crt

등록 후 아래 명령어로 정상 등록 여부를 확인했다.

keytool -list -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit | grep company

6. 빌드 성공 🎉

모든 인증서 등록이 끝난 뒤, 다음과 같이 빌드가 정상적으로 동작했다.

./gradlew clean build --refresh-dependencies

마무리하며

이번 경험을 통해 단순히 Gradle 설정만으로는 해결되지 않는 문제들도 있다는 걸 느꼈다. 특히 사내망에서는 프록시 + 인증서라는 이중 장벽이 존재하기 때문에, 다음과 같은 순서로 문제를 접근하면 해결이 가능하다.

✅ 문제 해결 요약

1. Gradle & Java 버전 확인
2. build.gradle, settings.gradle 정상 설정 확인
3. curl 테스트로 프록시 환경 여부 파악
4. gradle.properties에 프록시 수동 설정
5. 브라우저에서 프록시 SSL 인증서 추출 (※ 계층별로 모두!)
6. Java cacerts에 인증서 등록 (중간 + 루트)
7. Gradle 데몬 종료 후 ./gradlew build 재시도