Configuring SSL

Overview

This document details how to configure SSL endpoints in Neuron ESB, which can then be used in any number of scenarios.

Assumptions

This guide assumes that you have a basic understanding of the Neuron ESB Explorer, client connectors and service connectors. If you are not familiar with these aspects of the Neuron ESB platform, please review the Neuron ESB Fundamentals guide before proceeding.

When using certificates for SSL, it is recommended that you use a certificate from a Certificate Authority. For development purposes you can use a self-signed certificate. This guide walks you thought using both.

Configuring a Service Connector

Configuring a service connector to use SSL is relatively simple. When using SSL, you do not need to configure a certificate in the service connector, you just need to set the security model to one of the “Transport” options. This section will guide you through creating a service connector and configuring it to use SSL.

Note – If the service you are connecting to is using a certificate from a trusted authority, that certificate will automatically be downloaded and used when making the call. However, if the certificate is not from a trusted authority, or if it’s a self-signed certificate, then you will need to manually import the certificate into the local computer’s certificate store. Also, if you are testing the service connector interactively with the business process or workflow testers, then the SSL certificate will also need to import the certificate into the current user’s certificate store. See the section Import the SSL Certificate for more information.

Create a Service Connector

1. Create a new service endpoint named SSLServiceConnector

2. Click on the Security tab and change the Security Model to Transport:None. If your scenarios require additional security on top of SSL, select the appropriate security model from the list, and configure the service endpoint according to the selected model.

3. Click on the Service Connector tab and enter the following values
   1. Enable the Service Connector
   2. URL: https://[URL from Certificate] (see the below for more details)
   3. If you are using the service connector from a process, uncheck the Subscribe checkbox. If using it in a messaging scenario, leave it checked and select a Subscriber from the dropdown list.

The “host” portion of the Service Connector URL must match one of the following from the certificate:

• Subject – For example, this will be displayed as CN = www.fabrikam.com.
• Subject Alternative Name – There may be several alternative names. For example:
  • DNS Name=www.fabrikam.com
  • DNS Name=fabrikam.com

In the above example, your URL must start with either www.fabrikam.com or fabrikam.com.

4. Click the Apply button.

Configuring a Client Connector

Configuring a client connector to use SSL requires a few more steps than a service connector. Besides configuring the client connector for a “Transport” security model, you will need to import the SSL certificate into the local machine’s certificate store and register it with the port the client connector is listening on. This section will guide you through creating a client connector and configuring it to use SSL.

Import and Register the SSL Certificate

To use SSL with a client connector, you will have to bind an SSL certificate to the client connector’s port. The certificate can either be issue by a certificate authority or self-signed. For information on creating a self-signed certificate, see the section Create a Self-Signed Certificate. Once you’ve obtained your certificate, follow the steps in these sections:

1. Import the SSL Certificate
2. Register the Certificate for the Client Connector’s Port

These steps can be completed before or after you create the client connector.

Create a Client Connector

1. Create a new service endpoint named SSLClientConnector

2. Click on the Security tab and change the Security Model to Transport:None. If your scenarios require additional security on top of SSL, select the appropriate security model from the list, and configure the service endpoint according to the selected model.

3. Click on the Client Connector tab and enter the following values
   1. Enable the Service Connector
   2. URL: https://[URL FOR THIS SERVICE ENDPOINT] (example: https://localhost:9099/esb)
   3. If the client connector is executing a process, select the Business Process radio button and edit the process list. If using it in a messaging scenario, select the Messaging radio button and select a publisher and topic from the dropdown lists.

4. Click the Apply button.

Create a Self-Signed Certificate

You can create your own SSL certificate for development and testing purposes. For production we always recommend getting a certificate from a Certificate Authority. There are many ways to create a self-siged certificate. You can download a tool from OpenSSL, or you can use your Windows OS to do it for you as demonstrated below.

Windows PowerShell

Windows PowerShell contains a command you can use to easily create an SSL certificate – New-SelfSignedCertificate:

1. Open PowerShell
2. Enter the following command

New-SelfSignedCertificate -FriendlyName "Neuron SSL Test Cert" -DnsName "www.fabrikam.com", "fabrikam.com" -CertStoreLocation "cert:\LocalMachine\My"

3. Copy the thumbprint value – you will need it later when registering the certificate with the client connector’s port.

You now have an SSL certificate with these details:

• Friendly name – Neuron SSL Test Cert
• Subject – CN = www.fabrikam.com
• Subject Alternative Name:
  • DNS Name=www.fabrikam.com
  • DNS Name=fabrikam.com
• Store – local machine’s personal store

The public key of this certificate can be used by clients attempting to access the server with the base URLs of www.fabrikam.com and fabrikam.com. When creating your own self-signed certificate, replace the fabrikam URL(s) with your own.

This certificate has only been saved to the local machine’s personal store. Since this is a self-signed certificate it won’t be trusted by Windows. You will need to export the certificate from the personal store and add it to the Trusted Root Certification Authorities store. Follow the steps in the sections Exporting Self-Signed Certificates and Import the SSL Certificate.

IIS Manager

Creating a self-signed certificate in IIS Manager is very simple.

1. Open IIS Manager

2. Double Click Server Certificates

3. Click the Create Self Signed Certificate link in the right pane. Enter a friendly name like “IIS Generated Test Cert” for the certificate and click OK.

That’s it! You now have an SSL certificate with these details:

• Friendly name – IIS Generated Test Cert
• Subject – CN = NeuronDev
• Subject Alternative Name – None
• Store – Local Computer’s Personal store AND Local Computer’s Trusted Root Certification Authorities store

