How To Set Up Charles Proxy on macOS

MacOS Charles Analystadmin Post Cover 953x498

This guide is for anyone who needs to inspect and/or modify HTTP requests to and from your macOS or Mac OS computer. For example, if you need to inspect Adobe Analytics or Google Analytics tracking beacons from Safari or Chrome.

See here for the Charles for Windows PC Guide

macOS Charles proxy use cases:

  • QA/verify Adobe Analytics or Google Analytics tracking beacons
  • Inspect and/or transform HTTP requests to and from your PC
  • Throttle connection either to specific hosts or all hosts
  • Local proxy for websites, apps, iOS Simulator, or Android Studio
  • Set up macOS to proxy for iOS, iPhone, iPad, Android, tvOS, and Apple TV
  • Monitor tracking beacons from Safari, Chrome, Firefox, Edge
  • Proxy HTTP & HTTPS traffic for macOS Mojave and macOS Catalina

Charles Proxy is a powerful website optimization and QA tool for developers, analysts, and engineers. With Charles you can monitor exactly how your application communicates with a remote server.

Part 1 – Certificate Set Up

The first part of the guide will help you add the Charles SSL Certificate to your Mac so that Charles can decrypt any local HTTPS traffic.

Step 0 – Download and install Charles

Step 1 – Open Charles then go to Help > SSL Proxying > Install Charles Root Certificate

MacOS Charles Install Root Certificate 1024x534

Step 2 – The Keychain Access window will open up. Notice “Charles Proxy CA” shows up with an “X”.

MacOS Apple Keychain Install Charles Root Certificate Part 1 1024x692

Step 3 – Double click on “Charles Proxy CA“.

MacOS Apple Keychain Install Charles Root Certificate Part 2 1024x692

Step 4 – A new window showing the details of the Charles Proxy CA certificate will open up.

MacOS Apple Keychain Install Charles Root Certificate Part 3 1024x719

Step 5 – Expand Trust, then click into the “When using this certificate” dropdown and select “Always Trust“.

MacOS Apple Keychain Install Charles Root Certificate Part 4

Step 6 – All the options under Trust should be set to “Always Trust” as shown below.

MacOs Apple Keychain Install Charles Root Certificate Part 5 Always Trust

Step 7Close the Charles Proxy CA window. You should be prompted with a confirmation and may need to enter your admin username and password for the changes to take effect.

MacOS Apple Keychain Install Charles Root Certificate Part 6 Use Password
MacOS Apple Keychain Install Charles Root Certificate Part 7 Password

Step 8 – Back at the Keychain Access window you should see green next to the Charles certificate.

MacOS Apple Keychain Install Charles Root Certificate Part 8 Complete 1024x692

We’re done setting up the Charles SSL certificate on macOS. You may close the Keychain Access window.

Part 2 – SSL Proxying Set Up

This part will help you set up Charles so that it can decrypt HTTPS encrypted traffic.

Step 1 – Enable macOS Proxy if it is not enabled already. Click on Proxy > macOS Proxy. You should see a checkmark to indicate that the macOS proxy is enabled.

Charles Proxy Mac Proxy Menu 1024x643

Step 2 – Go to Proxy > SSL Proxying Settings

MacOS Proxy Ssl Proxying Settings 1024x814

Step 3 – Click on the “Enable SSL Proxying” checkbox, then under “Include”, click “Add“.

Charles Ssl Proxying Settings 1 1024x804

Step 4 – Enter the host and port that you want to decrypt. See the table below for common host patterns used for analytics QA and validation. Then click “OK“, then click “OK” again to go back to the main Charles window.

Common Hosts Used in Analytics QA

UsageHostPort
Adobe Analytics (3rd Party Cookies)*.omtrdc.*443
Adobe Analytics (Common FPC CNAME Option)smetrics.*443
Adobe DTM & Launch*.adobedtm.*443
Google Analytics*.google-analytics.*443
Google Tag Manager*.googletagmanager.*443
Tealium IQ*.tiqcdn.*443
Decrypt All HTTPS Requests*443
MacOS Charles Ssl Proxying Settings For Google Analytics 1024x804
MacOS Charles Ssl Proxying Settings For Google Analytics Complete 1024x804

Step 5 – Close Charles and Re-Open

Step 6 – Enter “google-analytics” as the Filter and on a new browser tab, go to https://app.analystadmin.com/, you should see the HTTPS Google Analytics tracking beacon go out.

MacOS Charles Macos Ssl Complete Set Up 1024x485

For users who only need to intercept HTTPS on your local machine (Ex: web browser), you can stop here.

iOS Simulator Charles Proxy Set Up

This part only applies to users who need to proxy traffic from a simulated iOS device.

Step 0 – Install XCode from the Mac App Store.

Step 1 – In Charles, go to Help > SSL Proxying > Install Charles Root Certificate in iOS Simulators.

Install Charles Root Certificate On Ios Simulator 1024x595

Step 2 – You should see the confirmation message shown below. Click “OK“.

Charles Root Certificate Has Been Added To Ios Simultor 1024x212

Step 3 – Open up the iOS Simulator. Enter Command + Space Bar and type “Simulator”, then open the Simulator app.

Ios Simulator 517x1024

Step 4 – In Charles, filter by “google-analytics“, and on the iOS Simulator go to https://www.analystadmin.com/. You should see the Google Analytics pageview HTTPS request captured in Charles.

Ios Simulator With Charles Proxy Running 1024x555

You’re done! Now you have a macOS computer that can proxy local traffic as well as external traffic from phones and tablets.

Common Issues with Charles Proxy

SymptomTroubleshooting Tips
Charles shows garbled text in HTTPS request content– Check that Enable SSL Proxying is checked in SSL Proxying Settings
– Check that your host list contains the host that you are looking to decrypt
– Check that the Charles SSL Certificate is installed on your Mac or external device (whichever device sends out the data needs to have the certificate installed)
Charles doesn’t show any requests or Charles shows fewer requests than expected– Check that you have no active VPN connections. Charles often times doesn’t work well over VPN
– Check that you have started recording (the red/black button on the main Charles toolbar)
– Try removing your request filter
– Uncheck “Focused” to make sure there are no filters under Focused Hosts
– If browser testing, disable all add blocker and cross-check with another browser
– If you are attempting to proxy an external device, make sure that you are on the same network.
– Offices sometimes have strict firewalls and router settings that may block proxying in general or specifically block port 8888, which Charles listens on. Check with IT or try proxying with a more advanced hotspot Charles method.

Leave a Reply

Your email address will not be published. Required fields are marked *