iOS ATS Exception Configuration in Info.plist

To enable HTTP connections for example.com in your iOS app, you need to add an exception domain configuration in your Info.plist file under the NSAppTransportSecurity dictionary. The recommended approach is to use NSExceptionDomains to specify exact domains that need HTTP access while keeping ATS enabled for other domains.

Contents

• Understanding App Transport Security
• Basic Configuration for example.com
• Advanced Exception Settings
• Step-by-Step Implementation Guide
• Security Considerations
• Common Issues and Troubleshooting
• Alternative Approaches

Understanding App Transport Security

App Transport Security (ATS) is a security feature introduced by Apple that enforces best practices for network connections in iOS apps. By default, ATS requires all network connections to use HTTPS with specific security requirements. When your app attempts to make an HTTP connection to example.com, ATS blocks it and displays the error message you encountered.

ATS aims to:

• Prevent accidental insecure connections
• Force developers to use secure HTTPS connections
• Protect user data from interception and tampering

However, there are legitimate cases where you might need to connect to services that don’t support HTTPS yet, such as development servers, legacy APIs, or third-party services under your control.

Basic Configuration for example.com

The most straightforward way to allow HTTP connections to example.com is by adding an exception domain configuration to your Info.plist file. Here’s the minimal configuration needed:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>example.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
        </dict>
    </dict>
</dict>

This configuration:

• Enables HTTP connections to example.com and its subdomains
• Maintains ATS security for all other domains
• Is the recommended approach for production apps that need specific HTTP connections

Important: The domain name in the plist must match exactly how it appears in your code. If you use http://www.example.com in your code, you should specify www.example.com in the plist, not just example.com.

Advanced Exception Settings

For more granular control over the exception, you can add additional keys to your configuration:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>example.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSExceptionMinimumTLSVersion</key>
            <string>TLSv1.2</string>
            <key>NSExceptionRequiresForwardSecrecy</key>
            <true/>
            <key>NSRequiresCertificateTransparency</key>
            <true/>
        </dict>
    </dict>
</dict>

Available Exception Keys:

According to the Apple Developer documentation, using these keys allows you to maintain security while making exceptions for specific domains.

Step-by-Step Implementation Guide

Method 1: Using Xcode Property List Editor

1. Open your project in Xcode
2. Select your app target in the Project Navigator
3. Open the Info.plist file
4. Right-click in the empty area and choose “Add Row”
5. Add the key: NSAppTransportSecurity
6. Set the type: Dictionary
7. Click the triangle to expand the NSAppTransportSecurity dictionary
8. Add a new row: NSExceptionDomains (type: Dictionary)
9. Add your domain: example.com (type: Dictionary)
10. Configure the exception settings:
    • NSIncludesSubdomains: Boolean (true)
    • NSExceptionAllowsInsecureHTTPLoads: Boolean (true)

Method 2: Editing Info.plist as Source Code

1. Right-click on Info.plist in Xcode
2. Choose “Open As” → “Source Code”
3. Add the following XML inside the top <dict> element:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>example.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
        </dict>
    </dict>
</dict>

Method 3: Using CocoaPods or Build Settings

For more complex configurations, you can use build settings. As shown in the Corona Labs documentation, you can configure ATS in your build.settings file:

settings = {
    iphone = {
        plist = {
            NSAppTransportSecurity = {
                NSExceptionDomains = {
                    ["example.com"] = {
                        NSIncludesSubdomains = true,
                        NSThirdPartyExceptionAllowsInsecureHTTPLoads = true,
                    },
                },
            },
        },
    },
}

Security Considerations

When using ATS exceptions, consider these security best practices:

1. Use Specific Domain Exceptions

Avoid using NSAllowsArbitraryLoads = true as it disables ATS completely for your app. Instead, specify exact domains that need exceptions.

2. Limit the Scope

Only add exceptions for domains you control or trust. According to Apple’s guidelines, you should:

• Use the most restrictive configuration possible
• Test thoroughly to ensure only intended connections bypass ATS
• Document why each exception is necessary

3. Consider Temporary Exceptions

For development purposes, you might want to use conditional compilation to enable ATS exceptions only in debug builds:

#if DEBUG
    // ATS exception configuration
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSExceptionDomains</key>
        <dict>
            <key>example.com</key>
            <dict>
                <key>NSIncludesSubdomains</key>
                <true/>
                <key>NSExceptionAllowsInsecureHTTPLoads</key>
                <true/>
            </dict>
        </dict>
    </dict>
#endif

Common Issues and Troubleshooting

Issue 1: Still Getting the Error After Configuration

Solution: Double-check that:

• The domain name in the plist matches exactly what you’re using in code
• You’re not using https://example.com when the exception is for http://example.com
• The plist syntax is correct (all tags properly closed)

Issue 2: Subdomain Not Working

Solution: Ensure NSIncludesSubdomains is set to true and verify the subdomain name matches exactly.

Issue 3: App Store Rejection

Solution: Apple has been strict about ATS exceptions since iOS 10. According to Stack Overflow discussions, you should:

• Document why you need the exception
• Use the most restrictive configuration possible
• Consider using HTTPS instead if possible

Issue 4: Third-Party Content Still Blocked

Solution: Use NSThirdPartyExceptionAllowsInsecureHTTPLoads instead of or in addition to NSExceptionAllowsInsecureHTTPLoads.

Alternative Approaches

1. Server-Side Proxy

Instead of making direct HTTP requests, set up a secure HTTPS proxy server that forwards requests to the HTTP service. Your app communicates with the proxy via HTTPS, maintaining end-to-end security.

2. Network Extension

For enterprise apps, consider using a Network Extension to modify network traffic while maintaining security at the app level.

3. Hybrid Approach

Use different configurations for different build targets:

• Debug: More permissive ATS settings
• Release: Minimal exceptions or no exceptions

According to the Mobix documentation, you can configure different ATS settings for different app configurations.

Conclusion

Enabling HTTP connections for example.com in your iOS app requires configuring ATS exceptions in Info.plist. Here are the key takeaways:

1. Use NSExceptionDomains to specify exact domains that need HTTP access
2. Configure minimal exceptions with NSIncludesSubdomains and NSExceptionAllowsInsecureHTTPLoads
3. Maintain security by avoiding blanket ATS disabling
4. Test thoroughly to ensure only intended connections bypass ATS
5. Document your exceptions for App Store review and maintenance

The recommended configuration for example.com is:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>example.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
        </dict>
    </dict>
</dict>

Remember to review Apple’s current App Transport Security guidelines before submitting to the App Store, as requirements may evolve over time.

Sources

1. Apple Developer - Fine-tune your App Transport Security settings
2. Stack Overflow - Transport security has blocked a cleartext HTTP
3. Google for Developers - App Transport Security
4. CocoaCasts - How To Add App Transport Security Exception Domains
5. Corona Labs - Managing App Transport Security
6. Apple Developer Documentation - NSExceptionDomains
7. Hacking with Swift - How to handle the HTTPS requirements in iOS with App Transport Security