Configuring App Transport Security Exceptions in iOS and macOS Apps

Useful answer

To permit a specific domain to use plain-text HTTP while keeping App Transport Security active for all other hosts, add an NSExceptionDomains entry for that domain in the app’s Info.plist. This leaves the default ATS policy — HTTPS with TLS 1.2 or later, forward secrecy, and SHA-256 or stronger certificates — intact everywhere else.

How ATS works and the exception mechanism

ATS is enforced by the system URL loading stack — NSURLSession, CFURLConnection, WKWebView — on iOS 9+ and macOS 10.11+. When a request is made, the stack checks the URL against the ATS policy defined in Info.plist. If no matching exception is found, the request must satisfy ATS requirements or it is blocked.

An exception is declared under the NSAppTransportSecurity dictionary. NSExceptionDomains lets you relax requirements per domain, such as allowing insecure HTTP loads or lowering the minimum TLS version.

Worked configuration example

The following snippet allows HTTP loads for example.com and all its subdomains, while preserving ATS for every other host.

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>example.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSThirdPartyExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSThirdPartyExceptionMinimumTLSVersion</key>
            <string>TLSv1.0</string>
        </dict>
    </dict>
</dict>

Place this block inside the top-level dict of your app’s Info.plist. No other changes are required.

Verification

1. Edit Info.plist in the project directory with write access.
2. Build the app for a simulator or device, for example with xcodebuild, then run it.
3. In the app, attempt to load http://example.com/resource using NSURLSession or WKWebView. The request should succeed for the excepted domain.
4. Attempt to load an HTTP resource from a non-excepted host. Inspect the console output for messages like 'App Transport Security has blocked a cleartext HTTP request' to confirm ATS is active for non-excepted domains.
5. Optional: use a network proxy such as Charles to verify that TLS handshake parameters for allowed HTTPS connections meet ATS minima.

Limits and common mistakes

• ATS only applies to system URL loading APIs. Direct socket code or third-party libraries that bypass NSURLSession are not protected.
• Disabling ATS globally with NSAllowsArbitraryLoads set to true can lead to App Store rejection unless a justified privacy and security explanation is provided.
• Misspelling the domain name in NSExceptionDomains or omitting NSIncludesSubdomains when subdomains are needed causes the exception to be ignored and produces hard-to-debug connection failures.
• Setting NSThirdPartyExceptionMinimumTLSVersion to an outdated value weakens security for that domain. Prefer the default TLS 1.2+ requirement.
• Changes to Info.plist require a clean rebuild; re-running without rebuilding may use cached settings.

Rollback

If you need to revert, delete the NSExceptionDomains entry or the specific domain dictionary from Info.plist, rebuild, and redeploy. The app will then enforce the default ATS policy for all hosts.