지니제스트 테크 블로그 배너
지니제스트Tech Archive
모바일8분 소요

안드로이드 Cleartext 차단과 로컬 API 연결 실패 해결

•
지지니제스트
•조회 3

안드로이드 앱에서 PC의 로컬 API 서버를 호출할 때 나는 ECONNREFUSED와 CLEARTEXT not permitted를 구분하고, 에뮬레이터의 10.0.2.2, 실기기의 adb reverse, 디버그 빌드에만 들어가는 network_security_config로 해결하는 방법입니다.

안드로이드 Cleartext 차단과 로컬 API 연결 실패 해결

PC에서 http://localhost:8080으로 띄운 API 서버를 브라우저나 Postman으로 부르면 잘 되는데, 안드로이드 앱에서 부르면 실패합니다. 이때 나오는 오류는 보통 둘 중 하나이고, 원인이 전혀 다릅니다.

오류 의미
ECONNREFUSED, Failed to connect to /127.0.0.1:8080 주소가 잘못돼 엉뚱한 곳에 연결함
CLEARTEXT communication to ... not permitted 주소는 맞는데 앱이 평문 HTTP를 막음

첫 번째는 네트워크 경로 문제, 두 번째는 앱의 보안 정책 문제입니다. 하나를 고치면 다른 하나가 나타나는 경우가 많아서 순서대로 보겠습니다.


localhost가 가리키는 곳

앱 안에서 localhost나 127.0.0.1은 PC가 아니라 안드로이드 기기 자신입니다. 기기 안에는 8080을 리슨하는 서버가 없으니 바로 연결이 거부됩니다.

안드로이드 에뮬레이터는 가상 라우터 뒤의 10.0.2.0/24 네트워크에서 동작합니다. Android Developers 문서 기준으로 주소는 이렇게 정해져 있습니다.

  • 10.0.2.2: 개발 PC의 루프백(127.0.0.1)으로 연결되는 특별한 주소
  • 10.0.2.3: 첫 번째 DNS 서버
  • 10.0.2.15: 에뮬레이터 자신의 네트워크 주소
  • 127.0.0.1: 에뮬레이터 자신의 루프백

그래서 에뮬레이터에서는 http://10.0.2.2:8080으로 부르면 PC의 서버에 닿습니다. USB로 연결한 실기기는 이 주소를 쓸 수 없습니다. 같은 Wi-Fi에서 PC의 사설 IP로 부를 수도 있지만, 공유기의 AP 격리나 PC 방화벽에 막히는 경우가 많습니다.

실기기에는 adb reverse가 깔끔합니다. 기기의 포트를 USB를 통해 PC의 포트로 이어 줍니다.

BASH
adb reverse tcp:8080 tcp:8080
adb reverse --list

이제 기기 안의 http://localhost:8080이 PC의 8080으로 연결됩니다. 에뮬레이터에서도 같은 명령이 동작하니, adb reverse를 쓰면 에뮬레이터와 실기기 모두 엔드포인트를 localhost:8080 하나로 맞출 수 있습니다. 이 연결은 기기를 다시 꽂거나 adb 서버가 재시작되면 사라지니, 자주 쓰면 실행 스크립트에 넣어 둡니다.

서버가 어느 주소에서 리슨하는지도 봅니다. 10.0.2.2와 adb reverse는 PC의 루프백으로 들어오므로 127.0.0.1에만 리슨해도 됩니다. 같은 Wi-Fi에서 PC IP로 접속한다면 0.0.0.0에서 리슨해야 합니다.


평문 HTTP 차단

주소를 고치면 이번에는 이런 예외가 납니다.

TEXT
java.net.UnknownServiceException: CLEARTEXT communication to 10.0.2.2 not permitted by network security policy

HttpURLConnection이라면 Cleartext HTTP traffic to 10.0.2.2 not permitted입니다. 앱의 targetSdkVersion이 28(Android 9) 이상이면 평문 HTTP가 기본으로 막혀 있고, OkHttp 같은 HTTP 클라이언트가 연결 전에 이 정책을 확인해 요청을 보내지 않습니다. 서버 로그에 아무 기록도 남지 않는 이유입니다.

