Charles Proxy Setup for 💻 Desktops and 📱Mobile Devices
Some test cycles require extended logging of the internet traffic from and to our devices, or a connection routed through a proxy server. For that purpose, mobile testers often deal with the Charles Web Proxy software. The goal of this post is to guide you through the first steps and the overall configuration. The procedure may seem complicated at first, but bear once we’ve finished the initial setup, its future use just requires 30 seconds to get everything ready. So let’s get started!
Agenda
- Download and Install Charles on Desktops — macOS and Windows
- Connect Mobile Devices to Charles — iOS and Android
- Install Charles CA Root Certificates — Desktops (macOS and Windows) and Mobile Phones (iOS and Android — physical and virtual)
- Capture and Decrypt SSL Traffic Using Charles
- Export Device Logs to Support Bug Reports
- Tidy Up
- Miscellaneous Issues
1. Download and Install Charles on Desktops — macOS and Windows
Although Charles is not an open-source software or a free tool, a demo version is available. It can be downloaded and used for free but limits each session to 30 minutes. Consequently, we have to restart the software now and then, if you want to use it for a more extended period.
Let’s head over to Charles Proxy’s website at https://www.charlesproxy.com/download/ and download the appropriate version for our operating system.
macOS
Let’s download and install Charles Proxy on a Mac.
Open a browser and navigate to a random site. We see new log entries popping up in the Charles log now. If that log is filling up, we are good to go.
We can stop the recording by clicking the red circle 🔴 and clear the current session with the broom 🧹.
Windows
Now let’s go through the download and installation process on Windows.
Open a browser and navigate to a random site. We see new log entries popping up in the Charles log now. If that log is filling up, we are good to go.
As before, we can stop the recording by clicking the red circle 🔴 and clear the current session with the broom 🧹.
I recorded a quick video walk-through for Windows users: https://youtu.be/koE6nwjha3k?si=cexIhGvdRO0J-ZzU.
We are done with the desktop download and installation. As soon as Charles is running, it automatically captures and records all browser traffic. This procedure typically covers the most common browsers like Chrome, Firefox, Safari, and Edge.
2. Connect Mobile Devices to Charles — iOS and Android
Configuring Charles on the phone is a little different. Important notes to keep in mind, when connecting new mobile devices:
- Make sure your phone is connected to the same WiFi as the computer it’s plugged into.
- Once a new device tries to connect to our Charles session, Charles asks to grant the permission to do so. Be sure to allow the connection.
- Also disable or appropriately configure any firewall or internet security.
As Charles is running now, we want to route all the network traffic from and to our devices through it. Depending on the device you plan to use, perform the following steps matching your device(s).
Gathering two crucial pieces of information first
Before we can configure our mobile device to use Charles, we need to know the internal IP Address of our computer (running Charles) and the Port. This can quickly be done as follows:
- In Charles on desktop, click Help ▸ Local IP Address to locate your IP. The address consists of four blocks of one to three digits each. It is
10.0.0.76in my case. It may look something like192.168.178.100in yours.
- We also need to know the port, that Charles is using. It is
8888by default, but you may check via Proxy ▸ Proxy Settings.... It is the HTTP Proxy Port. You can also click the gear icon in the toolbar and select Proxy Settings... there.
We are going to need both numbers in the next step.
Real Device
Configure Charles Proxy on a real iOS device. To connect our iOS device, let’s follow these steps:
- Go to Settings
- Tap WiFi. Select the connected WiFi network.
- Tap (i) to the right of our selected WiFi network
- Scroll down to the Configure Proxy section.
- Tap Manual.
- In the Server field, enter the IP Address retrieved earlier.
- For the Port, enter default port 8888 retrieved earlier.
- Verify that Manual configuration is on and the Router number is correct.
The settings on your device may look slightly different, but you should be able to find the right area to modify the WiFi network. It will be located around the WiFi network to which you are currently connected.
Simulator
For an iOS simulator, we don’t download and install Charles. We do install a root certificate though. Keep reading to learn more about CA root certificates.
Real Device
To connect our Android smartphone, just head to the WiFi settings and proceed as follows:
- Go to Settings ▸ Network & Internet ▸ WiFi
- Locate the active connection, tap on the gear icon ⚙️ next to it.
- In the Network details, tap the edit icon ✏️.
- Tap on Advanced options.
- Under the Proxy menu, expand options and select Manual.
- Enter the previously retrieved IP address in the Proxy hostname field and the port in the Proxy port field.
- Tap Save. Done!
Here’s also a quick video walk-through: https://youtu.be/Tsrm7T7hrjU?si=uZxU5OTRM9wuxCYN.
Emulator
Configure Charles Proxy on an Android virtual device.
- Go to the emulator’s Extended Controls ▸ Settings ▸ Proxy. Uncheck the box preceding ‘Use Android Studio HTTP proxy settings’.
- Select the ‘Manual proxy configuration’ radio button.
- For ‘Host name’ and ‘Port number’, enter the previously retrieved Local IP Address and port.
- Click Apply.
- Verify that Proxy status changed to Success.
If the proxy configuration settings don’t work in the emulator’s Extended Controls, try restarting the emulator. In case there are still issues, follow the below outlined steps.
- Go to Settings ▸ Network & internet ▸ Wi-Fi.
- Tap on the gear icon ⚙️ next to the WiFi network.
- Tap on the edit icon ✏️.
- Tap Advanced Options.
- Under the Proxy menu, expand the options and tap Manual.
- In the Host and Port fields enter the previously retrieved Local IP Address and Proxy Port respectively.
3. Install CA Root Certificates — Desktops (macOS and Windows) and Mobile Phones (iOS and Android)
As soon as customers require us to use Charles, they want to know what our mobile device is doing during its communication with their services. If this communication is encrypted, which is great for our day-to-day security, this traffic needs to be decrypted using a certificate. We are now going to install this certificate to allow Charles to listen to that communication. Let’s start with the desktops again.
Installing Desktop Certificate
macOS
Fortunately, Charles already includes this certificate and allows us to install it using the menu easily. Just follow through this process:
- Within Charles click Help ▸ SSL Proxying ▸ Install Charles Root Certificate.
After finishing the wizard, close the certificate and keychain windows, and now we are good to go. Here is a link to the diagram to reiterate the Mac root CA installation process: https://user-images.githubusercontent.com/70295997/223403200-2d226828-6555-4b59-9329-fb8c01908d2b.png.
Windows
Let’s now proceed to installing the root CA certificate on Windows.
- Within Charles click Help ▸ SSL Proxying ▸ Install Charles Root Certificate.
- In the new window click Install Certificate…
- Complete all the steps of the installation wizard.
- We should verify the certificate’s been installed as expected. Navigate to Control Panel ▸ Network and Internet ▸ Internet Options ▸ Content ▸ Certificates.
- Click on the Trusted Root Certification Authorities tab and verify the Charles Proxy CA certificate is listed.
- Alternately, verify proper installation by opening the Run window with
Win+R. Type certmgr.msc and pressEnter.
Win + R. Type certmgr.msc and press Enter.- Make sure that Charles Proxy CA is listed under Certificates-Current User ▸ Trusted Root Certification Authorities ▸ Certificates.
Now we can close the certmgr and proceed to proxying on our Windows machine.
Installing the certificate on a mobile device
To get Charles working on our phone we have to obtain a trust certificate. To install the certificate on a mobile device, we have to ensure that the device is successfully connected to our Charles session:
- Proxy is set to Manual and configured in our WiFi settings.
- Disconnect any active VPNs to avoid issues during the Charles session.
- Charles is running and the permission for our device has been granted.
- We can browse on our phone and new logging entries appear within Charles.
Real Device
- Open Safari and head to the address chls.pro/ssl (which leads to https://www.charlesproxy.com/getssl) on the mobile device.
- This downloads the certificate and should automatically open the download prompt.
- Allow the download and go to Settings.
Tap General and then Profiles & Device Management.
- Open the downloaded profile for Charles.
- The certificate is not verified/trusted. Tap Install.
- Enter the passcode, if yo have it, and then tap Install twice.
- Tap Done, once the profile is installed.
- Open the installed profile for Charles and confirm it’s now verified/trusted.
Depending on the device, additionally we may need to trust the certificate in the Settings. In that case, navigate to Settings ▸ General ▸ About ▸ Certificate Trust Settings and toggle the Charles Proxy CA on to trust it.
Now we are ready to proxy with our phone. Go to any web site on the phone, e.g., google.com. Go back to Charles on our desktop. Click on Start Recording. The log starts filling up. We are good to go!
Simulator
In our Charles on desktop, let’s go to Help ▸ SSL Proxying ▸ Install Charles Root Certificate on iOS Simulators.
The Charles Root Certificate gets added to iOS simulators.
Open an app, bing.com for example. Perform a few actions. If the logs start filling up, it’s good news!
Emulator
In our Charles on desktop, let’s go to Help ▸ SSL Proxying ▸ Install Charles Root Certificate on a Mobile Device or Remote Browser.
- On the emulator, in Chrome browser, navigate to the address chls.pro/ssl (which leads to https://www.charlesproxy.com/getssl).
- This downloads the certificate and should automatically open the download prompt.
- Allow the download and go to Settings ▸ Security ▸ More security settings.
- Go to Encryption & credentials ▸ Install a certificate ▸ CA certificate.
- A security message pops up. Click Intall anyway.
- Open the downloaded .pem file.
- Go back to the Encryption & credentials view.
- Click on Trusted credentials and verify that the Charles Proxy CA is included as a trusted certificate.
Open a random app, YouTube for example. Perform a few actions. If the logs start filling up, we are good to go.
Real Device
We can configure the Charles Root Certificate on a physical Android device basically the same way as with the virtual device.
In our Charles on desktop, let’s go to Help ▸ SSL Proxying ▸ Install Charles Root Certificate on a Mobile Device or Remote Browser.
- On our phone, in Chrome browser, navigate to the address chls.pro/ssl (which leads to https://www.charlesproxy.com/getssl).
- This downloads the certificate and should automatically open the download prompt.
- Allow and verify the download.
- On the phone, go to Settings ▸ Security & privacy ▸ More security & privacy ▸ Encryption & credentials.
- Proceed to Install a certificate. Tap CA certificate.
- A security message pops up. Click Install anyway.
- Open the downloaded .pem file. Verify identity with PIN or fingerprint.
- Go back to the Encryption & credentials view.
- Click on Trusted credentials and verify that the Charles Proxy CA is included as a trusted certificate.
Open a random app, YouTube for example. Perform a few actions. If the logs start filling up, we are good to go.
Here’s also a short video walk-through I recorded for an Android phone: https://youtu.be/PvxDnBqLPDc?si=4nQB8jhvvU0AyoR_.
Set Up Our Own Certificate
To draw the certificate-related section to a close, there are other ways of handling a certificate in more secure manner, if we don’t want to install Charles as the trusted root. This post delineates how to proceed, when we want to set up our own certificate authority (CA) and trust that instead.
4. Capture and Decrypt SSL Traffic Using Charles
Enabling HTTPS proxying
Now that are devices (desktop and mobile) are set up, we are ready to record incoming and outgoing traffic. For that we need to change our proxy settings. In incurs enabling SSL Proxying within Charles. This is rather quickly done:
- Within Charles click Proxy ▸ SSL Proxying Settings…
- In the SSL Proxying Settings tick Enable SSL Proxying and click the Add button below.
- Enter an asterisk
*as Host and443as Port - Now click OK and OK again
We may need to restart Charles afterwards.
macOS
We can tell Charles which domains we want to encrypt. Click Add under the Include section. Under Host, if we put an asterisk *, Charles will monitor all traffic. If we put an asterisk and the domain we're looking for *<domain_name>, we indicate the specific host to monitor our traffic for. It will just look for that domain, i.e., *google.com.
For the Port, we input 443.
Now, let’s open a browser, head over to google.com and perform a few actions.
Everything with a padlock icon 🔒 is not monitored and shows as <unknown>. The rule that we set is for google.com, so everything with that domain has a blue lightning icon ⚡️ next to it. It means our specific test domain traffic is being recorded, and that’s good news!
Now we can stop and save the session log in a file. More on that in the log retrieval section.
Windows
Enabling SSL proxying on Windows is identical to the Mac steps.
We may need to restart Charles afterwards.
It’s time to open a browser and navigate to some random website, e.g., google.com. Perform some actions, like search for ‘stuff’, and observe the Charles logs populating.
We set the rule to allow proxying for all domains. So, all the traffic, including the google.com domain has a blue network circle 🌐 or a lightning icon ⚡️ next to it. It means that all domain traffic is being recorded. It matches our set rule. Domain coverage can be customized, as described below.
Tailor Coverage to Our Needs
Earlier. we entered * as the Host. This wildcard character enables the SSL proxying for every possible web address or service we may visit. Thus we might want to tailor the proxying — and therefore logging — to our needs by specifically including certain domain addresses as parts of host. Using wildcards provides a very versatile way of filtering specific URLs, which we want to cover.
This can become very handy, if we want to limit the coverage to an app or page under test. Here are some examples:
googlewould cover every network traffic packet from and to google, which includes photos.google.com, google.com/mail and so on.photos.googleormeet.google.comwould include everything from and to photos.google.com and meet.google.com respectively, but not google.com/mail for instance.google.com/mailwould cover the entire mail section, but no other section such as photos.google.com. Though it would cover photos.google.com/mail/, if such websites existed.
So we take the relevant part of the address, which may include/exclude or be limited to sub-domains like calendar in calendar.google.com and replace the rest of the address with a * to allow every string or even no string (zero or more characters) in its place. We can also use the ? wildcard, which replaces exactly one single character. So go?gle would match google or goggle, but not gogle or googgle.
If we want to only record mobile traffic and avoid interference from the desktop, we should uncheck the macOS Proxy or Windows Proxy options under the Proxy menu.
In the Host section, we can enter the domain specific to our mobile app, not just a web app that’s accessed via a browser. For example, enter <mobile_app_name>.com to trace all the activities specific to that app and its endpoints such as: /api/<mobile_app_name>/login, /api/<mobile_app_name>/userinfo, or /api/<mobile_app_name>/places/getuserplaces.
In order to filter out the traffic data sequences for a specific domain, we can use the Filter feature. For example, enter ‘goog’ to isolate the logs from google.com, or ‘bing’ from bing.com respectively.
Now that Charles is running with the right settings, the root CA certificates are installed, mobile our devices are configured to use Charles on our computer, and the SSL proxying is enabled, we are set to read and log the traffic!
Log Icons
While recording a session we capture different types of traffic. Each sequence in the logs is prefixed by one of these icons:
📋 To summarize: the padlock 🔒 icon means SSL proxying is not enabled for that HTTPS host; the blue network circle 🌐 or the lightning ⚡️ icon means the traffic for our chosen test domain(s) is being recorded.
5. Export Device Logs to Support Bug Reports
It’s time to start a wrap-up by collecting the log information and exporting it. We do this in order to provide descriptive supporting documentation with a bug report. It’s only adequate that we work closely with our developers and send them a solution-oriented report not a problematic one. So, let’s be helpful and retrieve that log file. Here are some recommended pre-retrieval steps:
- Clear the Charles log using the broom button 🧹.
- Be sure, that logging is active (red recorder button 🔴 in the toolbar).
- Perform your actions or steps to reproduce an issue.
- Stop recording the logs by clicking the red button and turning it grey 🔘.
Now, we can:
- Head to File ▸ Save Session as…
- Choose a folder and pick a file name. Do not use periods in the name.
- Upload the log ending with .chls to your bug report.
That’s it! We are done with extracting Charles logs. Attach the .chls file to your bug report. Jira, for example, accepts this file format. When the report gets assigned to a developer, they are able to download and open the file up in Charles. They can see all the details that were happening when we tested our app, e.g., the contents of requests and responses. Log files allow for issue communication, debugging, root cause analysis, and the according fix to happen efficiently.
6. Tidy up
The very last step, before concluding with the Charles Web Proxy tool, is wiping the slate clean and restoring any applicable default settings.
When done with the Charles session, be sure to close the software and to revert the WiFi settings on the mobile devices to their prior state. Therefore, set the Proxy to None again in the WiFi settings.
Remove Charles Root Certificates
We also want to remove the certificate from our devices if they are our privately used desktops, smartphones and tablets and not only meant for testing.
Chromium
Windows
- Open the Run window with
Win+R, typecertmgr.mscand pressEnter. If the root certificate was added underTrusted Root Certification Authoritiesduring the root certificate installation steps, then go there and look forCharles Proxy CA. Right-click on it and clickDelete.
- Alternatively, go to Control Panel ▸ Internet Options ▸ Content ▸ Certificates ▸ Trusted Root Certification Authorities, click on Charles Proxy CA and click Remove.
macOS
- Remove the certificate via the Chrome browser Settings as depicted below:
- Alternatively, go to Spotlight Search ▸ Keychain Access ▸ Certificates, click on Charles Proxy CA and click Delete.
Firefox
Windows
- Click the navigation drawer menu in the browser’s top-right corner and select Settings. Go to Options ▸ Privacy & Security ▸ View Certificates ▸ Authorities tab. Scroll down to XK72Ltd, click Charles Proxy CA, click Delete or Distrust and then OK.
macOS
- Firefox default directory for certificates is ~/Library/Application Support/Mozilla/Certificates on macOS. Locate the Charles certificate at this path, right-click on it and click Move to Trash.
- Alternatively, perform removal via the Firefox browser Settings, as in the flow illustrated below.
Now, let’s remove root certificates from our mobile devices.
Android
On the phone, go to Trusted credential’s User tab and look for the Charles root certificate. Open the certificate and tap Uninstall.
On an emulator, the process in essentially identical.
iOS
On a physical device, navigate to Settings ▸ General ▸ Profiles & Device Management. Under Configuration Profiles, we’ll see an entry for Charles Proxy. Open it and then tap Remove Profile. Enter your passcode (if required) and confirm the removal.
Profiles & Device Management isn’t available in iOS Simulator. To remove the Charles Proxy certificates, reset the simulator by clicking the Hardware menu and then Erase All Content and Settings….
If we ever want to start logging in the future, we can jump back in. Just spin up the Charles app and add the IP address and port to our WiFi settings again. If we’ve removed the certificate, we can add it back too. Review and repeat the above described steps, if you encounter any issues with your environment.
7. Miscellaneous Issues and Questions
❓What happens if Charles root certificate is not installed?
🛠️ Solution:
When we have Charles running without having a root certificate installed, most of the sites will browse just fine. But for the hosts where we have enabled SSL Proxying (by going to Proxy ▸ SSL Proxy Settings and adding an entry), we get an error as seen in the images below.
Your connection is not private or Did Not Connect: Potential Security Issue error page, as seen on Chrome and Firefox.
❓Cannot monitor traffic on Android.
🛠️ Solution:
While proxying with most iOS apps works fine, for Android we require a special debug app version. Developers need to calibrate network settings in the manifest file to allow for network interception. They have to add a network security configuration file into the Android project, in order for us to be able to read the traffic for our app in Charles Proxy. Of course, this special debuggable build is never meant for production release to the customers. So, make a point to get a debug test app before proxying on Android devices. There is a high chance that your test app will already be configured for the Android version. iOS does not require that for traffic interception.
❓Usage of Charles with some mobile apps is limited.
🛠️ Solution:
Mobile manufacturers, like Google and Apple, are aware of existing proxying tools like Charles or Fiddler. They recognize them as legitimate tools, but they choose not to share all the information and limit usage of some apps. For example, we are not able to use the Apple Id, access the App Store, and Siri does reply but is unable to execute any commands. Those are hidden from Charles by device manufacturers.
❓Windows: No internet connection after setting manual proxy. We set the manual proxy on our phone to the computer running Charles. When we try to browse a website on the phone, we expect to see a prompt on Charles about an unauthorized device trying to connect, as per the Charles documentation. But we don’t see that prompt, and our phone appears to have no internet connection. Even after manually adding the phone’s local IP to Proxy ▸ Access Control Settings, there is still no internet access on our phone and Charles is not recording any network activity on that phone.
🛠️ Solution:
- Open Start. Type “network status” and click the matching item.
- Click Change connection properties.
- Under Network Profile, select Private (it was originally set to Public).
Charles may need to be restarted. Fiddler, however, works fine without having to change the Network Profile to Private.
❓Firefox: No internet connection after setting manual proxy. Charles is not recording network traffic on Firefox but it is working fine on Chrome and Edge.
🛠️ Solution:
👉Go to Options ▸ Settings (under Network Proxy), and make sure Use system proxy settings is selected. If we’re getting ‘Your connection is not secure’ on HTTPS sites after that, we may have to visit https://chls.pro/ssl and select ‘Trust this CA’ to identify websites to install the SSL certificate on Firefox.
Happy testing, logging and debugging!
This post only covers a fraction of everything that testers can accomplish with the Charles Web Proxy tool. There are many more useful features left for us to explore that are a separate topic on its own.
I welcome any comments and contributions to the subject. Connect with me on LinkedIn, X , GitHub, or Insta.