java.io.IOException: Cleartext HTTP traffic to [host] not permitted bedeutet, dass Android eine unverschlüsselte http://-Anfrage gemäß der wirksamen Netzwerksicherheitsrichtlinie der App abgelehnt hat. Dies betrifft am häufigsten Android 9 oder höher, wenn die App auf API-Level 28 oder höher ausgerichtet ist. Dazu gehören auch Anfragen über HTTP-Komponenten der Plattform sowie Media3 oder ExoPlayer. Ermitteln Sie als sicherste erste Maßnahme den genauen blockierten Host oder die Quelle der Weiterleitung und stellen Sie die Anfrage auf HTTPS um, sofern der Endpunkt dies unterstützt. Aktivieren Sie Klartextverkehr nicht global, bevor Sie das Ziel ermittelt haben.

Was „Cleartext HTTP Traffic Not Permitted“ bedeutet

Derselbe Richtlinienfehler kann als java.io.IOException: Cleartext HTTP traffic to [host] not permitted, CLEARTEXT communication to [host] not permitted by network security policy oder in der kürzeren Form Cleartext HTTP traffic not permitted erscheinen. Media3 kann außerdem den zugehörigen Fehler ERROR_CODE_IO_CLEARTEXT_NOT_PERMITTED oder CleartextNotPermittedException melden.

Diese Fehlersignaturen bedeuten, dass die App versucht hat, eine unverschlüsselte HTTP-Verbindung herzustellen, und die wirksame Richtlinie die Anfrage abgelehnt hat. Laut der Android-Dokumentation zur Netzwerksicherheitskonfiguration ist die Unterstützung von Klartextverkehr für Apps mit Ziel-API-Level 28 oder höher standardmäßig deaktiviert. Entscheidend ist das Ziel-API-Level. Allein die Tatsache, dass auf dem Gerät Android 9 oder höher ausgeführt wird, belegt nicht, wie die Richtlinie jeder App konfiguriert ist.

Dieser Leitfaden gilt, wenn eine direkte URL, eine Weiterleitung, eine Backend-Antwort, eine Medien-Playlist, eine CDN-Ressource, eine Plattformkomponente oder ein SDK eines Drittanbieters zu HTTP führt. Er gilt nicht für SSLHandshakeException, CertPathValidatorException oder android.os.NetworkOnMainThreadException, da diese auf andere Fehlerbedingungen hinweisen.

Den von Android blockierten HTTP-Endpunkt ermitteln

Ermitteln Sie das tatsächliche Laufzeitziel, bevor Sie die Anwendungsrichtlinie ändern. Die im Quellcode der Anwendung sichtbare URL muss nicht mit der URL übereinstimmen, die Android letztlich blockiert.

  1. Notieren Sie den Host, der in der Ausnahme oder in der Logcat-Ausgabe genannt wird.
  2. Prüfen Sie, ob die ursprüngliche Anfrage-URL mit http:// beginnt.
  3. Prüfen Sie, ob eine anfängliche HTTPS-Anfrage zu HTTP weiterleitet.
  4. Prüfen Sie, ob eine Backend-Antwort, Medien-Playlist oder ein CDN eine HTTP-Ressourcen-URL bereitstellt.
  5. Ermitteln Sie anhand des Stacktraces, ob die Anfrage von einer Plattformkomponente, Media3 oder ExoPlayer, WebView oder einer Bibliothek beziehungsweise einem SDK eines Drittanbieters stammt.

Die Medienwiedergabe kann selbst dann fehlschlagen, wenn die anfängliche Medien-URL korrekt erscheint, weil eine Playlist oder eine referenzierte Ressource zu HTTP führt. Die Media3-Fehlerbehebung zu Klartextverkehr von Google nennt eine HTTP-URL unter einer Richtlinie, die Klartextverkehr untersagt, als Grundlage dieser Fehlergruppe.