가장 쉬운 방법은 매니페스트에 android:usesCleartextTraffic="true"를 넣는 것이지만, 이 설정은 릴리스 빌드의 모든 통신에서 평문을 허용합니다. 실수로 http:// 주소를 쓰는 코드나 SDK가 있어도 막히지 않게 됩니다. 개발용 주소만, 디버그 빌드에서만 허용하는 것이 맞습니다.


디버그 빌드에만 들어가는 설정

네트워크 보안 구성 파일로 특정 호스트에만 평문을 허용할 수 있습니다. 여기서 흔히 하는 실수가 두 가지 있습니다.

  • <domain-config>는 빌드 종류를 구분하지 않습니다. src/main에 넣으면 릴리스에도 들어갑니다. <debug-overrides>는 이름과 달리 신뢰할 인증서만 바꿀 수 있고 평문 허용은 바꾸지 못합니다.
  • <domain>에는 호스트 이름이나 IP를 하나씩 적습니다. 192.168.0.0/16 같은 대역 표기는 지원하지 않습니다.

그래서 Gradle 소스 세트를 씁니다. src/debug/res에 같은 이름의 리소스를 두면 디버그 빌드에서만 src/main/res의 것을 덮어씁니다.

src/main의 network_security_config는 평문을 모두 막고, src/debug의 같은 이름 파일은 10.0.2.2와 localhost만 허용하며, Gradle이 디버그 APK에는 debug 파일을, 릴리스 APK에는 main 파일을 넣는 구조
같은 이름의 리소스를 debug 소스 세트에 두면 디버그 빌드에서만 바뀐다

XML
<!-- app/src/main/res/xml/network_security_config.xml -->
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="false" />
</network-security-config>
XML
<!-- app/src/debug/res/xml/network_security_config.xml -->
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="false" />
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="false">10.0.2.2</domain>
        <domain includeSubdomains="false">localhost</domain>
        <domain includeSubdomains="false">127.0.0.1</domain>
    </domain-config>
</network-security-config>

매니페스트는 src/main에서 한 번만 연결합니다.

XML
<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >

networkSecurityConfig를 지정하면 Android 7.0 이상에서는 매니페스트의 usesCleartextTraffic 값이 무시되고 이 파일이 기준이 됩니다. 릴리스 APK를 만든 뒤 Android Studio의 Build > Analyze APK로 res/xml/network_security_config.xml을 열어 평문 허용이 빠져 있는지 확인합니다.


확인 순서

BASH
# 디버그 빌드 설치
./gradlew installDebug

# 포트 연결 (실기기 또는 localhost를 쓰는 경우)
adb reverse tcp:8080 tcp:8080

# 앱 로그에서 HTTP 요청과 예외 보기
adb logcat -s OkHttp AndroidRuntime

OkHttp 로깅 인터셉터를 켜 두었다면 --> GET http://localhost:8080/...와 <-- 200 줄로 요청이 오간 것을 볼 수 있습니다. CLEARTEXT 예외가 다시 나면 설치된 빌드가 정말 디버그 빌드인지, 디버그 설정 파일의 호스트 이름이 앱에서 쓰는 주소와 정확히 같은지 봅니다. localhost와 127.0.0.1은 다른 항목입니다.


같이 겪는 문제

React Native 개발 빌드는 템플릿에서 디버그 빌드의 평문 통신을 이미 허용해 둡니다. 그래서 Metro(기본 8081)에 연결이 안 된다면 대부분 정책이 아니라 경로 문제이고, 실기기에서는 adb reverse tcp:8081 tcp:8081이 필요합니다. 직접 networkSecurityConfig를 지정했다면 그 파일이 우선하니 디버그 설정에 localhost가 들어 있는지 확인합니다.

로컬 서버에 자체 서명 인증서로 HTTPS를 붙였다면 CertPathValidatorException이 납니다. targetSdk 24 이상 앱은 사용자가 설치한 CA를 기본으로 신뢰하지 않기 때문입니다. 이 경우는 <debug-overrides>가 맞는 도구입니다. 디버그 소스 세트의 설정 파일에 넣으면 디버그 빌드에서만 그 CA를 신뢰합니다.

XML
<debug-overrides>
    <trust-anchors>
        <certificates src="@raw/local_ca" />
        <certificates src="system" />
    </trust-anchors>
</debug-overrides>

참고 자료