(December 2016) This article mentions PI trusts, now superseded by more secure forms of authentication. AL00309 discusses the move from PI trusts to Windows Integrated Security (WIS) for PI API.
OSIsoft: Configure Minimum Permissions for PI Interfaces and Buffering [for 3.4.380 & later]
In order for an interface to be able to write data to the PI Server, it must have the proper permissions. Because the interface application cannot respond to a login prompt, we use the PI Trust table on the PI Server to map an interface connection to a specific user. The following guidelines for creating trusts for your interfaces are discussed in this article:
OSIsoft strongly recommends using Windows authentication instead of PI Trusts. AL00309
discusses the migration from PI Trusts to Windows authentication with PI API applications, such as PI Interfaces.
A Simple Trust Based on IP Address/Netmask Only
If you have static IP addresses, one of the simplest trusts you can make to work for any interface connection is one based upon IP address and netmask of the interface machine. If your interface node has multiple NICs that would be able to communicate with the PI Server on the network, you must set up a trust for each IP address, even if you just see the connection with one. To see all IP addresses from a given computer, type ipconfig –all
at a command prompt.
The trust must be mapped to a PI Identity that has write access to the data security of the tags associated with the interface on the PI Server. Then using this type of trust, the PI Server will allow any
application from that IP address to connect to the PI Server as the specified PI Identity, including interface tools, PI Buffer Server, apisnap.exe, and PI System Management Tools, just to name a few. If buffering is enabled, the PI Buffer Subsystem or PI Buffer Server requires write access on the tags' Data Security Access Control List (ACL). In the case of using buffering, the interface application needs read access to the Point Database and read access to the Point Security ACL for each tag to which it writes. See the PI Server System Management Tools User Guide section titled, "Updated access permission model
The only information required to build this trust is the IP address assigned to the interface machine. If the interface is running on the PI Server, a trust is not required as the PI Server installs a trust for itself by default. To get the IP address of the interface node, go to the interface machine and run the ipconfig
command in a command prompt window and press Enter
. Then build the trust on the PI Server based on the IP address of the interface machine and a netmask value of 255. 255. 255. 255
. In the event that Network Address Translation takes place between the interface and PI Server, the translated address will need to be known. Please see KB00864 - How to determine the credentials for a PI Trust
Use the PI System Manager Tools (PI SMT) Trust Editor plug-in to easily build a trust. Download the PI SMT Install kit
. An example of IP address/netmask only-based trust would be configured as follows in the Mappings & Trusts
plug-in within PI System Management Tools:
Cons of IP Address trusts
: IP Addresses are not as user-friendly as hostnames, can be more easily spoofed, and are more likely to change over time. If you need to move or replace your interface box, it will be easier if you are using hostname as a trust credential, rather than IP Address. The hostname can only be used if the IP address of the interface machine can be resolved by Reverse Name Lookup from the PI Server. If you have dynamically-assigned IP Addresses, then do not use IP Address in your trust table.
More Complex PI Trusts for Interfaces
It is recommend that you create more robust, secure trusts than ones simply based on an IP address. Below are guidelines for creating more complex trusts, some of which provide additional reliability and more security. Some of these trusts must take into consideration the type of connection that the application is making, namely a PI API or PI SDK connection, or both. Please refer to the documentation for your PI Interface to determine whether the interface uses the PI API and/or PI SDK to connect to the PI Server.
Interface Connection Types
There are two different types of connections that can be made to the PI Server: PI API and PI SDK. At this time, most OSIsoft interfaces and the PI Buffer Server (BufServ.exe) use the PI API to connect to the PI Server. Other interfaces such as the Batch Framework interfaces will utilize the PI SDK to connect and write data, while some API based interfaces will still support using the PI SDK for specific use cases, such as writing PI Annotations. Please refer to interface specific documentation for more information on whether or not this is supported for a given interface. The PI System Management Tools utility uses the PI SDK to connect to the PI Server. Distinguishing the type of connection may be important when creating trusts, especially if using hostnames or application names as part of the trust (see KB00864 - How to determine the credentials for a PI Trust
Trusts based on IP Address/Netmask and Hostname
Often customers set up two trusts on an interface machine:
- One using the IP address/netmask
- One based on hostname
This ensures that the interface will continue to send data if one trust fails, for example, if the IP address changes. Note that the hostname may be different depending on whether the interface uses the PI API or the PI SDK to connect. See KB00864 - How to determine the credentials for a PI Trust
for details on finding the IP address and hostname credentials.
Until PI SDK 126.96.36.1993 was released, you often had to set up more than one trust when using hostname in your trust credentials because the PI API and PI SDK used different credentials when connecting to the PI Server. With PI SDK 188.8.131.523 and later, this is no longer the case. You can use the FQDN in your trust for both PI API and PI SDK connections.
All versions of the PI API use the fully qualified host name. An example of a fully qualified host name is "apollo.osisoft.com." The fully qualified host name for a PI API Connection is determined by the following:
- Local DNS cache
- Local hosts file
- Reverse-name lookup on the incoming IP address using DNS
The PI SDK 1.3.3 and earlier will present to the server what is referred to as "simple hostname" or machine name. An example of this would be "apollo." PI SDK 184.108.40.2063 and later presents both the simple and FQDN to the PI Server.
More Specific Trusts – Multiple Credentials
You can limit the scope of a trust by adding additional credentials to the trust. For example, adding application name as a credential will only allow an application with that name to be trusted. PI API and PI SDK connections pass application names differently as well.
The PI API and PI SDK transmit application names (AppName) differently and this must be taken into account when trusts are created. With an application that uses the PI SDK for its connection, the entire application name is used. Interfaces using the 64-bit PI API may use the Long Process Name. With PI API-based applications, only the first four letters of the name and the capital letter "E" are presented by default. See KB00505 - How to recognize connecting application names in the PI Network Manager Statistics table and message logs
for information on how the AppNames are associated with the applications.
At this point in time, there are no OSIsoft interfaces that use only the PI SDK for their connections (there are some that use both); however, you may have PI SDK-based applications running on the interface node, such as PI SMT, PI ProcessBook, or PI DataLink, for which you will want to create a trust based on the AppName.
The use of Windows Integrated Security is recommended for PI SDK applications. Please see the section titled, "Why use Windows Integrated Security?
As an example, let’s look at a fictional interface called the Automation interface. If it were PI API-based, it might appear to the server as "AutoE." If it were PI SDK-based, it might appear as "automation.exe." The only way to know for certain is to follow KB00864 - How to determine the credentials for a PI Trust
If you are using buffering on the interface node, it must have write access on the tags' Data Security ACL. If your PI Trust is based on hostname or IP address, then the PI Buffer Subsystem or PI Buffer Server will connect, depending on which method you are using. However, if your trusts are based on application, you must create an additional trust for the buffering application. If using the PI Buffer Subsystem, "pibufss.exe" is the PIBufSS application name; if using the PI Buffer Server, "APIBE" is the BufServ application name.
Least Privilege – Specific Users
If you wish to control access to tags, you can configure the Point Security and Data Security of tags by selecting the level of access for individual PI Identities. Please see the section titled, "About access permissions on the PI Server
," in the PI Server 2012 Configuring PI Server Security Guide.
Please also see the following resources: