Secure HTTP (HTTPS) with the Local Server

This topic applies to

Applies to

SuiteCommerce Web Stores

The gulp local command starts two instances of the local server at the following URLs:

  • http://localhost:7777

  • https://localhost:7778

The instance running at port 7778 provides a secure domain using HTTPS. This enables you to test the application using secure domains. However, before using secure domains on the local server, you must perform the following:

  • Modify the distro.json.

  • Modify the root URL of the shopping-local.ssp file.

  • Generate the required SSL certificates and private keys.

  • Configure the KEYPEM and CERTPEM environment variables.

  • Install the certificates on your system.

Generate SSL Certificates and Private Keys

To access a secure domain via HTTPS when running the local server, you must use an SSL certificate and a private key. Since the local server is intended for testing and not a production environment, you can create a self-signed certificate locally and do not need to use a third-party certificate provider.

To generate an SSL Certificate and a Private Key

  1. Download and Install OpenSSL

    See Download and Install OpenSSL for more information.

  2. Generate an RSA private key.

    1. Run the following command:

      openssl genrsa -des3 -out ca.key 1024
    2. Enter and confirm a password for the certificate.

      You will use this password in the remaining procedures for creating a certificate and private key.

    This command outputs the RSA private key in a file called ca.key.

  3. Create a new SSL certificate.

    1. Run the following command:

      openssl req -new -sha256 -key ca.key -out ca.csr

      This command uses the RSA private key created in the previous step.

    2. Accept the default value for the localhost field. The other fields are not required to create the certificate used by the local server when running HTTPS.

    This command outputs the SSL certificate in a file called ca.csr.

  4. Create a self-signed certificate:

    openssl x509 -req -days 3600 -in ca.csr -out ca.crt -signkey ca.key

    If you are prompted to enter a password, use the password you entered when generating the RSA key.

  5. Create a server key:

    openssl genrsa -des3 -out server.key 1024

    This command outputs the server private key to a file called server.key.

  6. Create a certificate signing request (CSR):

    openssl req -new -sha256 -key server.key -out server.csr

    This command outputs the CSR to a file called server.csr.

  7. Remove the password from the server certificate.

    This step is optional. If you encounter problems with the password, you can remove it from the certificate.

    1. Copy the server.key file to server.key.org.

    2. Run the following command to generate a new server.key file that has no password:

      openssl rsa -in server.key.org -out server.key

      This command creates a new private key called server.key. The local server uses this file when creating a secure domain. Therefore, you should move it to a permanent location.

  8. Create a self-signed server certificate:

    openssl x509 -req -sha256 -days 3600 -in server.csr -signkey server.key -out server.crt

    This command creates a new server certificate called server.crt. The local server uses this file when creating a secure domain. Therefore, you should move it to a permanent location.

Configure the KEYPEM and CERTPEM Environment Variables

After generating a server certificate and private key, you must define environment variables that point to these files.

Using the method for setting environment variables for your operating system, create the following:

Note

You must set these environment variables before running the local server.


KEYPEM

<path_to_file>/server.key

CERTPEM

<path_to_file>/server.crt

On Windows, for example, you can set these environment variables as in the following example:

set KEYPEM=c:\OpenSSL-Win64\server.key
set CERTPEM=c:\OpenSSL-Win64\server.crt

Install the Generated Certificates

After generating the SSL and server certificates, you must enable them to work with your web browser. On Windows, you can use the Certificate Import Wizard.

To install generated certificates:

  1. Run the server.crt file you generated using OpenSSL.

  2. Click Install Certificate.

  3. Click Next.

  4. Choose Place all certificates in the following store, then click Browse.

  5. Choose Trusted Root Certification Authorities, then click OK.

  6. Click Next.

  7. Verify that your settings are correct, then click Finish.

  8. Click Yes to verify that you want to install the certificate on your system.

After installing the server certificate, you should repeat these procedures to install the ca.crt file generated in a previous step.

Modify the distro.json File

To access a secure domain on the local sever, you must ensure that the https object exists in the local object of taskConfig. After adding the https object, add an entry for the HTTPS port, certificate and key.

Your distro.json file should look similar to the following:

"tasksConfig": {
    "local": {
        "http": {
            "port": 7777
        },
        "lessSourcemap": false,
        "jsRequire": true,
        "https": {
            "port": 7778,
            "key": "KEYPEM",
            "cert": "CERTPEM"
        }
    },
    ...

Note

You must set the key and cert properties as shown above. The local server uses these values to determine the environment variables used to local the certificate and key required to use HTTPS.


Modify the Root URL of the Shopping SSP Application

To use HTTPS with the local server, you must change the value of the ROOT variable in the shopping SSP application.

To modify the root URL of the shopping SSP application:

  1. Open the index-local.ssp file.

    This file is located in <SCA_Source_Root>/Modules/suitecommerce/ShoppingApplication@x.y.z/Internals.

  2. Change the value of the ROOT variable:

    var ROOT = 'https://localhost:7778/'
    
  3. Compile and deploy the application using the following command:

    gulp deploy

    Since the above procedure changes a backend file, you must deploy the files to NetSuite. In the process of compiling the application, this command creates the shopping-local.ssp file based on the index-local.ssp file modified above.

Access the Local Server Using a Secure URL

To access the local server using the local server, you must use the URL of your secure domain.

To access the local server using a secure domain:

  1. Run the following command:

    gulp local
  2. Access the secure domain of the local server using a URL of the following form:

    https://checkout.netsuite.com/c.<account_id>/<SSP_application>/shopping-local.ssp

    For example, your URL should look similar to the following:

    https://checkout.netsuite.com/c.123456/sca-dev-montblanc/shopping-local.ssp