How to test secure (https) services from localhost

As a developer, if you want to integrate and test third party secure services with your server running on a local machine, you need to install security certificate locally. For example, if you are integrating with a payment gateway API over https, your local server should also support https. You can use reverse proxy like ngrok to setup a secure tunnel but exposing your development machine to public network is risky. In this article, I will explain how to create and install SSL Certificates on local Ubuntu system so that you can test such integrations.

Using certificates from real certificate authorities (CAs) for development can be dangerous or impossible (for hosts like localhost or 127.0.0.1). Self-signed certificates can cause trust errors. mkcert is a simple tool for generating locally-trusted development certificates. It requires no configuration.

mkcert automatically creates and installs local CA in the system root store and generates locally-trusted certificate.

Pre-requisites

1. Ubuntu Machine
2. Web Server (Apache2/Nginx)
3. certutil package

Install certutil

The Certificate Database tool or certutil is a command-line utility that can create/modify certificate and their key databases. It can be used to list, generate, modify, or delete certificates. It can be also used to create or change password and generate new public/private key pairs. It can display contents of key database and can also deletes key pairs within key database.

On our Ubuntu server, we can install it by running the following command:

$ sudo apt-get install -y libnss3-tools

Download and setup mkcert tool

Depending on our OS platform and requirement we need to download the binary file for mkcert tool.

Here is how to do it for Ubuntu:

$ mkdir ~/mkcert && \
  cd ~/mkcert && \
  wget https://github.com/FiloSottile/mkcert/releases/download/v1.1.2/mkcert-v1.1.2-linux-amd64 && \
  mv mkcert-v1.1.2-linux-amd64 mkcert && \
  chmod +x mkcert

Generate certificate

We can generate our local CA to generate our certificates with these commands:

# mkcert -install

$ ./mkcert localhost

To check is the certificate is generated:

$ ls -l

-rw-------   1 satish satish    1708 Sep 20 18:10 localhost-key.pem
-rw-r--r--   1 satish satish    1484 Sep 20 18:10 localhost.pem
-rwxr-xr-x   1 satish satish 4455604 Aug 25 22:30 mkcert*

Enable certificate on localhost Web Server

Our next step is to install our web server and enable SSL to use this locally trusted development certificate.

I installed nginx and enabled SSL using following commands:

# apt install -y nginx
# systemctl start nginx

Edit the default file located at /etc/nginx/sites-available/default and add our locally generated SSL certificate and key details:

server {
    listen       80;
    server_name  localhost;
    return       301 https://$host$request_uri;
}
server {
    listen       443 ssl;
    server_name  localhost;
# SSL
    ssl_certificate       /<PATH TO Mkcert DIR>/localhost.pem;
    ssl_certificate_key   /<PATH TO Mkcert DIR>/localhost-key.pem;
location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    }
}

Now you can restart the nginx server to make these changes effective:

# systemctl restart nginx

Test

Test everything is working fine by browsing https://localhost to confirm it is working:

We are now ready to use our local server to test integration with external https enabled services.

Warning: mkcert is meant for development purposes alone not recommended for production.

What other methods have you used to test https service integrations from your local machine?

At 47Billion, we specialize in helping companies build awesome products. If you are looking for a an experienced team to build your complete solution, please contact us at info@47billion.com.