Enable a secure HTTPS listener

This document describes how to enable secure HTTPS listener for an API Builder service. 

Introduction

The generation of API Builder services is a simple process with the help of the API Builder CLI tool.

Some users may want to run their APP using the Secure Sockets Layer (SSL), so this document describes how to make the necessary configuration changes. Additionally, this document provides the technical requirements and an example of how to scaffold and run an API Builder service and configure SSL. 

Prerequisites

Prior to setting up a service and configure SSL, refer to:

  • API Builder Getting Started Guide - Provides detailed instructions for installing API Builder and creating an API Builder service.
  • API Builder Project - Provides detailed information about API Builder projects and services.
  • Install the API Builder Command Line Interface (CLI) globally using npm. It is a flow-node module published in npm public repositoryOnce API Builder CLI is installed, you can use it to create a new service, install the service's dependencies, and start the API Builder service.

    npm install -g @axway/api-builder
  • OpenSSL - Provides detailed information about OpenSSL.

Documentation and resources

 Useful resources on how to use the product:

Configure SSL

This document provides a step-by-step tutorial on how to run an API Builder service and configure SSL. These steps include:

  1. Scaffold and run the API Builder service.
  2. Create an SSL certificate.
  3. Configure SSL in the API Builder service.

These steps and their required prerequisites are described in the following sections.

Step 1: Scaffold and Run API Builder Service

If you already have a generated service, you can proceed to Step 2.

To scaffold and run your API Builder service, execute the following commands:

api-builder init <YOUR_APP_NAME>
cd <YOUR_APP_NAME>
npm install --no-optional
npm start

Once your service is running, point your browser to http://localhost:8080/console, for access to the API Builder user interface (UI) console.

For additional information on the API Builder UI, refer to the API Builder Getting Started Guide.

Now, stop the service by using Ctrl + C in your terminal where the service is running and go to the next step.

Step 2: Create an SSL certificate

Create one new folder on the root level of your directory.

cd <api-builder-service>
mkdir <new-folder>

Navigate to the newly created folder and create SSL certificate via OpenSSL. Please execute the following command:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -subj "/C=US/O=Axway/CN=API Builder"

NOTE: -subj "/C=US/O=Axway/CN=API Builder" is the default DN.

Due to the generation process, you will need to set PEM passphrase; for example, this is a password that must be supplied by anyone wanting to use the keys.

Once your certificate is created, you will find two new files in your <new-folder>; for example, the key.pem file that will store the private key and the cert.pem file which is the certificate.

In case you specified the PEM passphrase when generating the certificate, there is a password that must be supplied by anyone wanting to use it.

Note: Additional information is available at: Creating an HTTPs server with Node.js and NodeJS and SSL

Step 3: Configure SSL in the API Builder service

Navigate to the  ./conf/default.js file from the root of your project. Your SSL configuration goes here. The options are the same as what is used by the Node.js https.createServer() method. You will find the initial SSL configuration. For example:

// Your ssl configuration goes here. The options are the same has what is used by
// Node.js https.createServer() method
// https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener

// ssl: {
//  port: 8443
// }

Enable SSL by uncommenting the configuration. Once the configuration is uncommented, add a key and certificate, provide the paths to the files, and provide a password for the private key (configured as an OS environment variable). The following is the sample configuration:

// Your ssl configuration goes here. The options are the same has what is used by
// Node.js https.createServer() method
// https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener

ssl: {
  port: 8443,
  key: fs.readFileSync(path.join('.', 'ssl','key.pem'), 'utf8'),
  cert: fs.readFileSync(path.join('.', 'ssl','cert.pem'), 'utf8'),
  passphrase: process.env.API_BUILDER_SSL_PASSWORD
}
Then navigate to the root directory of <your-project> and run the service using the following command:

 

API_BUILDER_SSL_PASSWORD=<your-passphrase-key-password> npm start

Note: Additional information is available at API Builder Configuration.

Related Links