Connector Security

Please ensure that you have read and understand the following topics before continuing on:

• Get Started/Overview document
• Microsoft Windows http://en.wikipedia.org/wiki/Microsoft_Windows
• Windows Services http://en.wikipedia.org/wiki/Windows_service
• Windows Applications
• Windows users
• Windows Permissions
• HTTP/HTTPS https://en.wikipedia.org/wiki/HTTPS
• x509 Certificates
• Connector Adaptors
• OpenSSL

For any Connector installation the are a number of mechanisms that can be set up to ensure that Connector runs securely, and safely for transfering sensitive information between business systems, and Ecommerce systems. These mechanisms include the following:

• Configuring the port number that the Connector's Host Service runs on.
• Configuring the Connector's Host Service to use the HTTPS protocol to securely encrypt data being sent through the public internet or internal networks.
• Configuring adaptors to restrict data access to specific systems talking to the Connector software and associated business systems.
• Setting up Windows user permissions to restrict user access to data and settings configured to the Connector.

Each of the following sections below go into more details of each of these points.

When any 3rd party system or software wants to access data made available by the Connector, a HTTP request will be sent to the Connector's Windows Host Service. Before the Connector can accept a request it must be configured to listen on a "port" where it can accept requests from.

By default when the Connector is first installed in Windows it will be set to listen on port 8050. This means that any HTTP requests made to the Windows computer will fail unless the request specifically targets the correct port 8050. In modern times Windows by default will block access to all ports using its inbuilt firewall software. If this occurs then you need to add an exception to the Windows Firewall (or any other installed firewall/anti-virus software) to allow incoming requests to the Connector's Host Service on the Connector's configured port (8050 by default).

Once a Windows computer is allowed to recieve incoming HTTP requests to the Connector's port, that alone will only allow other computers in the same connected internal network to send requests to the Connector. To allow requests to be sent from over the internet (such as allowing Squizz.com to do so) you will need to have setup in your internet router and/or other networking devices a port forwarding rule. This tells the router that any incoming requests from the internet on a given port are allowed to be redirected to the computer where the Connector service is running. It's important to be aware that once this is setup that any external 3rd parties will then be able to access the Connector service (if they have the correct internet address, port number and Connector credentials to do so). To control which 3rd parties can have access the Connector installed on your Windows computer please read the "Restricting Access Of Incoming Requests To The Connector Host Web Service" section further down.

To change the port that the Connector Host Service runs on, follow these steps:

1. Open the Connector Application by clicking on its icon from within the Windows start menu.
2. Click on the Settings tab.
3. In the Web Service Port text box enter the port number that you want the Connector to listen on. This can be a number between 1 and 65535.
4. Click on the Save button.
5. Under the Connector Service Status section Click on the Restart button. This will restart the Connector's Windows Host service. If you cannot restart the service from the application then you will need to restart from the Windows Services program which is available from the Control Panel's Administration Tools area.

Once the Connector service is restarted then any requests sent to the computer on the specified port will be forwarded to the Connector's Host Service to process.

Sometimes you may want several different 3rd parties to be access data from the Connector service installed on your computer. However you may not want them to be able to access all the data that the Connector provides. In this circumstance it is possible to restrict which 3rd parties can access data through the use of adaptors and "Adaptor Data Routing".

Adaptor Authentication

When a request is made to the Connector Host Service, each request must initially go through to one adaptor to handle the request. For each adaptor there is the ability to set an Adaptor Key, and an Adaptor Password. Only if the incoming request has the correct adaptor key and adaptor password will the Connector allow the request to proceed to the adaptor and allow data to be retrieved from its configured data source. The way that the Connector validates the adaptor key and password in the incoming request is by using HTTP Basic Access Authentication. Incoming requests must place the adaptor key and password into the HTTP request's header, where the key and password have been encoded into a the Base64. This looks something like Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

