Android Network Security Configuration

WHY IT EXISTS: Before Android 7.0, customizing network security policies like trusting a self-signed certificate required writing complex, error-prone code using APIs like SSLSocketFactory. This made it difficult to manage security rules consistently, especially when distinguishing between debug and release builds.

THE MENTAL MODEL: Think of Network Security Configuration as a declarative rulebook for your app's outgoing connections. Instead of telling your app how to verify a certificate in your code, you simply declare what to trust in a separate XML file. This cleanly separates security policy from application logic.

HOW IT WORKS: You create an XML file (e.g., network_security_config.xml) in your app's res/xml directory and reference it from your AndroidManifest.xml. Inside this file, you define configurations for specific domains or a default base configuration. These rules let you control settings like cleartext traffic permissions and trust anchors. For example, you can set a base config to block all cleartext (HTTP) traffic, then create a domain-config to make an exception for a specific legacy domain. The system then automatically applies these policies to all network requests made by your app.

WHEN TO USE IT: This is the standard approach for several key scenarios. First, to enforce HTTPS-only connections by disabling cleartext traffic. Second, to trust custom Certificate Authorities (CAs), such as self-signed certificates used in a development or staging environment, without modifying production code. Third, to implement certificate pinning, which restricts connections to servers with specific, known certificates to prevent man-in-the-middle attacks.

WHEN NOT TO USE IT: Avoid using it to create overly permissive rules in production. For example, do not create a configuration that globally allows cleartext traffic or trusts all user-added CAs. These actions defeat the purpose of modern transport security and expose your users to network-based attacks. If you must allow an insecure connection, always scope the rule to the specific domain that requires it.

ONE CANONICAL EXAMPLE: A common task is allowing an old, HTTP-only API to function in an otherwise secure app. Since apps targeting Android 9 (API 28) and higher block cleartext by default, you must create an exception. Your config would have a base-config with cleartextTrafficPermitted="false" and a specific domain-config with cleartextTrafficPermitted="true" that includes the domain legacy.api.example.com. This allows the one exception without compromising security for all other connections.