Direkte HTTP-URLs, Weiterleitungen zu HTTP und von einem Backend zurückgegebene HTTP-Ressourcen erfordern dieselbe erste Entscheidung: Prüfen Sie, ob genau dieses Ziel HTTPS verwenden kann. Erstellen Sie keine Domänenausnahme, bevor der tatsächliche Laufzeit-Host bekannt ist.

Lösung 1: Die fehlschlagende Anfrage auf HTTPS umstellen

Wann diese Lösung geeignet ist: Verwenden Sie diese Lösung, wenn Sie den Server oder Medienendpunkt kontrollieren oder die Quelle der URL ändern können und die Ressource über HTTPS verfügbar ist.

Voraussetzungen:

  • Sie kontrollieren den Endpunkt oder können die Quelle ändern, die seine URL bereitstellt.
  • Die Ressource ist über HTTPS verfügbar.
  1. Ändern Sie die URL-Quelle von http:// zu https://.
  2. Aktualisieren Sie Weiterleitungen so, dass sie durchgehend HTTPS verwenden.
  3. Testen Sie genau die zuvor fehlgeschlagene Anfrage oder den betreffenden Wiedergabepfad erneut.

Erwartetes Ergebnis: Wenn jede Ressource im getesteten Pfad HTTPS verwendet, sollte Android den Vorgang nicht mehr als Klartextverkehr ablehnen. Eine nachgelagerte Weiterleitung, ein Playlist-Eintrag oder eine vom Backend bereitgestellte HTTP-URL kann den Fehler weiterhin auslösen und muss gesondert geprüft werden.

Risiko und Rücknahme: Dies ist eine Konfigurationsänderung mit geringem Risiko, bei der kein Datenverlust zu erwarten ist. Stellen Sie die vorherige URL nur wieder her, wenn die HTTPS-Umstellung fehlschlägt. Weiten Sie diesen Schritt nicht auf eine unabhängige Zertifikatsfehlerbehebung aus. Fehler bei der Zertifikatsprüfung gehören nicht zum Umfang dieses Fehlers.

Das zusammengeführte Manifest und die verpackte Netzwerksicherheitsrichtlinie prüfen

Wann diese Lösung geeignet ist: Verwenden Sie diese bestätigte Diagnosemaßnahme, wenn das Quellmanifest oder die Netzwerksicherheitskonfiguration korrekt erscheint, der Laufzeit-Build die Anfrage jedoch weiterhin blockiert.

Voraussetzung: Sie müssen das zusammengeführte Manifest oder die verpackten Ressourcen des betroffenen Builds prüfen können.

  1. Prüfen Sie das zusammengeführte Manifest und nicht nur die XML-Quelldatei.
  2. Vergewissern Sie sich, dass die verpackte Datei network_security_config.xml vorhanden ist.
  3. Prüfen Sie, ob der Anfrage-Host exakt mit der erlaubten Domäne übereinstimmt.
  4. Prüfen Sie, ob eine Weiterleitung oder Playlist auf HTTP verweist.
  5. Testen Sie die betroffene Build-Variante erneut.

Erwartetes Ergebnis: Die Prüfung sollte zeigen, ob die erstellte Anwendung den vorgesehenen Verweis android:networkSecurityConfig und die verpackte Richtlinie enthält und ob diese Richtlinie den tatsächlich blockierten Host abdeckt. Sie kann außerdem zeigen, dass eine andere Build-Variante oder eine nachgelagerte HTTP-Ressource beteiligt ist.

Risiko und Rücknahme: Dies ist eine Prüfung mit geringem Risiko, ohne Datenverlustrisiko und ohne erforderliche Rücknahme. Gehen Sie nicht davon aus, dass eine Änderung an einer Quelldatei aktiv ist, bevor Sie die zusammengeführte und verpackte Ausgabe geprüft haben.

Lösung 2: Klartextverkehr nur für die erforderliche Domäne erlauben

Wann diese Lösung geeignet ist: Verwenden Sie eine domänenspezifische Ausnahme nur, wenn HTTP unvermeidbar ist und Sie das genaue Ziel ermittelt haben, das diese Ausnahme benötigt.