The Connector will compare this request header against the adaptor's known key and password, and only if they both match will the request be accepted. This method means that the 3rd party software making requests to the installed Connector must be told of the adaptor key and password needed to pass the Connector's adaptor authentication. Without knowing both pieces of information a 3rd party will be unable to access any data. It is advisable to make the adaptor's password as long as possible to make it as difficult as possible for automated intruder software to guess the adaptor password. Also avoid setting a password based on text that can be easily found in a dictionary. Lookup Dictionary Attacks and Brute Force Attacks for more infornation on what you can do to protect the Connector software from attackers.

Using Adaptor Data Routing To Limit Data Access

Once a single adaptor within the Connector has been setup with a key and password, all 3rd parties who have both the adaptor key and password will be able to access any, and all data made available from an adaptor's datasource. This however may not be ideal since you may want to limit access to one specific piece of data for one 3rd party, but make all data accessible to another 3rd party.

In this scenario where you want to limit access of data at different levels for different 3rd parties, this can be achieved by setting up multiple adaptors in the Connector. With multiple adaptors in place you can set up different credentials to each adaptor, then use the "Adaptor Data Routing" functionality to control which adaptor has access to another adaptor's data for each given data export/import. 

Lets take an example Adaptor X and Adaptor Y are setup in the Connector. Adaptor X is configured to retreive all data from a connected busines system. Adaptor Y is NOT configured to obtain data from any system, but instead a route has been setup so that when any requests come in to Adaptor Y to retrieve product data, they are forwarded to Adaptor X. All other data requests in Adaptor Y are not routed and blocked. The credentials to Adaptor X are given to the Ecommerce system called "Trustworthy Websites Pty Ltd". The credentials to Adaptor Y are given to the Ecommerce system called "Restricted Websites Pty Ltd". In this scenario Trustworthy Websites will be able to retrieve all data such as products, customer accounts, taxcodes from the ERP system that Adaptor X is configured to. Restricted Websites however will only be able to retrieve product data using Adaptor Y, since it only is allowed to forward requests to Adaptor X to obtain products from Adaptor X's connected ERP system.

Setting up separate adaptors for each 3rd party makes it easier to control data access within the Connector. That coupled with the use of adaptor data routing makes is simple to configure only one data source, which multiple adaptors can leverage off.

The Connector Host Windows Service runs as a Web Service. This allows other connected computers to make incoming requests for obtaining, or pushing data from the Connector service. This communication can be done over the public internet, or within a private computer network. To ensure that any data read from the Connector, or given to the Connector cannot be read by any other computer when the data is in transit, we need to encrypt the data. Once the data is encrypted only the sender and intended receiver can understand what has been sent.

The Connector can be set up to use the HTTPS transport protocol to do the encryption work for its web service (HTTPS is the same technology also used to encrypt data in a web browser). In order to use HTTPS a security certificate (TLS/SSL) needs to be issued and installed on the computer where the Connector Host service is installed. This certificate contains the keys used to lock and unlock the encrypted data.

Ways To Obtain a Security Certificate

The easiest way to get a TLS/SSL ceritifcate is from Squizz.com which offers them for free to any organisations signed up to the platform. Otherwise you will need to pay a seller such as Verisign, or Geotrust to issue you out a certificate. The certificate sellers have one big bonus in that their certificates are widely trusted by other computers, where as certificates issued by Squizz.com are only trusted by computers that have Squizz.com's root CA certificates installed. This means that if you want computers besides Squizz.com to be able to talk to your installed Connector, then you either need to get those computers to install the Squizz.com CA certificates, or else you buy a certificate off the major sellers. A 3rd option is to create your own self signed certificates. This is useful if you only want computers under your control to be able to talk to the Connector webservice over HTTPS, such as in an internal network.

When you want a certificate you need to provide details about your business/organisation, as well as the domain name or public IP address where the certificate will be used. It is important that the certificate is issued to the correct domain or public IP address that the Connector is running on, otherwise the certificate will not work.

Squizz.com offers a way for organisations to obtain a security certificate for free, which can be can used to secure incoming requests to a Connector. To obtain a certificate from Squizz.com follow these steps:

