Using HTTPS Connections with the Sage 300 Connector

Summary

The Sage 300 Connector tool is able to communicate with the Sage 300 server over HTTP and HTTPS. HTTP communication is enabled by default.

This article describes how to configure both the Sage 300 and BPA Platform servers to use HTTPS.

Procedure

Prerequisites

A basic knowledge of the following is required:

• PowerShell commands
• MS-DOS commands
• How to restart server services
• Certificates — Especially their use in the Microsoft Management Console (MMC)

Step 1: Import and Configure the Certificate in the Sage 300 Server

The Sage 300 server that is hosting the Sage 300 Connector Agent requires a certificte installed with the following features:

• Includes the fully qualified domain name (FQDN)
• Includes the intended purpose of Client Authentication
• Installed to the following stores:
  • Personal\Certificates
  • Trusted Root Certification Authorities\Certificates

If required, for testing purposes, you can use a PowerShell script to create a “self-signed” certificate — see https://docs.microsoft.com/en-us/powershell/module/pkiclient/new-selfsignedcertificate?view=win10-ps. However, it is recommended that certificate creation, and the subsequent import into the certificate store, is performed by the server or domain administrator responsible for the Sage 300 server.

To import the certificate and its .PFX file (together with its password), do the following:

1. From the Sage 300 server, open a command prompt window as the Administrator.
2. In the command window, go to the folder containing the certificate and .PFX file.
3. Enter the following command:

   certutil -p PFXPassword -importPFX ComputerName.pfx

   where:

   • PFXPassword is the password for the .PFX file
   • ComputerName is the Sage 300 server’s hostname

   If the returned response is successful, continue with this procedure. If not, check and re-run the command.

The certificate should now be in the Personal\Certificates and Trusted Root Certification Authorities\Certificates stores in the Sage 300 server. You can check this using an MMC snap-in.

Step 2: Reserve a URL for the Agent in the Sage 300 Server

1. From the Sage 300 server, open a command prompt window as the Administrator.
2. Enter the following command:

   netsh http add urlacl url=https://+:port_number/ user=EVERYONE

   where port_number is the TCP port used to communicate with the Event Agent (default of 4207)

   If the returned response is “URL reservation successfully added“, continue with this procedure. If not, check and re-run the command.

   For more information about using the add urlacl command, go to https://msdn.microsoft.com/en-us/library/windows/desktop/cc307223(v=vs.85).aspx

Step 3: Configure the Port for the SSL Certificate for the Sage 300 Server

1. From the Sage 300 server, open the Microsoft Management Console (type MMC in Start > Run).
   
2. If the Certificates snap-in for the local computer has not been added previously, do the following:
   1. Go to File > Add/Remove Snap-in.
   2. From the Available snap-ins panel, double-click Certificates.
   3. Select Computer account, then click Next.
   4. Select Local computer, then click Finish.
   5. Click OK.
3. Expand Certificates (Local Computer) > Third-Party Root Certification Authorities > Certificates.
   
4. From the middle panel, highlight the FQDN certificate uploaded in step 1, and scroll across until you can see the Intended Purposes column.
5. Ensure Client Authentication is part of the Intended Purposes.

   If it isn’t, do the following:

   1. Right-click on the certificate and select Properties.
   2. Select Enable only the following purposes.
   3. Select Client Authentication.
   4. Click OK.
6. Double-click the certificate.
7. Go to the Details tab.
8. Highlight the Thumbprint field.

   If you cannot see this field, change Show to be <All>.

   

9. Copy the Thumbprint text into a text editor such as Notepad. Remove all the spaces from the text.

   Note that in some instances, there may be a hidden character at the beginning of the Thumbprint string; this needs removing as well.

10. Open a command prompt as the Administrator.
11. Enter the following command:

    netsh http add sslcert ipport=0.0.0.0:port_number certhash=THUMBPRINT appid='{A86AD080-2EC6-44FB-82E4-BB1E409AB93C}'

    where:

    • port_number is the TCP port used to communicate with the Event Agent (default of 4207)
    • THUMBPRINT is the Thumbprint text with the spaces removed

    If the returned response is “SSL Certificate successfully added“, continue with this procedure.

    If the returned response is “SSL Certificate add failed, Error: 1312 A specified logon session does not exist. It may already have been terminated.” check the certificate has not been removed from Personal\Certificates in the MMC.

Step 4: Export the Certificate from the Sage 300 Server

If you don’t have a .CER file for the FQDN certificate, do the following, else skip to step 5:

1. Still in the Microsoft Management Console (MMC), right-click the FQDN certificate.
2. Select All Tasks > Export.
3. Follow the wizard, leaving all options as default, and save the certificate to a location accessible by the BPA Platform server running the Sage 300 Conector tool.

Step 5: Change the Sage 300 Connector Agent to use HTTPS

1. From the Sage 300 server, go to the Sage 300 Connector installation folder (by default, this is C:\Program Files(x86)\Sage 300 Connector Agent\.
2. Open Sage300IntegrationService.exe.config in a text editor such as Notepad. Ensure you run the text editor as Administrator otherwise you cannot save the file properly.
3. For the ServiceUri key, enter the URI using the following format:

   https://FQDN_of_the_Sage_300_server:port_number

   where:

   • FQDN_of_the_Sage_300_server matches the certificate name
   • port_number is the TCP port used to communicate with the Event Agent (default of 4207)

   For example: https://sage-300-2017.mydomain.local:4207

4. Save this change.
5. Go to Control Panel > Administrative Tools > Services.
6. Restart the Sage 300 Connector Agent service.

Step 6: Import the Certificate into the BPA Platform Machine

From the machine running BPA Platform and the Sage 300 Connector tool (note that isn’t necessarily the BPA Platform server; it could be a machine running just the BPA Platform client and Sage 300 Connector tool), do the following:

1. Copy the .CER certificate created in step 4 to this machine.
2. Double-click the certififcate.
3. Click Install Certificate in the General tab.
4. From the Store Location panel, select Local Machine.
5. Click Next.
6. Select Place all certificates in the following store and click Browse.
7. Highlight Trusted Root Certification Authorities and click OK.
8. Click Next then Finish.

   If the returned response is “The import was successful” continue with this procedure, else retry the certificate import.

Step 7: Enable HTTPS in the Sage 300 Connector Connection

For Existing Connections

Existing connections to this particular Sage 300 Connector Agent must be changed to use HTTPS; do the following:

1. Open the connection’s global configuration.

   You may experience a delay before the configuration opens as the Sage 300 Connector waits for the connection to the Agent to timeout first.

2. From the Agent Connection tab, click Advanced.
3. Enable Use HTTPS.
4. If communication is over a custom TCP port number (default of 4207), enable Set custom port number and enter the new port number below.
5. Click OK.
6. Go to the Company tab.
7. You must re-select the Company database the Agent is monitoring.
8. Click OK.

For New Connections

New connections to this particular Sage 300 Connector Agent must be over HTTPS. When adding the global configuration for this Agent, do the following to ensure communication is over HTTPS:

1. From the Agent Connection tab, click Advanced.
2. Enable Use HTTPS.
3. If communication is over a custom TCP port number (default of 4207), enable Set custom port number and enter the new port number below.
4. Click OK.