Voraussetzungen:

  • Die App ist auf API-Level 24 oder höher ausgerichtet.
  • Sie können den genauen Host oder die genaue Subdomain bestimmen.
  • Sie akzeptieren, dass über Klartext-HTTP übertragene Daten abgefangen oder verändert werden können.
  1. Fügen Sie eine XML-Datei für die Netzwerksicherheitskonfiguration hinzu.
  2. Legen Sie eine domain-config mit cleartextTrafficPermitted="true" ausschließlich für den erforderlichen Host fest.
  3. Lassen Sie includeSubdomains auf „false“, sofern nicht tatsächlich jede Subdomain HTTP benötigt.
  4. Verweisen Sie über android:networkSecurityConfig auf die XML-Datei.
  5. Testen Sie den blockierten Endpunkt erneut.

Erwartetes Ergebnis: Das angegebene Ziel darf möglicherweise HTTP verwenden, während für andere Ziele weiterhin die Klartextbeschränkungen der App gelten. Der Erfolg hängt davon ab, ob die konfigurierte Domäne mit dem tatsächlichen Laufzeit-Host übereinstimmt. Dies schließt Ziele von Weiterleitungen oder Medienressourcen ein.

Risiko und Rücknahme: Dies ist eine sicherheitsrelevante Änderung mit mittlerem Risiko, bei der kein Datenverlust zu erwarten ist. Klartextverkehr bleibt selbst dann anfällig, wenn das Ziel vertrauenswürdig ist. Entfernen Sie zur Rücknahme die domain-config oder stellen Sie den Endpunkt auf HTTPS um. Weiten Sie die Konfiguration nicht auf unbeteiligte Domänen aus und aktivieren Sie includeSubdomains nicht nur, damit eine Anfrage erfolgreich ist.

Verhalten je nach API-Level und der Fallback android:usesCleartextTraffic

Im relevanten Zielbereich wird Klartextverkehr ab API-Level 28 standardmäßig blockiert. Die Netzwerksicherheitskonfiguration ermöglicht ab API-Level 24 die Steuerung von Klartextrichtlinien. Für API-Level 23 und niedriger ist gemäß den zugrunde liegenden Android-Versionshinweisen zusätzlich zu einer Netzwerkkonfigurationsstrategie android:usesCleartextTraffic erforderlich.

Eine Netzwerksicherheitskonfiguration kann ab Android N Vorrang vor android:usesCleartextTraffic haben. Noch wichtiger ist, dass die offizielle Dokumentation zum Anwendungsattribut usesCleartextTraffic darauf hinweist, dass das Attribut bei Apps mit Ziel-API-Level 38 oder höher ignoriert wird. Es ist daher kein zukunftssicherer Ersatz für die Netzwerksicherheitskonfiguration.

Wann der allgemeine Fallback geeignet ist: Verwenden Sie android:usesCleartextTraffic="true" nur zur vorübergehenden Kompatibilität oder wenn in einem älteren Zielbereich der gesamte Klartextverkehr erlaubt werden muss und derzeit keine engere domänenspezifische Möglichkeit verfügbar ist.

Voraussetzungen:

  • Sie verstehen, dass diese Einstellung die Transportsicherheit umfassend schwächt.
  • Es steht Ihnen noch keine engere domänenspezifische Option zur Verfügung.
  1. Setzen Sie im Anwendungselement android:usesCleartextTraffic="true".
  2. Prüfen Sie das zusammengeführte Manifest in der erstellten APK- oder AAB-Datei.
  3. Vergewissern Sie sich, dass die App unbeabsichtigte Ziele weiterhin blockiert, falls zusätzlich eine Netzwerksicherheitskonfiguration vorhanden ist.
  4. Planen Sie die Umstellung auf eine Netzwerksicherheitskonfiguration oder HTTPS.

Erwartetes Ergebnis: In Zielbereichen, in denen das Attribut berücksichtigt wird, darf die Anwendung möglicherweise Klartextanfragen stellen, sofern keine wirksame Netzwerksicherheitskonfiguration ein anderes Verhalten vorgibt. Für Apps mit Ziel-API-Level 38 oder höher bietet das Attribut diesen Fallback nicht.