1. Open a web browser and enter the URL www.squizz.com
2. Click on the Login button.
3. In the fields type in your Email and password that you have registered with (if you have not registered yet then you need a person who has registered to send you an invitation). 
4. Click on the Login button.
5. Click on the Organisations menu button.
6. Find the relevant organisation that you are an administrator of and click on its profile icon.
7. In the organisation profile click on the Admin button.
8. In the Admin area click on the Security Certificates button.
9. Click on the Create Certificate button.
10. Enter the public IP address or domain that the Connector application will be accepting requests from. This will typically be a static IP address designated to the organisation's router, or a domain setup using DNS. It is important that if an IP address is set that it is static IP address, otherwise the certificate won't work when an internet connection to the Connector changes it IP address and no longer matches the certificate.
11. Click the Save button.
12. Copy the certificate ID of the newly created certificate.
13. Close the Security Certificates dialog.
14. Open the Connector application that is installed on the computer that the certificate will be setup on.
15. Click on the Adaptor button for any adaptor.
16. Within the Squizz.com Settings tab enter the settings used to connect with the squizz.com organisation.
17. Click on the Test button to ensure a connection can be made to Squizz.com APIs.
18. Click on the Verify Certificate button.
19. Paste in the certificate ID copied from step 12.
20. Click the Verify button. A request will be made to Squizz.com's API to validate the certificate with the IP address used to send the verification. If the IP address matches the IP address or domain set against the certificate then squizz.com will activate the certificate.
21. Maximise the web browser that was display the Squizz.com organisation profile.
22. Click on the Security Certificates icon again.
23. The certificate should now show links to download the certificate's files.
24. Download the certificate files. This includes:
    • Certificate Private Key
    • Squizz Intermediate Certificate
    • Squizz Root CA Certificate

Once the certificate files have been downloaded you can then use these files to secure the Connector, or secure any other third party software (such as Apache, Nginx web server software) to allow Squizz.com to securely send requests to the Connector. See the next section on how to use the certificate files to secure the Connector's Host Service.

To secure incoming requests to the Connector Host service issued from Squizz.com, you will first need to download and add Squizz.com root CA (Certificate Authority) certificates to the Windows certificate trust store. This will tell Windows that Squizz.com is a trusted authority, and that any traffic data encrypted with Sqiuzz.com security certificates is OK. Squizz.com issues two certificates, the root CA certificate, and the intermediate certifcate, that both can be downloaded from the Admin area of an organisation's profile within Squizz.com.

Once you have download both the root CA certificate, and the intermediate certificate, do the following steps to install these within Windows. These steps require you to have administrator access to the Windows machine.

Steps to Install Squizz.com root CA certificate

1. In the Windows search box type the text mmc.msc
2. Right click on the mmc application and click the Run as administrator menu item
3. Click on the File menu item.
4. Click on the Add/Remove Snap-In... menu item.
5. In the Available Snap-Ins list select the the Certificates Snap-In then click on the Add > button
6. In the Certificates Snap-in dialog click on the Computer Account radio option then click the Next button.
7. Click on the the Local Computer radio option then click on the Finish button.
8. In the Add or Remove Snap-ins dialog click on the OK button.
9. Click on the arrow to expand the Certificates (Local Computer) tree,
10. Expand the Trusted Root Certification Authorities folder
11. Righ click on the inner Certificates folder
12. Click on the All Tasks menu item
13. Click on the Import menu item. The Certificate Import Wizard will open.
14. In the Certificate import wizard check that the Store Location is set to Local Machine. If it is not then you may not be running the mmc application as an administrator and will have to go back to step 1. In older versions of Windows you may not be able to see the Store Location option and can continue on.
15. Click on the Next button.
16. In the File Name text box click on the Browse button and navigiate through the filesystem to find the root certificate file that you had downloaded from Squizz.com.
17. Click on the Next button.
18. Select the Place all certificates in the following store radio option if it not already selected.
19. Click on the Next button.
20. Click on the Finish button. If another confirmation dialog appears accept that you wish to add the ceritificate.

Steps to Install the Squizz.com intermediate CA certificate

