SysTecevo

Androidの「Cleartext HTTP traffic not permitted」とは？原因・HTTPS移行・Network Security Configの対処法

初回掲載日:
最終更新日:

AndroidアプリのHTTP通信とHTTPS通信、Cleartext HTTPエラーを整理したオリジナル図解

Androidアプリで Cleartext HTTP traffic not permitted と表示されたら、アプリが暗号化されていない http:// 通信を行おうとして、現在のネットワークセキュリティポリシーに止められています。

先に結論：本番の解決策は、API・画像・WebViewなどの接続先を https:// に移行することです。開発中のローカル通信だけを例外にしたい場合は、アプリ全体を無条件で許可するのではなく、対象ドメインとデバッグ時に限定して設定します。

この記事で分かること

  • Cleartext HTTPとは何か、なぜAndroid 9（API 28）以降で問題になりやすいのか
  • HTTPS化、usesCleartextTraffic、Network Security Configurationの使い分け
  • 開発用の例外をreleaseビルドへ持ち込まないための考え方
  • APIだけでなく画像・WebView・外部SDKも含めて原因を探す手順
  • 修正後にdebug / releaseの両方で確認するチェックリスト

Cleartext HTTP traffic not permittedの意味

Cleartext（クリアテキスト）通信は、TLSで暗号化されていないHTTP通信です。URLが http:// で始まる場合、通信内容の盗聴や改ざんのリスクがあります。Androidの公式ドキュメントでは、Android 9（API 28）以降を対象にするアプリではcleartext通信が既定で無効になります。一方、Android 8.1（API 27）以下を対象にしたアプリでは既定値が異なります。

このエラーは、必ずしも「サーバーが落ちた」という意味ではありません。まず、アプリが実際にどの http:// URLへ接続しようとしたのかを特定してください。HTTPSの証明書エラーやDNSエラーとは、確認する場所が異なります。

HTTP通信のブロックとHTTPS、Network Security Configurationの限定例外を比較するオリジナル図解
本番はHTTPS、開発時の例外は対象を絞って扱います。

まず確認する5つのポイント

  1. URL：ログ、例外、設定ファイルから http:// の接続先を探します。APIだけでなく、画像URL、WebView、音声・動画、外部SDKも対象です。
  2. 対象SDK：アプリの targetSdk と実機・エミュレーターのAndroidバージョンを確認します。
  3. HTTPS対応：同じホストがHTTPSで提供されているか、リダイレクト任せではなく実際のHTTPS URLで確認します。
  4. 設定の適用先：debug用のmanifestやNetwork Security Configurationだけを変更して、releaseにも効くと思い込まないようにします。
  5. 実機テスト：debugビルドで直っても、releaseビルド、実機、主要画面、画像読み込みまで再確認します。

対処方法の比較

方法範囲使う場面注意点
接続先をHTTPSへ変更必要な通信だけ本番の基本解決サーバー、証明書、URL、リダイレクトも確認
usesCleartextTraffic="true"アプリ全体に広く影響管理下のレガシー環境など攻撃面を広げるため、安易な恒久設定にしない
domain-config指定ドメイン限定した開発用ホストなど対象ドメインとsubdomain設定を明示する
debug-overridesdebug時開発・テストだけの例外releaseへ例外を持ち込まない構成にする

最優先の解決策：HTTPSへ移行する

本番API、画像配信、WebViewのページ、外部サービスのURLを https:// に変更します。単にHTTPからHTTPSへリダイレクトするだけでなく、アプリが最初からHTTPSへ接続するようにしてください。HTTP接続を残したままアプリ全体のcleartext許可を有効にする方法は、エラーを隠すだけになり、通信の保護という本来の目的から外れます。

HTTPSへ移行できない古いサービスがある場合は、提供元の対応計画、認証情報の送信有無、通信内容の機密性を確認し、例外を残すリスクを明示したうえで判断します。

開発中だけ特定ドメインを許可する

