JSON Services (Legacy)

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 enable SSL on the Patriot Data Service's JSON communication port.

Deprecated

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.

1: Prerequisites

• JSON services can only be activated on Patriot installations registered with either the ICA Advanced module or the JSON SDK module(On Patriot v6.4, JSON Service can only be activated with JSON SDK module).

2: Enable the Patriot JSON Services

Open the AppSettings.json 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)

caution

Always make a backup copy of your Data Service config file before making changes.

Open the AppSettings.json file using a text editor. The JSON settings are as follows,

{
  "DataService": {
    "JsonSdk": {
      "Enabled": true,
      "UserName": "patriot",
      "Port": true,
      "Password":"Patriot12##",
      "Encrypted" : true
    },
  }
}

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 web browser 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 AppSettings.json).

Contact Patriot Support for the full list of JSON commands available.

3: Enable SSL Encryption

Installing the SSL certificate

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 circumstances 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 web browser 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 AppSettings.json).

Contact Patriot Support for the full list of JSON commands available.