Using PI Web API Securely

Document created by jkim Employee on Jun 24, 2019
Version 1Show Document
  • View in full screen mode

I’d like to take some time to give some guiding tips on how to make your PI Web API more secure. “How do we lock down the PI Web API” is a question we often get here at OSIsoft and the answer it depends on a lot of factors, but there are some steps that you can use across all systems to safeguard your data.


  1. Ensure that mappings for your users on the Data Archive are set to least privileges.


This applies to all your applications in the PI System and not just the Data Archive. Ensure that no users have unnecessary access to data, whether that be read or writing capabilities, that they don’t need. This reduces the number of users and paths for unintended access.


  1. Ensure the mappings for your users on the AF Server are set to least privileges, particularly for the Configuration AF Database.


  1. Disable Writes through the PI Web API service


In the case that none of the users accessing the PI Web API need to write data, all data writing endpoints can be disabled through the use of the “DisableWrites” configuration parameter, which can be added to the System Configuration element for the PI Web API in the AF Configuration Database.



  1. Use Kerberos or Claims-based authentication to ensure that users accounts are less easily spoofed/stolen


Now onto some more programming related topics:


  1. Cross-origin Resource Sharing (CORS)


As we discussed in the video on the topic, Cross-Origin Resource Sharing is a method of allowing access on scripts running in one domain from access resources, such as the PI Web API, in another. This is relaxation of typical modern browser’s same-origin policies. An origin is a unique combination of protocol (HTTP, WSS, etc.), hostname of the site, and port number that is used to reach a given web resource.


This section only applies to you and your application if you’re writing an application against the PI Web API with scripts running on the browser (e.g. making a REST call from your JavaScript application). By default, CORS is disabled in the PI Web API and Cross-Origin requests are not allowed. In order to enable it you’ll need to connect to the AF Configuration database under the OSIsoft > PI Web API > [Your PI Web API Instance Name] > System Configuration.


From here you can you can add the names of the WebPages that you expect and want to have access to the PI Web API in the CorsOrigins. You should only use the explicit website name from which you expect requests to this attribute.


You can specify what HTTP methods are supported for these Cross-Origin requests as well. The default setting for this is “GET, OPTIONS”, which is to say read only access. Add the HTTP request verbs needed for your application to function properly as needed. As a note, these HTTP Verbs will be permitted for all origins listed in the CorsOrigins attribute.


Additionally, we recommend enabling support for CORS credentials. This allows cross-origin requests to include authorization headers in order to support using Kerberos and Basic authentication protocols. This is disabled by default.


For more information please see the online PI Web API Documentation for CORS.


  1. Cross-Site Request Forgery (CSRF)


Beginning in 2017, the PI Web API offers Cross-Site Request Forgery Defense. CSRF Defense is enabled by default with the PI Web API. CSRF defence protects the PI Web API server from being manipulated by other sites’ scripts loaded in a user’s web browser, possibly using the user’s cached credentials or session cookies.


The method the PI Web API uses for CSRF Defense requires that a custom HTTP request header be sent with Cross-Site Origin Requests. We recommend using the “X-Requested-With” HTTP Header because most (though not all) major JavaScript Libraries already add this header to requests they generate by default.


This type of defence relies on the same-origin policy restriction of modern web browsers that only Javascript (e.g. RESTful calls) can be used to add custom headers to requests, and this is only permitted when the requested resource is within the same origin of the origination of the request. In other words, a web browser will allow scripts running on “” to add custom headers for requests made “” because both reside within the same Domain/Origin, but not allowing customer headers when making requests to “”


By default, CORS does not allow any Cross-Origin requests that use custom HTTP Headers. By requiring a custom HTTP Header for Cross-Origin requests, the browser performs an OPTIONS preflight CORS check to the PI Web API for the request with the custom HTTP Header. This OPTIONS check allows for the PI Web API to check that the Origin of the request is a member of the allowed origins or the same origin as the PI Web API. By forcing the Pre-flight check, we require the sender to identify their true origin (since scripts can’t overwrite the origin of a request). This is important because the requester could potentially be a malicious third party site, as they maybe have the proper authorization by having stolen an end user’s cookie/authorization credentials.


If the request is from an allowed origin, then the actual request can hit the PI Web API. However, if it’s not a member of the allowed Origins the PI Web API tells the browser as such and the potentially malicious request is not executed by the browser.


  1. X-Frame Options


The PI Web API allows administrators to indicate under which circumstances a browser is able to render a page from the PI Web API in a <frame>, <iframe> or <object> tag. By default, the PI Web API will allow this for requests from the same origin. It is possible to change the configuration of the XFRAMEOPTIONS AF configuration attribute to allow for additional origins by using “ALLOW-FROM uri”, where uri is the origin that is allowed to render the page within the HTML tags.