You may have a situation whereby you want to use client certificates to authenticate users. This may be desirable if you have an integrated environment where you can generate your own client certificates and automatically distribute them to the client PCs/laptops.

NOTE: bear in mind any external interfaces that connect to your X3 system when thinking about using this option.  For example, they may need to be excluded from client certificates entirely.

Sage X3 provides this facility, with two related configuration options:

1. You can configure Client authentication such that the browser just needs to present a client certificate which is signed by a CA the Server knows about in order to proceed. The user will still need to login with a valid username and password, so this is just an added layer of security.
2. Once setup as step 1 above, you then have the option to additionally configure Syracuse such that the Common Name in the client certificate is taken as the users X3 Login name, therefore not prompting the user for username/password in this case.

These steps are described in the online help at https://online-help.sageerpx3.com/erp/12/staticpost/host/

In this blog article I will describe the following steps:

1. Configure X3 Server for Client authentication.
2. Create a new Client certificate, which is now required for any user to connect.
3. Install the client certificate in the client browser, which then allows login as normal (using a username/password)
4. Introduce certificate only sign-on by configuring client-side certificates to authenticate the users.

Configure X3 server for Client authentication

First, we need a server certificate to use as an indicator to Sage X3 which CA we want to use for client authentication.    i.e. all client certificates need to be signed by the same CA as this server certificate.

In reality you will likely need to load into X3 the CA certificate and generate then load this server certificate from your certificate provider. For the purposes of my testing, I will re-use the existing CA certificate generated by the Syracuse installation, which is already loaded in Administration, Administration, Certificates, Certificates of Certification Authorities. I will however create a new “dummy” server certificate to use for the client certificate configuration.

Launch the tool D:\Sage\Syracuse\syracuse\certs_tools\certgen.bat

You can enter any name you like to the server, as it isn’t being used for anything other than pulling out the CA details.   I will call mine “clientcerts”

In X3, Navigate to Administration, Administration, Certificates, Certificates

Create a new certificate, you only need to load the certificate itself not the private key, and specify the ca.  You do NOT want to enter anything for “server” (Syracuse hosts)

To start with, we only want to update the server to use Client Authentication.

Navigate to Administration, Administration, Servers, Hosts

I am going to leave the non-SSL port 8124 alone and just update port 443.   For production systems you should not be allowing user connections on the 8124 port anyway.   Select the “Client Authentication” check box and select the “Client certificate” then save the changes.   Be aware this may result in Syracuse automatically restarting.  If not, you will need to manually restart the service for the change to take effect.

Now try to connect to the URL https://myHost.example.com/   You will get the following error as Syracuse needs a client certificate to be presented:

NOTE: you can still connect normally using http://myHost.example.com:8124/ without a certificate.

Create a new Client certificate

We will create a client certificate, using the CertGen tool, as we must use the same CA as the “clientcerts” server certificate from the previous stage.

I am creating a certificate called “mike” to save some time, as I will use this same certificate later in the final stage for my own personal login… but you can enter any name as required.

Launch the tool D:\Sage\Syracuse\syracuse\certs_tools\certgen.bat

 Check the created certificate D:\Sage\Syracuse\syracuse\certs_tools\output\mike.crt

Create a PKCS12 format client certificate using the following command (assuming you have openssl installed):

cd D:\Sage\Syracuse\syracuse\certs_tools\output

set PATH=D:\OpenSSL\bin;%PATH%

openssl pkcs12 -export -in mike.crt -inkey mike.key -certfile ca.cacrt -out mike.p12

Copy the resulting “mike.p12” file to the client PC or Laptop.

Install the client certificate on the client PC for the browser to use.

The installation of the Client certificate may vary for different browsers, but most browsers should be using the Windows keystore to find the certificates.

Simply double click the “mike.p12” file on the Windows PC and go through the Certificate Import Wizard.

 We can then run “certmgr” to view the certificate just added.

 Try to connect to the URL https://myHost.example.com/

I am now prompted to select the certificate with which to authenticate to Syracuse.

Chrome:

Firefox:

As this certificate is valid, I can now progress to the normal login screen, where I still need to enter my login details as normal (using ADMIN user for example)

Configure X3 server to use client side certificates for user authentication.

Although we now need a Client certificate to get to the login screen, every user could use the same Client certificate, and they still need to type in their username and password.   If needed we can now configure X3 to take an individual Client certificate and present as the users authentication token

Edit D:\Sage\Syracuse\syracuse\bin\nodelocal.js

Change the line

      "auth": "basic"

to be

      "auth": ["basic", "certificate"]

Restart the Syracuse service for this change to take effect

Login using https://myHost.example.com/

I am selecting the “Mike” certificate and as the “Mike” user exists in X3 I am routed straight into X3 navigation page without having to enter my username and password.

If my certificate name does not match an X3 username, I will see an “Authentication failed” message.

NOTE: to exit X3 the user still needs to click “Log out” in order to close their sessions correctly, which returns them to the login screen.  The user can then just click the “Sign in” button without entering username/password to go back into X3 if needed.

Conclusion

Hopefully this article clarifies the steps needed to implement Client certificates with Sage X3.   Feel free to provide your feedback in the comments below.