Configuring SSL for a Node.js Application in a Windows Azure Web Role

Secure Socket Layer (SSL) encryption is the most commonly used method of securing data sent across the internet. This common task discusses how to specify an HTTPS endpoint for a Node.js application hosted as a Windows Azure Cloud Service in a web role and how to upload an SSL certificate to secure your application.

This task includes the following steps:

• Step 1: Create a Node.js service and publish the service to the cloud
• Step 2: Get an SSL certificate
• Step 3: Import the SSL certificate
• Step 4: Modify the Service Definition and Configuration Files
• Step 5: Connect to the Role Instance by Using HTTPS

Step 1: Create a Node.js service and publish the service to the cloud

When a Node.js application is deployed to a Windows Azure web role, the server certificate and SSL connection are managed by Internet Information Services (IIS), so that the Node.js service can be written as if it were an http service. You can create a simple Node.js 'hello world' service using the Windows Azure PowerShell using these steps:

1. From the Start Menu or Start Screen, search for Windows Azure PowerShell. Finally, right-click Windows Azure PowerShell and select Run As Administrator.

   

   Something missing?

   To successfully complete this section, you must have a working installation of Node.js and the Windows Azure SDK for Node.js for your platform.

   • Install the Windows Azure SDK for Node.js: Windows installer | Mac installer | Linux download
   • If you are using Mac or Linux, install Node.js from http://nodejs.org. The Windows installer already includes Node.js.

   
   

2. Create a new service project using the New-AzureServiceProject cmdlet.

   

3. Add a web role to your service using Add-AzureNodeWebRole cmdlet:

   

4. Publish your service to the cloud using Publish-AzureServiceProject cmdlet:

   

   Note

   If you have not previously imported publish settings for your Windows Azure subscription, you will receive an error when trying to publish. For information on downloading and importing the publish settings for your subscription, see How to Use the Windows Azure PowerShell for Node.js

The Created Web Site URL value returned by the Publish-AzureServiceProject cmdlet contains the fully qualified domain name for your hosted application. You will need to obtain an SSL certificate for this specific fully qualified domain name and deploy it to Windows Azure.

Step 2: Get an SSL Certificate

To configure SSL for an application, you first need to get an SSL certificate that has been signed by a Certificate Authority (CA), a trusted third-party who issues certificates for this purpose. If you do not already have one, you will need to obtain one from a company that sells SSL certificates.

The certificate must meet the following requirements for SSL certificates in Windows Azure:

• The certificate must contain a private key.
• The certificate must be created for key exchange (.pfx file).
• The certificate's subject name must match the domain used to access the cloud service. You cannot acquire an SSL certificate for the cloudapp.net domain, so the certificate's subject name must match the custom domain name used to access your application. For example, mysecuresite.cloudapp.net.
• The certificate must use a minimum of 2048-bit encryption.

Step 3: Import the SSL certificate

Once you have a certificate, install it into the certificate store on your development machine. This certificate will be retrieved and uploaded to Windows Azure as part of your application deployment package based on configuration changes you make in a subsequent step.

To import the SSL certificate, perform the following steps:

1. Using Windows Explorer, navigate to the directory where the .pfx file containing the certificate is located and then double-click on the certificate. This will display the Certificate Import Wizard.

   

2. In the Store Location section, select Current User and then click Next. This will install the certificate into the certificate store for your user account.

3. Continue through the wizard, accepting the defaults, until you arrive at the Private key protection screen. Here, you must enter the password (if any) for the certificate. You must also select Mark this key as exportable. Finally, click Next.

   

4. Continue through the wizard, accepting the defaults, until the certificate has successfully been installed.

Now you must modify your service definition to reference the certificate you have installed.

Step 4: Modify the Service Definition and Configuration Files

Your application must be configured to reference the certificate, and an HTTPS endpoint must be added. As a result, the service definition and service configuration files need to be updated.

1. In the service directory, open the service definition file (ServiceDefinition.csdef), add a Certificates section within the WebRole section, and include the following information about the certificate:

   <WebRole name="WebRole1" vmsize="ExtraSmall">
   ...
       <Certificates>
           <Certificate name="SampleCertificate" 
               storeLocation="LocalMachine" storeName="My" />
       </Certificates>
   ...
   </WebRole>

   The Certificates section defines the name of the certificate, its location, and the name of the store where it is located. Since we installed the certificate to the user certificate store, a value of "My" is used. Other certificate store locations can also be used. See How to Associate a Certificate with a Service for more information.

2. In your service definition file, update the http InputEndpoint element within the Endpoints section to enable HTTPS:

   <WebRole name="WebRole1" vmsize="Small">
   ...
       <Endpoints>
           <InputEndpoint name="Endpoint1" protocol="https" 
               port="443" certificate="SampleCertificate" />
       </Endpoints>
   ...
   </WebRole>

   All of the required changes to the service definition file have been completed, but you still need to add the certificate information to the service configuration file.

3. In your service configuration files (ServiceConfiguration.Cloud.cscfg and ServiceConfiguration.Local.cscfg), add the certificate to the empty Certificates section within the Role section, replacing the sample thumbprint value below with that of your certificate:

   <Role name="WebRole1">
   ...
       <Certificates>
           <Certificate name="SampleCertificate" 
               thumbprint="9427befa18ec6865a9ebdc79d4c38de50e6316ff" 
               thumbprintAlgorithm="sha1" />
       </Certificates>
   ...
   </Role>

4. Refresh your service configuration in the cloud by publishing your service again. At the Windows Azure PowerShell prompt, type Publish-AzureServiceProject from the service directory.

   As part of the publish process, the referenced certificate will be copied from the local certificate store and included in the deployment package.

Step 5: Connect to the Role Instance by Using HTTPS

Now that your deployment is up and running in Windows Azure, you can connect to it using HTTPS.

1. In the Management Portal, select your cloud service, then click Dashboard.

2. Scroll down and click the link displayed as the Site URL:

   

   Note

   If the Site URL displayed in the portal does not specify HTTPS, then you must manually enter the URL in the browser using HTTPS instead of HTTP.

3. A new browser will open and display your web site.

   Your browser will display a lock icon to indicate that it is using an HTTPS connection. This also indicates that your application has been configured correctly for SSL.

   

Additional Resources

How to Associate a Certificate with a Service

Configuring SSL for a Node.js Application in a Windows Azure Worker Role

How to Configure an SSL Certificate on an HTTPS Endpoint