1. In the Windows search box type the text mmc.msc (skip steps 1 to 9 if following from the previous steps)
2. Right click on the mmc application and click the Run as administrator menu item
3. Click on the File menu item.
4. Click on the Add/Remove Snap-In... menu item.
5. In the Available Snap-Ins list select the the Certificates Snap-In then click on the Add > button
6. In the Certificates Snap-in dialog click on the Computer Account radio option then click the Next button.
7. Click on the the Local Computer radio option then click on the Finish button.
8. In the Add or Remove Snap-ins dialog click on the OK button.
9. Click on the arrow to expand the Certificates (Local Computer) tree,
10. Expand the Intermediate Certification Authorities folder
11. Righ click on the inner Certificates folder
12. Click on the All Tasks menu item
13. Click on the Import menu item. The Certificate Import Wizard will open.
14. In the Certificate import wizard check that the Store Location is set to Local Machine. If it is not then you may not be running the mmc.msc application as an administrator and will have to go back to step 1. In older versions of Windows you won't be able to see the Store Location option and can continue on.
15. Click on the Next button.
16. In the File Name text box click on the Browse button and navigiate through the filesystem to find the intermediate certificate file squizz_intermediate_ca.cert.pem that you had downloaded from Squizz.com.
17. Click on the Next button.
18. Select the Place all certificates in the following store radio option if it not already selected.
19. Click on the Next button.
20. Click on the Finish button. If another confirmation dialog appears accept that you wish to add the ceritificate.

When a security certificate is created within Squizz.com there two files that you can download for it. The certificate file example_org.cert.pem contains a public key of the certificate. This key can be made freely available to anyone in the world. The second file example_org.key.pem contains the private key that should be kept very safe and secure from the general public. The private key ensures that only your machine can be used to authenticate and communicate with safely.

To add the certificate in Windows certificate manager you must first combine the public certificate key with the private certificate key into a single PKCS12 file. To make this possible you need to install and use a command line application such as OpenSSL which can do so. Once you have openssl on your Windows machine do the following steps to make the PKCS12 file (which contains the extension .pfx).

1. Open a command line console by running it as an Administrator user, and type the following (ensure you change mydomain_or_ip text to the actual domain or IP address your connector will be running on).
   
   openssl pkcs12 -export -out mydomain_or_ip.pfx -inkey mydomain_or_ip.key.pem -in mydomain_or_ip.cert.pem -certfile squizz_intermediate_ca.cert.pem
    
2. The console application will ask you to set a password for the certificate. This password will be used later to allow the pfx file to be added to the Windows Certificate Manager. The password also is used to gain access to the private key in the file so be careful not to make the password too easy.
3. In the Windows search box type the text mmc.msc
4. Right click on the mmc application and click the Run as administrator menu item
5. Click on the File menu item.
6. Click on the Add/Remove Snap-In... menu item.
7. In the Available Snap-Ins list select the the Certificates Snap-In then click on the Add > button
8. In the Certificates Snap-in dialog click on the Computer Account radio option then click the Next button.
9. Click on the the Local Computer radio option then click on the Finish button.
10. In the Add or Remove Snap-ins dialog click on the OK button.
11. Expand the Personal folder
12. Righ click on the inner Certificates folder
13. Click on the All Tasks menu item
14. Click on the Import menu item. The Certificate Import Wizard will open.
15. In the Certificate import wizard check that the Store Location is set to Local Machine. If it is not then you may not be running the mmc.msc application as an administrator and will have to go back to step 1. In older versions of Windows you won't be able to see the Store Location option and can continue on.
16. Click on the Next button.
17. In the File Name text box click on the Browse button and navigiate through the filesystem to find the pfx file generated from step 1.
18. Click on the Next button.
19. Select the Place all certificates in the following store radio option if it not already selected.
20. Click on the Next button.
21. Enter the password that you set from step 2.
22. Click on the Finish button. If another confirmation dialog appears accept that you wish to add the ceritificate.

Steps to assign the Squizz.com issued certificate to a port

