Installing security certificates for AX Server

Install a certificate from a Certificate Authority (CA) to replace the default self-signed certificate used to secure the SSL connection between AX Server and client applications.

Tools and prerequisite knowledge

This task requires you use Oracle's keytool utility for managing keys and certificates. For more information about the keytool utility, see the Oracle keytool documentation.

To successfully complete this task, you should also be comfortable working with security certificates and Java KeyStore technology:

Security certificate an electronic document used to prove the ownership of a public key. The certificate includes information about the key, information about its owner's identity, and the digital signature of an entity that has verified the certificate's contents are correct. For more information, see Security certificates
Java KeyStore a repository of security certificates plus corresponding private keys used for in SSL encryption. For more information, see Oracle: Creating a KeyStore

Backup the TomEE application server configuration before you start

In Windows Explorer, open the TomCat\conf sub-folder in the directory where you installed the Analytics Exchange server application you are updating the keystore configuration for.
Copy the conf\tomee.xml, conf\server.xml, and conf\system.properties files to a safe backup location.
If you run into any issues while you are configuring the security certificate, you can restore your original configuration by stopping the ACL Analytics Exchange Service, restoring these files, and then restarting the service.

Server-side process

Tip

Add the Java bin subdirectory to your OS PATH environment variable so that you can use the keytool command without specifying the full path. To add the subdirectory to the path for your session, execute Set PATH=<java_bin_path>;%PATH%.

If you are using a PFX certificate file, you can convert it to a keystore with private key using one keytool command:

keytool -importkeystore -srckeystore yourpfxfile.pfx -srcstoretype pkcs12 -destkeystore cientcert.jks -deststoretype JKS

Create a new keystore

Open a command prompt on the server.
Use the following syntax to create the new keystore:
keytool -genkeypair -alias <alias> -keyalg RSA -keystore <keystore_filename>
Example keytool -genkeypair -alias AX_store -keyalg RSA -keystore myAxKeystore

Answer each question when prompted:

Field	Example
What is your first and last name? Note You must enter the hostname of your AX Server instance for this question.	axserver.ax.com
What is the name of your organizational unit?	Purchasing
What is the name of your organization?	ExampleCompany
What is the name of your City or Locality?	Cupertino
What is the name of your State or Province?	CA
What is the two-letter country code for this unit?	US
Is <CN=axserver.ax.com, OU=Purchasing, O=ExampleCompany, L=Cupertino, ST=CA, C=US> correct?	y

Press Enter to use the same password as the keystore or specify a new password and press Enter.

Generate a Certificate Signing Request (CSR) on the new keystore

Note

Skip this section if you are using an existing certificate.

If you purchased your security certificate from a commercial CA, such as VeriSign, consult the documentation they provide for information on configuring your keystore. Create a CSR using the following syntax:

keytool -certreq -alias <alias> -keyalg RSA -file <csr_output_file> -keystore <keystore_filename>

Result You now have a file that you can use to request a certificate from a certificate authority.

Import your CA certificate into the keystore

If your certificate is in a format such as PKCS12 that cannot be imported into a keystore, and you cannot convert it to the PEM format, contact Support for assistance with configuring the certificate in Tomcat.

Depending on the CA you are using you may need to import an intermediate certificate and/or root certificate into your keystore. Use the following syntax to import one or both of these certificates:
keytool -import -alias <alias> -keystore <keystore_filename> -trustcacerts -file <certificate_filename>
If you are importing both certificates the alias specified for each certificate should be unique. You need to first import the root certificate, and then run the keytool command again to import the intermediate certificate.
Use the following syntax to import your security certificate:
keytool -import -alias <alias> -keystore <keystore_filename> -trustcacerts -file <certificate_filename>
The alias specified must be the same value specified when you generated the keystore. The imported certificate will replace the default self-signed certificate created in the keystore.
Copy the keystore file to the App\keystores sub-folder.

Configure the TomEE application server to use the certificate

Locate server.xml in the TomCat\conf sub-folder and open it in a text editor.
Update the following settings and then save and close server.xml:
- keystoreFile the name and path to the keystore file you created in the following format: C:\ACL\App\keystores\<your_keystore_name>
- keystorePass the password you specified for the keystore when you created it. The password must be enclosed in double quotation marks ('' '').
Locate system.properties in the TomCat\conf sub-folder and open it in a text editor.
Update the following settings and then save and close system.properties:
- javax.net.ssl.trustStore the name and path to the keystore file you created in the following format: C:/ACL/App/keystores/<your_keystore_name>
  Note
  You must use the forward slash '/' character in the keystore path. If you use the backslash character '\' as is common in Windows environments, you will encounter server errors when logging in.
- javax.net.ssl.trustStorePassword the password you specified for the keystore when you created it
Restart the ACL Analytics Exchange Service.

Client-side process

Import certificates into the AX Client machine Java cacerts file

This configuration must be completed on each end-user computer where AX Client is installed if you are using a certificate without a root certificate in the cacerts file by default.

Open Windows Explorer and navigate to the cacerts file in the jre\lib\security sub-folder where AX Client is installed.
The default location is C:\Program Files(x86)\ACL Software\ACL Analytics Exchange Client\jre\lib\security
Create a backup copy of the file before making any changes.
Depending on the certificates you receive from the Certificate Authority you are using, you may need to import an intermediate certificate and/or root certificate into the cacerts file. Use the following syntax to import one or both of these certificates:
keytool -import -alias <alias> -keystore <cacerts_file> -trustcacerts -file <certificate_filename>
If you are importing both certificates the alias specified for each certificate should be unique.
Type the password for the keystore at the Password prompt and press Enter.
The default Java password for the cacerts file is changeit.
Enter y at the Trust this certificate? prompt and press Enter.

If necessary, install the certificate in the web browser on each computer that will access Analytics Exchange web applications.