One drawback of using IIS to generate a test certificate instead of the Windows PowerShell command is that the IIS-generated cert is only intended for the machine it’s created on. You can use this cert to enable SSL on an IIS-hosted Web site or on Neuron ESB Client Connectors that are hosted by a Neuron ESBinstance on the same machine. You cannot set additional Subject Alternative Names for this cert.

Exporting Self-Signed Certificates

If you created a self-signed certificate using IIS, it’s already stored in both the Local Computer’s Personal and Trusted Root Certification Authorities stores and nothing more needs to be done. If you created a self-signed certificate using the PowerShell command it’s only stored in the Local Computer’s Personal store and you will have to export the certificate so you can add it to Trusted Root Certification Authorities store. If you’ve obtained a certificate from a Certificate Authority, you already have the certificate file that can be imported and can skip this section.

1. Open the local computer certificate manager by typing “Cert” in Windows Cortana search bar and select “Manage computer certificates”.

2. Expand Personal and select Certificates. You will see any self-signed certificates you created in this store.

3. Select the certificate you need to export, then right-click, select All Tasks->Export…

4. Follow the wizard steps to export the certificate, making sure you select the option to export the private key on the Export Private Key page and select the default values on the Export File Format page:

You now have a .pfx file you can import into other stores on this computer.

Import the SSL Certificate

The certificate you use for SSL can either be a self-signed certificate or one issued by a certificate authority. Regardless of how the certificate is obtained, it needs to be imported into the Local Computer’s Personal certificate store. If the certificate is self-signed or is generated by a Certificate Authority that Windows does not trust, then it will also need to be imported into the Local Computer’s Trusted Root Certification Authority store. Finally, if you will be testing either a client connector or a service connector interactively, you will also need to import the certificate into the same store(s) using the Current User Certificate Manager. An interactive test would be one where the application is running under the currently logged-in Windows credentials. For example, the Neuron ESB Process Tester could be used to test a service connector via the Service Endpoint process step. Testing in this manner would require any SSL certificates to be installed in the Current User’s store. Other examples include a Visual Studio project, SoapUI or Postman.

If you haven’t already done so, save the certificate file to the local file system.

1. Open the local computer certificate manager by typing “Cert” in Windows Cortana search bar and select “Manage computer certificates”.

2. Expand Personal and select Certificates. Select the Personal folder
3. Right click the Personal folder and select All Tasks -> Import

4. Import your certificate using the wizard
5. If your certificate is not signed by a trusted certificate authority (i.e. it’s a self-signed certificate), right-click the Trusted Root Certification Authorities and repeat steps 5 and 6

If you are testing a client connector or service connector interactively, repeat these steps but select “Manage user certificates” in step one:

Register the Certificate for the Client Connector’s Port

Once the certificate has been added to the appropriate certificate stores, you need to add a new SSL certificate binding for the port the client connector listens to. This can be done in two ways – with IIS Manager or the Network Shell command-line utility.

IIS Manager

If the Web Server (IIS) role has been installed on the Neuron ESB Server, you can use IIS Manager to register the certificate. This method has a few caveats:

• You will have to create a site in IIS with the same host that the Neuron ESB Client Connector is configured for
• The Neuron ESB service account will need to be configured as Local System

The benefits of this method is that registering the certificate is very simple and that you can host services in both IIS and Neuron ESB. For example, IIS can host a service at https://[servername that matches self-signed cert created by IIS]/myservice and a Neuron ESB Client Connector can have a Client access url of https://[servername that matches self-signed cert created by IIS]/esb, and as far as the client is concerned they would be accessing the same host.

To register a certificate in IIS:

1. Open IIS Manager and select the site you want to register the certificate with

2. Click Bindings in the right-hand navigation under Actions

3. Click the Add button. At a minimum, set the following values in the Add Site Binding dialog:
   1. Type – Https
   2. Port – Port number to use for SSL (default is 443)
   3. SSL Certificate – Select either your self-signed certificate or a certificate issued by a Certificate Authority that was previously imported to the certificate store(s)

For more details on adding a site binding, see Add or Edit Site Binding Dialog Box

4. Click OK

5. Click Close.

Network Shell

If you don’t have the Web Server (IIS) role installed on the Neuron ESB Server, or if you don’t want to “share” host names between IIS and Neuron ESB, you can still register the certificate using the Network Shell command-line utility. For a complete list of options when using the netsh add sslcert command, see:

https://docs.microsoft.com/en-us/windows-server/networking/technologies/netsh/netsh-http#add-sslcert

To register a certificate using netsh:

1. The netsh command requires the thumbprint of the certificate you want to register. Open the local computer certificate manager by typing “Cert” in Windows Cortana search bar and select “Manage computer certificates”.

2. Expand Personal and select Certificates in the navigation and double-click the certificate you want to register. Click the Details tab, then select the Thumbprint field:

3. Copy the thumbprint value
4. Open a command prompt as an Administrator
5. Enter the following command, replacing these parameters:
   1. ipport – The IP address and port this certificate should be bound to. Using 0.0.0.0 will bind any IP address with the specified port number
   2. certhash – The thumbprint value from step 3, with no spaces
   3. appid – A new GUID in registry format. These can easily be created in Visual Studio.

netsh http add sslcert ipport=0.0.0.0:6900 certhash=4ba86878e789e50f21040ef650e4582e274022e6 appid={37483F66-1570-4EEE-8816-9144650F9BFD} certstore=My

6. To verify the certificate was properly added, use this command, matching the ipport value with what you used in the previous command:

netsh http show sslcert ipport=0.0.0.0:6900