Risiko und Rücknahme: Dies ist ein sicherheitsrelevanter Fallback mit hohem Risiko, da er Klartextverkehr für die gesamte Anwendung erlauben kann. Er löscht keine Anwendungsdaten, kann übertragene Daten jedoch dem Abfangen oder Verändern aussetzen. Setzen Sie das Attribut zur Rücknahme wieder auf „false“ und entfernen Sie die HTTP-Abhängigkeiten.

Localhost, 10.0.2.2, numerische IP-Adressen, Weiterleitungen und Medien-URLs prüfen

Lokale Entwicklungsumgebungen und generierte Ressourcen-URLs erfordern eine app-spezifische Prüfung. Wenn das Ziel localhost, eine Loopback-Adresse, 10.0.2.2 oder eine numerische IP-Adresse ist, müssen Sie vor einer Richtlinienänderung den tatsächlichen Laufzeit-Host und die vorgesehene Build-Umgebung bestätigen. Berichte zu diesen Zielen sind nützliche Diagnosehinweise, belegen jedoch nicht, wie die Konfiguration einer bestimmten App den Host abgleicht.

  • Prüfen Sie, ob das Ziel ausschließlich für die Entwicklung vorgesehen ist.
  • Prüfen Sie, ob dieselbe Klartextrichtlinie unbeabsichtigt in einem Release-Build enthalten ist.
  • Untersuchen Sie Weiterleitungen, Medien-Playlists, CDN-Ressourcen und vom Backend bereitgestellte URLs auf HTTP-Ziele.
  • Ermitteln Sie, ob HttpURLConnection, OkHttp, WebView, MediaPlayer, DownloadManager, Media3, ExoPlayer oder ein SDK eines Drittanbieters den Fehler ausgegeben hat, bevor Sie komponentenspezifische Schlussfolgerungen ziehen.
  • Testen Sie den betroffenen Host und die Build-Variante manuell, statt anzunehmen, dass eine Domänenausnahme auf jedes lokale oder numerische Ziel zutrifft.

Aktivieren Sie in einer Produktions-App keinen anwendungsweiten Klartextverkehr, nur um einen Entwicklungsserver zu unterstützen. Wenn HTTP vorübergehend unvermeidbar ist, beschränken Sie jede bestätigte Ausnahme auf das erforderliche Ziel und prüfen Sie, dass sie nicht weiter gefasst ist als beabsichtigt.

Prüfen, ob der genaue Fehler ohne Ausweitung des Klartextzugriffs behoben ist

  1. Testen Sie genau die Anfrage, Weiterleitungskette oder den Wiedergabepfad erneut, die beziehungsweise der den Fehler ursprünglich ausgelöst hat.
  2. Testen Sie die betroffene Ziel-Build-Variante, statt davon auszugehen, dass eine Variante alle Builds repräsentiert.
  3. Prüfen Sie nach einer Richtlinienänderung erneut das zusammengeführte Manifest und die verpackte Netzwerksicherheitskonfiguration.
  4. Wenn Sie eine Domänenausnahme verwendet haben, vergewissern Sie sich, dass nur das erforderliche Ziel erlaubt ist und unbeteiligte HTTP-Ziele weiterhin blockiert werden.
  5. Dokumentieren Sie, ob der Build auf API-Level 28 oder höher sowie auf API-Level 38 oder höher ausgerichtet ist, bevor Sie das Verhalten der Manifestattribute beurteilen.

Der ursprüngliche Vorgang sollte ohne die Fehlersignatur der Klartextablehnung abgeschlossen werden, während für die Anwendung weiterhin die engstmögliche Richtlinie gilt. Eine Änderung an einer Quelldatei allein bestätigt nicht, dass der Fehler behoben wurde. Wenn der Fehler weiterhin auftritt, prüfen Sie erneut den Laufzeit-Host, die Weiterleitungskette, die Playlist-Ressourcen, die verpackte Konfiguration und die auslösende Bibliothek, statt die Ausnahme auszuweiten.