Overview: This post reviews information relating to the use of certificate(s) with the PI Connector Relay and OMF applications based upon questions from customers and partners.
Components required to send an OMF message and OMF application authentication
A recent release of the PI Connector Relay (Relay) introduced support for OSIsoft Message Format (OMF) enabling applications to send:
- a payload conforming to the OMF specification
- serialized as JSON
using the protocol: HTTPS to communicate with the PI Connector Relay REST endpoint. - This is the area of focus for the rest of the blog post.
Authentication of an OMF application is enabled by:
1. (recommended) OMF application verifies server certificate is trusted as part of the HTTPS protocol handshake - This is the sub area of focus for the rest of the blog post.
2. (required) OMF application authenticates with the Relay using a token. The token is created using the PI Data Collection Manager when setting up an OMF application.
Overview of the ssl tls handshake animation full flow - YouTube
Note: there is no client certificate exchange support in the Relay, as shown in the video.
Certificate authentication (or not) options
For 1. above there are options:
a. (recommended) Customer or Partner obtains a certificate generated by a Certificate Authority.
In general the recommendation is for the customer to generate their own trusted certificate, then install that certificate on the Relay machine and bind to the port used by the Relay.
An example of how to bind the certificate: PowerShell-Examples/Assign-Cert.ps1 at master · mofff/PowerShell-Examples · GitHub
For this option the client application retrieves the Relay certificate (as part of the handshake, see video link above) and verifies it with the operating environment to validate it as a trusted certificate.
b. (not-recommended) Add the self-signed certificate created by the Relay on installation to the OMF client environment, so that it is a trusted certificate
The default installation process for the Relay, creates a self-signed certificate and binds it to the network port selected during installation to be used by the Relay REST endpoint.
c. (not-recommended) Turn off the certificate verification process. This usually involves providing a parameter/option/setting so the check is not performed.
Review certificate setup
Note: If you want to view the certificate only, you can do that by pointing your browser at the Relay endpoint and clicking on the area to the left of the URL to display a menu that includes an option to view the certificate.
All steps assume you are working on the server with the Relay installed, unless otherwise noted.
1. Determine the port used by the Relay
Obtain the port from the following configuration file, one way to do that is using a command prompt or PowerShell prompt (preferred, since step 3 requires PowerShell)
type "C:\Program Files\PIPC\Connector Relay\Relay\Configuration\Ports.config.json"
2.List the configuration for the port used by the Relay
For this example the previous step identified the port as 5460
netsh http show sslcert ipport=0.0.0.0:5460
3. List details of the certificate bound to the port by searching the certificate store
Replace the text Thumbprint in the second command below with the CertificateHash identified from the output of the previous command and run from PowerShell:
cd CERT:\ Get-ChildItem -Path Thumbprint -Recurse | Format-List -Property *
The output provides information about the location of the certificate in PSParentPath. For example:a snippet of the output of the command above on a test system:
PSParentPath : Microsoft.PowerShell.Security\Certificate::LocalMachine\My
Indicates the certificate is in the Local Computer certificate store in the Personal folder
4. View the certificate
Steps to access the Local Computer certificate store and view the certificate in the Personal folder: How to: View Certificates with the MMC Snap-in | Microsoft Docs
1. While a self-signed certificate is created by the Relay installation process, the recommendation is to use a certificate created by a trusted certificate authority
2. Certificate management are functions external to the OMF application and Relay, i.e.:
The Relay does not manage the certificate(s), the certificate is in the certificate store, associated with the network port and the Relay is configured to use that port.
The OMF application does not store trusted, intermediate or self-signed certificates, they are managed by the Operating System or application environment
3..The OMF application can be configured to determine how to act during the certificate handshake, usually by providing options/parameters/switches to libraries that manage connection.