Configuring Charles Web Debugger

Skip to end of metadata
Go to start of metadata

 

Certain problems that involve client side calls can be much easier to debug with a capture of the HTTP traffic going back and forth between your site, the user's browser and Gigya. When you report such problems to the Gigya support team you may be asked to provide a request/response capture of the reported problem. Charles is a Web Debugging Proxy that logs all HTTP(S) traffic between your computer and the Internet, allowing you to inspect all HTTP(S) traffic, set breakpoints, and modify incoming or outgoing data. Charles can debug traffic from virtually any application, including Internet Explorer, Mozilla Firefox, Opera, and others.

Note: Before you take a "Charles capture" to be submitted to Gigya it must be configured to capture HTTPS traffic as explained below.

 

Installing Charles

Charles runs on Windows (32 and 64 bit), Mac OS X and Linux (Debian flavors). It may be downloaded from http://www.charlesproxy.com/download/.

Working with Charles

When Charles is running, you can inspect the data transferred to and from the Gigya server by simply clicking on one of the sessions in the Sequence tab in the upper-pane. Session data will appear in the lower-pane.

 

Saving the Capture to a File

In case it is required, you can save the sessions to a file by clicking on File->Save, provide a file name and save  (in chls file format).

 

Configuring Charles to Capture HTTPS Traffic

Charles includes the ability to capture and decrypt HTTPS traffic. In order to do this, it generates its own SSL Certificate and uses this certificate to encrypt/decrypt HTTPS requests/responses. When using Charles's certificate, you will see a warning in your browser because the Charles CA Certificate is not in your list of trusted root certificates. You can choose to trust each certificate as you encounter them, or to avoid warnings, you can choose to trust the Charles CA Certificate.

 

Note: It is recommended that you make this configuration change on Test machines only.

Enabling SSL Proxying

  1. In Charles, click Proxy -> Proxy Settings.
  2. In the Proxy Settings dialog, select the SSL tab, check the "Enable SSL proxying" option and click OK.

Configuring OS X to Trust the Charles Root Certificate

  1. Download and unzip the Charles CA Certificate bundle. The bundle contains the Charles CA Certificate file.
  2. Run the Keychain Access utility from the Applications/Utilities folder. This tool enables you to manage your certificates.
  3. Choose the "login" keychain, then from the File menu, choose Import. Choose the .crt file you downloaded above and ensure that the "login" keychain is selected in the dropdown menu.
  4. Once the import is complete, the Charles CA SSL Certificate will be trusted for your login account.
  5. To trust the Charles Proxy SSL Proxying certificate for all users on the machine, drag-and-drop it from your login keychain to the System keychain.
  6. Quit and re-open Safari for the changes to take effect.

 

Registering the Charles Root Certificate in the System Certificate Store - Windows

This configuration is all that is required to capture traffic from Internet Explorer and Chrome:

  1. In Charles, click Help -> Install Charles CA SSL Certificate. A window will open warning you that the CA Root certificate is not trusted.
  2. Click Install Certificate to launch the Certificate Import Wizard. The certificate must be imported into the Trusted Root Certification Authorities store.
  3. Confirm the certificate thumbprint. It should read: 189B6E28 D1635F3A 8325E1E0 02180DBA 2C02C241
  4. Complete the wizard, and the CA SSL certificate is now installed. Restart Internet Explorer for the changes to take effect.

 

Configuring Firefox to Trust the Charles Root Certificate

The first time Charles is run, it will prompt you to install the Charles Add-on for Mozilla. If the add-on is not automatically installed, you can manually activate the Mozilla Firefox Proxy from the Proxy menu. Click here to download and install the add-on manually.

  1. After installing the Charles Add-on for Mozilla, go to Tools -> Charles -> Install Charles CA SSL Certificate.
  2. In the certificate import dialog, check the "Trust this CA to identify websites" option and complete the import.

 

Additional Information

If you have any further questions about Charles, please visit http://www.charlesproxy.com/documentation/using-charles/.