ICA Installation
Requirements
- Patriot ICA requires its own domain or subdomain, such as https://example.com or https://ica.example.com. Installing ICA on a folder within an existing domain is not currently supported, for example https://example.com/ICA/.
- The ICA address needs to be accessible from both external networks (i.e. internet users) as well as internal networks (i.e. operators)
- Patriot needs to be on version 6.6.26 or later, with the ICA module registered.
- Additional configuration may need to be added to your Patriot Data Service configuration file.
- You will need a web server that can run Microsoft Internet Information Services (IIS)
- You will need an SSL certificate for the web server. If you are planning to use Dealer Branding, it is recommended to get a wildcard certificate as it is much simpler than having a separate certificate per dealer.
There are no separate ICA updates, the ICA components are packaged into the main Patriot updater.
Patriot Server setup
Run the Patriot client utilities program as an administrator.
This program can be found in the Patriot client install directory, typically C:\Program Files (x86)\Patriot Systems\Patriot Version 6 Client\UtilitiesProgram.exe
In the System Menu, select System Settings > ICA Setup.
If ICA Setup is unavailable, you will need to update your version of Patriot, or use ICA Manual Server Setup instead
Service Settings
API Port Number
The TCP port which the data service will listen for API requests on. Can be any available TCP Port.
Token Timeout
The maximum number of hours which a user can be logged in, without being automatically logged out. Can be disabled by ticking Disable Api Timeout, which means token will effectively never expire.
Token Idle Timeout
The maximum number of minutes a user can be idle for, without being automatically logged out. Set to 0 to disable idle logout. Can be disabled by ticking Disable Token Idle Timeout, which means token will effectively never expire due to inactivity.
Token Secret Key
A private key used to generate the login tokens used by the client. To generate a new key, click the refresh button next to the field.
HTTP Binding Setup
The Patriot Data Service requires an HTTP binding to allow it to listen for incoming requests.
Ensure the Port Number matches the service API Port Number field, and that the user name matches the user which the data service is running under (typically NT AUTHORITY\SYSTEM).
SSL Certificate
The Patriot Data Service requires an SSL certificate to encrypt communication between the Data Service and the web server. This is a separate certificate than the one between the web server and the end-user customers.
Since this is only used internally between the Patriot server and web server, a self-signed certificate can normally be used. A trusted certificate from a 3rd party provider can be used instead, if required. If using an existing certificate, ensure it is installed into the local computer certificate store under the Personal\Certificates folder. Installing certificates into the current user store is not supported.
Ensure the Port Number matches the service API Port Number field, and then select an existing certificate or enter the details to generate a new self-signed certificate.
If generating a self-signed certificate, the Subject Name field must match the host name the web server is using to access the Data Service (usually the Data Servers Computer Name). The certificate must also be exported, and installed into the trusted root section of the computer certificate store on the IIS Server.
System Settings Configuration
From the System menu in the main Patriot client, select System Settings, then System Wide Settings.
On the General Client Settings tab, enter the appropriate ICA Settings
On the Data Service Settings tab, check the Timezone Support option. ICA only supports Standard timezone mode, and timezones won't be displayed in ICA if Timezone support is set to Legacy or Disabled. See Timezones for more information.
Save the changes to the system settings.
Test Data Service Setup
At this point, the data service should have all configuration in place. The data service will now need to be restarted, in order to apply the new settings.
Once the service has restarted, check that you can access https://patriotserver:9005/ from the web server (replacing server name / port number to match configuration).
You should see a login page for ICA, and the certificate should show as valid.
Web Server Configuration
Requirements
Ensure that Microsoft Internet Information Services (IIS) is installed
Install the Application Request Routing and URL Rewrite modules for IIS. Both install through the Microsoft Web Platform Installer 5.1
Install an SSL Certificate and enable it. Follow the instructions from your SSL Certificate provider for this step.
If a self-signed certificate was used on the data service server, install the self-signed certificate as a trusted root certificate on the web server.
IIS Setup
Run IIS Manager
Select the server, then select 'Application Request Routing Cache' in the Features View. Under Actions on the right, select 'Server Proxy Settings', then tick 'Enable Proxy' and save the proxy settings.
Return to the server Features View, then select Configuration Editor. Select the Webserver/proxy section. Find the key labelled "preserveHostHeader" and set it to True.
Return to the server Features View, then select URL Rewrite. From Actions, create a new blank rule.
Configure the rule as follows:
Add a new condition:
Update the pattern to match your ICA website address.
Update the URL to match your data service configuration. Ensure the /{R:0} segment is left on the end.
If you want visitors using HTTP to automatically redirect to HTTPS, which is strongly recommended, then add another rule as follows:
Again, update the URL in the condition to your ICA website address.
You may need to register your new ICA website in your DNS records to be able to connect from external devices.
Additional Security Configuration
Setting up a public website requires many security considerations. This document contains guidelines specific to the Patriot ICA web portal but is not intended as a complete security guide. We strongly recommend you consult an IT professional for the latest best practices.
Firewall Rules
All access to the Patriot Data Service API port should be made through IIS. To enforce this, set up your firewall to block all traffic to the API port except from the IIS Web Server source address.
TLS Configuration
Patriot ICA uses TLS to ensure the communication between the browser and the server is secure. This is controlled by the web server which by default can support a number of different encryption protocols and cyphers. Some of these protocols and encryption cyphers have over time had security vulnerabilities detected. This section is intended to confirm that only secure protocols are enabled on your web server.
If you are UL or ULC compliant, this section is compulsory when installing ICA.
Security Protocols
Only TLS 1.2 and TLS 1.3 should be enabled. TLS 1.0 and TLS 1.1 and all versions of SSL should be disabled.
Disabling security protocols in windows requires the editing of the windows registry. This page contains the entries for each protocol. Windows Security Protocol Registry Entries.
Cypher Suites
TLS makes use of a number of different encryption cyphers. The combination of the cyphers used is called a cypher suite. It is recommended that only NIST compliant cyphers are used, and therefore only cypher suites making entire use of NIST compliant cyphers is used.
NIST provide a document with guidelines on configuring compliant cypher suites. Section 3.3.1 of the NIST TLS Configuration Guidelines explains how to identify compliant cypher suites.
This Microsoft document explains how to configure cypher suites within windows.
Additional Security Headers
IIS can be configured to send additional headers when serving ICA, which informs the browser to enable additional stricter security checks.
To enable these headers, either:
-
If your IIS is only used for ICA redirects, you can instead use the HTTP Response Headers section in IIS Manager's Features View. Be aware that if you have other sites hosted by your IIS, these headers will apply to all of them.
-
To apply the response headers to ICA only, view your IIS Rewrite rule for ICA and add a Server Variable. Name it
RESPONSE_{Header-Name}, e.g.RESPONSE_Strict-Transport-Security. Set the value to the desired header value.
Patriot recommends the following headers are enabled for maximum security:
Strict Transport Security
Requires that ICA is only accessed over secure HTTPS. Insecure HTTP connections will refuse to load.
Example, requiring HTTPS for 1 year:
Strict-Transport-Security: max-age=31536000
This should only be enabled once you have confirmed your HTTPS setup is working. Begin with a low value for max-age (e.g. 100) and slowly increase once testing has confirmed no problems.
Content Security Policy
Controls where ICA is allowed to load resources such as scripts and images from.
Recommended value, allowing only ICA content and Google Maps integration:
Content-Security-Policy: default-src 'self'; object-src 'none'; frame-ancestors 'none'; script-src 'self' 'unsafe-inline' maps.googleapis.com; img-src 'self' data: maps.gstatic.com *.googleapis.com *.ggpht.com; connect-src 'self' data: maps.googleapis.com;style-src 'self' 'unsafe-inline' *.googleapis.com; font-src 'self' fonts.gstatic.com
If you are using ICA customisation that loads content from additional sources, ensure you allow these sources in the Content-Security-Policy header.
Frame Options
Prevents ICA from being loaded within an iframe.
Recommended value:
X-Frame-Options: DENY
If you are embedding ICA within an iframe, don't set this header. Additionally, you will need to remove the frame-ancestors 'none'; segment from the Content-Security-Policy header, if set.
Testing ICA
At this point, ICA should be fully configured.
When the Patriot Data Service is restarted you can check the ICA API is running and the port it is running on locally in the Windows Event Viewer
Check that you can access ICA from external devices, and check that HTTP to HTTPS redirect is working, if you enabled it.
Accessing ICA from the internal network using the normal address will require NAT loopback support in your router, or other network configuration. Check with your IT provider to configure this as it is outside the scope of this document.
Customisation & Language Translation
Please refer to ICA Customisation documentation.