Once the certificate issued by Squizz.com has been added to the Windows Certificate Manager we then need to tell Windows to associate the certificate to a given port. This will allow the Connector to listen in on the port and use the certificate to accept requests over HTTPS.

1. Open up a console.
2. Type in the following command, replacing the [thumbprint] value with the certificate's thumbprint and the port number based on the port that the Connector is configured to listen to incomming connections on. For certificates created in Squizz.com the thumbprint can be found by viewing the details of the certificate, located in an organisation's profile, within the Admin area, clicking on the Security Certificates button, then clicking on the certificate's IP address/domain to open the Certificate Detail dialog). If the certifcate was created with another certificate issuer then look at their documentation on how to get the certificate's thumbprint. Also you may need to change the port number if you have assigned the Connector to a different port.
   
   netsh http add sslcert ipport=0.0.0.0:8050 certhash=thumbprint appid={3067d291-68f9-47ee-8769-32e0fe544c9f}

Note: If the netsh command returns the error "A specified logon session does not exist. It may already have been terminated", then this means that it could not find the certificate based on thumbprint given. You will most likely need to add the certificate to the MMC window again or try setting the thumbprint of an other matching certificate.
Note: If in the future you need to unassign the certificate from the port then run the command Netsh http delete sslcert ipport=0.0.0.0:8050

To have the Connector's Windows Host service run and accept encrypted data requests using the HTTPS protocol, follow these steps:

1. Open the Connector Application by clicking on its icon from within the Windows start menu.
2. Click on the Settings tab.
3. Next to the Security Mode setting click on the Secure (HTTPS Using TLS/SSL) radio option.
4. In the x509 Certificate Thumbprint enter the thumbprint of the certificate listening on the Connector's port. The certificate's thumbprint can be found by viewing the details of the certificate within the MMC Windows application, or from the issuer of the certificate. In Squizz.com this can be found by viewing the details of the certificate within the Organisation's profile page.
5. Click on the Save Settings button.
6. Under the Connector Service Status section Click on the Restart button. Alternatively you can restart the Connector Host Service by doing the following:
   1. Click on the Windows Start button
   2. In the Windows Search text box type in Administrative Tools
   3. Click on the Administrative Tools program
   4. Click on the Services program
   5. In the Services window locate and right click on the service named SQUIZZ.com Connector Host
   6. Click on the Restart or Start menu itmes to restart the service.
      This will restart the Connector's Windows Host service..If you cannot restart the service check that you have Windows Administrator privillages with the Windows user you are logged in as.

Once the Connector service is restarted then any requests sent to the Connector over HTTPS will be security encrypted and decrypted by the Connector. It this is not working for you then you will need to check that the correct security certificates have been installed, and assigned to correct port that the Connector is listening to incomming requests on. Another problem can arise where multiple certificates are installed on the same machine with the same domain or IP address. Sometimes this can cause the computer sending the HTTPS request to get confused with which is the correct certificate. If that occurs then you may need to change the public IP address or domain in the certificate and start the certificate installation process again.

When the Connector Host Service is installed on a Windows computer it creates a number of files within the Windows ProgramData/SquizzCom folder (the ProgramData folder is hidden by default). One of these files connectordb.db3 is an SQLite database file which is used by the Connector to store all of its settings, configurations, credentials, and other data such as logs. It is important that this file is locked down with file permissions and made only accessible to allowed WIndows users, as well as the System user that the Connector Host Windows Service is running as (or any other designated user). Remember that if a Windows user does not have permission to read the file, that they also won't be able to use the Connector application.

Additionally in the ProgramData/SquizzCom directory other files can exist within the filename suffix adaptorcachedb.db3. These are also SQLite database files which store cached data and reduce the amount of data needing to be sent out from the Connector. These files may also need to be locked down with file permissions since they may store business sensitive information.

It is advisable to backup all files within the ProgramData/SquizzCom directory on a regular basis and ensure that the backups are safely secured. Also try to avoid deleting or moving any files within this directory since it could affect the running of the Connector, unless you know specifically what a file does.