Skip to content

Certificate Installation

Jump to bottom
John Harker edited this page Dec 18, 2019 · 2 revisions

Why is certificate installation required?

As the Postwoman application is a progressive web app, it must be served over HTTPS in order to be accessed. This means that to allow access to the proxy via AJAX, the proxy must also be served over HTTPS.

Naturally, if the proxy is set up locally, this can be an issue - as most people do not want to spend time setting up a self-signed certificate.

In order to overcome this issue, the Postwoman Proxy application generates a self-signed certificate and key on startup. The generated certificate has a Subject Alternative Name (SAN) exclusively for 127.0.0.1 allowing it to act as a trusted root solely for that local IP address.

Once the certificate is marked as trusted, the proxy can operate over HTTPS on your local device and therefore be used by Postwoman.

How do I install the certificate?

macOS

  1. When you open the Postwoman Proxy application for the first time, it will generate a certificate specifically for your machine. You will see the following dialog and a Finder window showing the directory with the generated Certificate: Postwoman Installation Process Prompt

  2. Double click the file named cert.pem. It will open in Keychain Access. Keychain Access Certificate Installation Prompt

  3. Click 'Add' and then search for 'The Postwoman Project' in Keychain Access. Keychain Access Search: 'The Postwoman Project'

  4. Double-click the certificate, and in the dialog that opens, expand the 'Trust' section by clicking the arrow to the left of the 'Trust' label. (See the red circle.) Keychain Access: Expand Trust Section

  5. Change the 'Secure Sockets Layer (SSL)' option to 'Always Trust'. Then close the window. Upon closing the window, you will be prompted to enter your password - and then the new settings will be saved.

  6. You can now close the opened Finder window and press 'OK' in the Postwoman Proxy dialog. You should now test the installation was successful by visiting https://127.0.0.1:9159 in the browser. Browser

  7. You have now (hopefully) installed the Postwoman certificate successfully... Happy debugging!

Windows

  1. When you open the Postwoman Proxy application for the first time, it will generate a certificate specifically for your machine. You will see the following dialog and a window showing the generated certificate:
    Certificate Installation Prompt

  2. Click 'Install Certificate...', the Certificate Import Wizard will open. Ensure that Local Machine is selected, and then click Next.
    Certificate Import Wizard

  3. Select 'Place all certificates in the following store' and then click 'Browse...'
    Certificate Store Selection: Browse

  4. Select the 'Trusted Root Certification Authorities' store, and click OK. Trusted Root Certification Authorities

  5. Click 'Next' and then click 'Finish'.
    Click 'Next' and then click 'Finish'

  6. You can now close any confirmation dialogs and the certificate window and click 'OK' on the Postwoman dialog. You should now test the installation was successful by visiting https://127.0.0.1:9159 in the browser. Browser

  7. You have now (hopefully) installed the Postwoman certificate successfully... Happy debugging!

Clone this wiki locally