Patriot includes a set of JSON services which are required by certain features of the ICA Advanced Module and/or Patriot's JSON SDK module. In many circumstances it is important that JSON communication on these services is encrypted for added data security. This document explains how to enable Patriot's JSON services and then how to to enable SSL on the Patriot Data Service's JSON communication port.
Please note that the usage of these services is deprecated, and should not be used for new development. See Third Party Integrations for our currently recommended integration methods for new development, including an updated REST API.
Open the PatriotService.exe.config file located within the Patriot server installation folder.. This file is normally found in,
\Program Files\Patriot Systems\Patriot Data Service
OR
\Program Files (x86)\Patriot Systems\Patriot Data Service (on 64 bit machines)
IMPORTANT: always make a backup copy of your Data Service config file before making changes.
Open the PatriotService.exe.config file using a text editor. Under application settings, PatriotService.Settings1, you will see all the existing application settings. The JSON settings are as follows,
.....
<setting name="JsonEnabled" serializeAs="String">
<value>True</value>
</setting>
<setting name="JsonServerPortNo" serializeAs="String">
<value>9001</value>
</setting>
<setting name="JsonUserName" serializeAs="String">
<value>patriot</value>
</setting>
<setting name="JsonPassword" serializeAs="String">
<value>Patriot12##</value>
</setting>
<setting name="JsonEncryption" serializeAs="String">
<value>True</value>
</setting>
</PatriotService.Settings1>
Add these settings in if they don’t exist and set the values as required:
JSONServerPortNo. Port the service is working on. This will need to be port forwarded to, through your firewall, if you wish to use the JSON service externally.
JSONEncryption If set to True, enables SSL encryption. It is highly recommended you enable encryption if you are using the JSON service remotely (ie outside the LAN).
JSONEnabled. Needs to be set to True before the JSON service is run.
JSONUserName and JSONPassword. The data service always sets the Http Client Credential Type to Basic. So a matching Username and Password must be supplied with every request. It is highly recommended that you change the username and password from the default values.
Now restart the Patriot Data service and Patriot's JSON services will attempt to start on your chosen port.
Depending on your server setup, you may need to add an HTTP Namespace Reservation on the selected JSON port before the services will run.
You can now test that the services are accessible over HTTP by browsing the services with a webrowser on the Patriot server.
E.g. browse to the URL http://localhost:9001/JsonClientService/GetClient?clientno=0001BASE01
You should be prompted for your JSON username and password (from the PatriotService.exe.config).
Contact Patriot Support for the full list of JSON commands available.
Before any client can connect to your encrypted JSON services you must install a valid SSL certificate on the Patriot Server and bind it to the JSON service port. How you go about this will depend on your particular use case. If multiple clients will be connecting to your JSON services then you will need to obtain your certificate from a trusted certificate authority. In other cirucumstances a self signed certificate may suffice.
One method of generating and binding a self signed certificate is detailed in this section.
Download Microsoft's IIS 6 resource kit installer here. The SelfSSL component must be selected from the Custom Installation options. All other components are optional.
Run the selfssl.exe tool from an Administrator command prompt:
CODE:
selfssl.exe /T /N:CN=localhost /K:1024 /V:3650
This command will generate a self signed certificate valid for 10 years and install it to the Trusted Root Certification folder.
Open Certificate Manager from the Windows Start menu by typing certmgr.msc into the Search box, and then pressing ENTER.
The new self signed certificate is easily identified by its Issued To field and expiration date. The certificate thumb print can be found by opening the certificate and scrolling down the Details tab.
You can now bind the certificate to your JSON service port with the following netsh command issued from an Administrator command prompt. The certhash value should be set to your new certificate's thumbprint.
CODE:
netsh http add sslcert ipport=0.0.0.0:9001 certhash=6e885e543b256a8631f1b3728f05536d8c7389d appid={00112233-4455-6677-8899-AABBCCDDEEFF} clientcertnegotiation=enable
The netsh command is again used to bind the certificate to the JSON service port.
You can now test that the services are accessible over HTTPS by browsing the services with a webrowser on the Patriot server.
E.g. To get the details of client 0001-01 browse to the URL https://localhost:9001/JsonClientService/GetClient?clientno=0001BASE01
You should be prompted for your JSON username and password (from the PatriotService.exe.config).
Contact Patriot Support for the full list of JSON commands available.