AndroidのNetwork Security Configurationは、マニフェストからXMLを参照して通信ポリシーを宣言する仕組みです。次の例は、原則としてcleartextを禁止し、開発用のホストだけを例外にする考え方です。ドメイン名は実際の開発環境に置き換えてください。

<!-- res/xml/network_security_config.xml -->
<network-security-config>
    <base-config cleartextTrafficPermitted="false" />
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">dev.example.test</domain>
    </domain-config>
</network-security-config>
<!-- AndroidManifest.xml -->
<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >

この設定は「安全になった」という意味ではありません。指定ホストへのHTTP通信を許可するため、開発専用のホスト・用途に限定してください。公開ビルドへ混入していないか、release APK/AABの設定と動作を確認します。

アプリ全体の許可を使う場合の注意

android:usesCleartextTraffic="true" は、アプリの広い範囲へcleartext通信を許可する設定です。既存のHTTPサービスを一時的に検証する場合でも、対象を限定できるNetwork Security Configurationを優先できないか検討してください。Androidのバージョン、target SDK、使用するネットワークライブラリによって適用されるポリシーの見え方が異なる場合があるため、最終的には実際のクライアントでテストします。

エラー別の確認表

症状原因候補次に確認すること
API呼び出し時に発生ベースURLがHTTP環境変数、BuildConfig、Retrofit等のbase URLを確認
画像だけ表示されない画像CDNや保存URLがHTTPレスポンスの画像URLと画像ライブラリのログを確認
WebViewだけ失敗読み込むページやリソースがHTTPページ内の混在コンテンツ、リダイレクト先を確認
debugは成功、releaseは失敗debug専用設定に依存release manifest、XML、サーバーURLを比較
HTTPSへ変えたら別エラー証明書、ホスト名、TLS、DNSなどcleartext問題と切り分けてHTTPS側を調査
Cleartext HTTPエラーをHTTPS化または開発用の限定例外へ分岐して検証するオリジナルフロー図
エラーを消すことではなく、通信先とビルド種別を分けて解決します。

release前チェックリスト

  • http:// のAPI、画像、WebView、外部SDKのURLを洗い出した
  • 本番接続先をHTTPSへ変更し、証明書とホスト名も確認した
  • usesCleartextTraffic を広く有効にしたままにしていない
  • Network Security Configurationの例外が開発用ドメインだけになっている
  • debug-overridesやdebug manifestの設定がreleaseに入っていない
  • releaseビルドを実機で起動し、ログイン、API、画像表示を確認した
  • ネットワークライブラリ独自のポリシーも公式仕様に照らして確認した

よくある質問

Q. Android 9未満なら何もしなくてよいですか？

いいえ。既定値が異なる場合でも、暗号化されていない通信のリスクは変わりません。本番通信はHTTPSを基本にします。

Q. usesCleartextTraffic="true" にすれば直りますか？

許可される範囲ではエラーが消える可能性がありますが、アプリ全体の保護を弱めるため、恒久的な解決策とは限りません。まず接続先をHTTPSへ移行し、必要なら対象を絞った開発用設定にします。

Q. localhostやエミュレーターの開発APIだけHTTPです。どうすればよいですか？

debug専用の設定、開発用ドメインのdomain-config、または開発環境自体のHTTPS化を検討します。releaseビルドが同じ例外を持たないことを必ず確認してください。

Q. このエラーはSSL証明書エラーですか？

別の問題です。今回のエラーは、暗号化されていないHTTP通信をポリシーが拒否したときのものです。HTTPS接続後に証明書エラーが出る場合は、証明書チェーンやホスト名などを別途確認します。

まとめ

Cleartext HTTP traffic not permitted は、アプリがHTTP通信を行おうとした一方で、Androidのネットワークセキュリティポリシーがcleartextを許可していないことを示します。最初に接続先を特定し、本番はHTTPSへ移行してください。開発上どうしても必要な例外は、対象ドメインとdebugビルドに限定し、releaseで残っていないことを検証するのが安全です。

公式情報