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.