How to set up SSL with Sage X3

Products

Sage X3

Description

• How do I set up SSL with Sage X3?
• Where can I find documentation for setting up SSL?

Disclaimer

Support

Sage Customer Support does not provide assistance for issues related to third party products or enhancements, hardware, report customizations, state or federal tax-related questions, or specific accounting questions. Please contact your Sage business partner, network administrator, or accountant for assistance. Please review this document for additional information on the scope of Sage Customer Support Services.

Resolution

Note: Sage Support can assist if you run into errors but due to each organization's specific architecture and security reasons, cannot assist in your actual SSL implementation. Setting up SSL requires specific and detailed work on the part of your IT professional(s), Sage consultant(s), and third party vendors such as a Certificate Authority (CA) like GoDaddy or VeriSign.  This article is not intended to replace their knowledge or function, and only attempts to give a high level overview of SSL for Sage X3 from both Sage and non-Sage resources.  Please reach out to your Sage consultant or IT professional for assistance.  

What is SSL?  SSL (Secure Sockets Layer) is a security standard which allows for an encrypted link to be established between two points (i.e. a Web browser from a remote location to a Web server in a completely different location, over the a public space such as the Internet).  SSL consists of a private key and a public key.  This article discusses these key points and how they relate to Sage X3.

For SSL to function, you will need the following:

• Access to the Syracuse server
• Admin access to Sage X3
• A website (www.whatever.com)
• Expertise of and access to modify DNS records
• A certificate authority (CA), such as GoDaddy or VeriSign
• An SSL tool such as openSSL (an open source tool)

High level overview of steps:

1. Obtain a website, such as from a Certificate Authority.
2. Modify DNS records to reflect accordingly (both privately and publically as deemed required by your IT professionals) so your users can reach your server and be redirected to the Syracuse server.
3. Use an SSL tool such as openSSL (not affiliated with Sage) to create a certificate request (*.csr file) and private key (*.key file) on your Syracuse server.  The *.csr file contains the public key used by the Certificate Authority to verify who you are.
   • openSSL is an open source utility.  However, its developers only provide it in the original source code format.  You will have to compile it yourself into a usable *.exe binary using the correct programming language compiler, or locate a credible online source.  For your convenience, Sage has provided this tool if you install the SAFE X3 Web Server (generally used for ADC in newer versions of Sage X3).
     • If you've installed the Sage SAFE X3 Web Server, you can find openSSL *.exe binaries under C:\Sage\SafeX3\WEB235.2\tool\SOFTS\HTTPD\bin, for example.  Exact path depends on actual install location and version. 
     • Before running any openSSL commands, you must first specify this in your environmental path.  Run this from any location in the Windows command prompt (editing it first with the correct path):
       • set OPENSSL_CONF=C:\Sage\SafeX3\WEB235.2\tool\SOFTS\HTTPD\conf\openssl.cnf
     • In the Windows command prompt, browse to the bin folder noted previously and run this, which will create a *.csr and a *.key file:
       • openssl req -out myCompany.csr -new -newkey rsa:2048 -nodes -keyout myCompany.key
         • Note:  myCompany is the name of your company.
4. Keep the *.key (private key) file secure.  Send the *.csr (certificate request) file to a Certificate Authority of your choice.  They will generate and return you a *.crt (certificate) file.  If they return multiple *.crt files, ask them which one to use.
5. In Sage X3, create the certificate to be used by X3 using the following steps:
   1. Browse to Administration, Certificates, Certificates, and click +New certificates.
   2. Fill in the required blanks.
   3. In the top "Certificate" section, drag/drop the *.crt file.  Do not drop the *.key file or *.csr files here.
   4. In the "Private key" section, drag/drop the *.key file.  Do not drop the *.crt file or *.csr files here.  Do not leave this section blank even though it's not required.  Leaving it blank will generate an error in a later step.
   5. Enter a Passphrase.
      • Leave the CA Certificates/Server sections blank unless you know why you are entering values here.
   6. Click Save.  If save is successful, you have selected the correct certificate and private key.  If clicking Save does nothing, Sage X3 is detecting these are not valid files, are encrypted, or of the wrong format.  The public key must match the private key.
6. This step requires all X3 users to be off.  Browse to Administration, Servers, Hosts and click the pencil icon.  If you have multiple hosts, choose the one marked "Started".
7. Select SSL.
8. For the Server certificates field, click the browse button and choose the certificate you just created in X3.
9. Adjust the Port as necessary.  The port may remain 8124, but the actual industry standard secure port is 443.  Your IT professionals will need to configure your network to function with this port.
   • WARNING: If there is a problem with the certificate from the Certificate Authority, with the certificate setup, or with the port, you may be locked out of X3.  Refer to the knowledgebase article link below for more information and for a solution if that happens.  You may want to add another line/connection by clicking the blue plus sign instead of modifying the original one to add the SSL/Sever certificate with port 443 so Syracuse is listening on both ports.  However, if you want to prevent HTTP access completely and just force HTTPS requirement, leave only one connection marked with SSL. 
10. After clicking Save, it may prompt you that it'll restart the Syracuse service.  All users must be logged out before you click the next prompt or they will be disconnected from X3 forcefully.
    • Note: The Syracuse service may not restart automatically so you may need to restart it manually.  If the Syracuse service does not stop/start in a timely manner, use Task Manager to kill any node.exe processes.

Note: X3 v7 may require additional modification of the nodelocal.js file.