This document details how to configure SSL endpoints in Neuron ESB, which can then be used in any number of scenarios.
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.
This guide also assumes that you are using pre-existing certificates that are already implemented on your system. If you need to create a certificate, information on how to do so can be found in Appendix A of this document.
Creating Certificate Credentials
Prior to using a certificate in conjunction with a client or service connector, you must first create a certificate credential inside the Neuron ESB Explorer.
Credentials are a user’s authentication information created and managed in the Neuron Explorer by navigating to Security -> Credentials.
From here just follow the following steps to create a certificate credential:
- Click New to open the Credentials properties window.
- In the Name textbox enter an appropriate name for the Credential you are creating.
- From the Type drop down list, select “Certificate”
- Click the ellipse next to the Locations textbox.
- Select the type of certificate that you wish to use
- Machine Certificate
- Personal Certificate
- Select the certificate store where your certificate is stored.
- Select the Find Type that you wish to use.
- Select the Certificate that you wish to use from the resulting list.
- Click the Ok button to apply the certificate to the Credential.
- Click the Apply button.
Configuring a Service Connector
Using certificates with a service connector is relatively simple. This section will guide you through creating a service connector, configuring it for standard SSL as well as configuring the service connector to use the certificate credential that you created previously.
Configuring a Service Connector for Standard SSL
When using standard SSL, you do not need to configure the certificate in the service connector. To implement standard SSL on a service connector, follow these steps:
- Create a new service endpoint named SSLServiceConnector
- Click on the Security tab and change the Security Model to Transport:None
- Click on the Service Connector tab and enter the following values
- Enable the Service Connector
- URL: https://[NAME THAT MATCHES SUBJECT NAME OF IIS7 ISSUED CERTIFICATE]
Configuring a Service Connector to use Certificate Credentials
For service connectors interacting with external services that implement a higher level of security than standard SSL, you need to configure the service connector to use the certificate credential that you created previously. In order to do this, follow these steps:
- Create a new service endpoint named CertificateServiceConnector
- Click on the security tab and select the security model that matches that of the service being called. In this example we are going to be using Transport:Certificate.
- Click on the service connector tab and enter the following values
- Enable the service connector
- URL: https://[URL FOR EXTERNAL SERVICE]
- Select the Certificate Credential you created from the Client Credentials dropdown list.
Configuring a Client Connector
As client connectors are services that Neuron ESB hosts for you to receive and send data to external parties, it is sometimes necessary to allow a client connector to accept more than one credential. Because of this you need to create an additional security entity, called an Access Control List, in order to use credentials with a client connector.
Creating an Access Control List
Let us first create an Access Control List which will use our certificate credential. To do so, follow these steps:
- Navigate to Security -> Access Control Lists
- Click New to open the Access Control Lists properties window.
- In the Name textbox enter an appropriate name for the Access Control List you are creating.
- From the Type drop down list, select “Certificate”
- Check the Certificate Credentials that you would like to include in the Access Control List
- Apply your changes
Configuring a Client Connector to use Certificate Credentials
With your access control list (ACL) created, we can now use it to configure the client connector to accept the certificate credentials that the ACL points to. To do this, follow these steps:
- Create a new service endpoint named CertificateClientConnector
- Click on the security tab and select the security model appropriate for your client connector. In this example we are going to be using Message:Certificate.
- Click on the client connector tab and enter the following values
- Enable the client connector
- URL: https://[URL FOR THIS SERVICE ENDPOINT] (example: https://localhost: 9099)
- Select the Access Control List that you created from the Access Control List dropdown list.
Creating a Certificate
In this section we will look at two different ways in which to create a certificate.
- Create a certificate explicitly with the PowerShell New-SelfSignedCertificate cmdlet like a developer might do for a custom service running on a non-standard port.
- Create a self signed cert issued by IIS7. This cert is closer to what you would use in production.
If you are only interested in using the same certificate used by IIS then you can skip to the section entitled Configure the Client Connector’s Certificate in Neuron and you may substitute the values from those instructions with values appropriate to your existing certificate.
The following steps assumes an environment running a Windows 7 or higher, or 2008 server or higher, operating system and assumes Neuron is running on the local machine as Local System.
- Open PowerShell
- Enter the following command
New-SelfSignedCertificate -Type Custom -Subject "CN=localhost" -CertStoreLocation "cert:\LocalMachine\My"
- Copy the thumbprint value
- Hold down the windows key and press R
- Type MMC to launch the MMC snap in
- Press Control-M to bring up the Add or Remove Snap-ins dialog
- Select Certificates from the left-hand list and click Add
- Select My User Account on the Certificates snap in dialog
- Click Finish
- Repeat step 7 selecting Computer account on the Certificates snap in dialog this time.
- Select Local Computer on the Select Computer dialog
- Click Finish
- Click OK to close the Add or Remove Snap-ins dialog
- Expand the Current User snap-in from the left panel of the MMC
- Select the Personal folder
- Open the Certificates folder
- Right click the localhost certificate, select All Tasks -> Export
- Follow the wizard to export the certificate, ensuring that you elect to export the private key
- Delete the localhost certificate
- Expand the Local Computer snap-in from the left panel of the MMC
- Right click the Personal folder and select All Tasks -> Import
- Import the .pfx file that you created in step 18
- Right click the Trusted Root Certification Authorities folder and repeat step 22
- Open a command prompt as an administrator
- Enter the following command using the thumbprint value from step 3
netsh http add sslcert ipport=0.0.0.0:6900 certhash=[The Value of your certificates Thumbprint without spaces] appid=[A Guid in Registry format] certstore=MY
That was a lot of steps, but what exactly did we just do?
First, we used PowerShell to create a self-signed certificate. Then we used MMC to export that certificate along with its private key, so we could use it in the local machine’s store. Then we imported that certificate into the Local Machines Personal folder and its Trusted Root Certification Authorities folder. Finally, we registered the certificate for port 6900.
Next, we will configure IIS7 to use a self-signed cert. Thankfully, this is much easier. We are doing this because we are going to host our custom service in IIS.
If you already have configured a certificate for IIS you know works then you can skip these steps.
- Hold the windows key and press R
- Type inetmgr to launch the IIS Manager
- Double Click Server Certificates in the main pane
- Click the Create Self Signed Certificate link in the right pane
- Follow the wizard to create the certificate
- Expand your computer in the left pane -> Expand Sites -> select your site
- Select Bindings from the Action menu in the right pane
- Add a binding for https and select the cert you created in the previous steps. If you named your certificate local host, make sure that you select the correct localhost from the drop down by using view.
That’s obviously much easier!
The good news is you can also use the certificate you just created in Neuron as well. So if you want to skip all of the steps we did when using PowerShell you can. The only caveat is when using this technique Neuron will need to be running as Local System and you will need to use the Default Web Site’s SSL port.
The upside is you can run Neuron alongside IIS and clients will not see a difference. For example you host your service at https://[servername that matches self-signed cert created by IIS]/myservice and your Neuron 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.