Use Case

According to PI Vision 3.x Installation guide, some features require Kerberos Constrained Delegation.

 

Kerberos constrained delegation must be configured between the PI Vision application server and the PI AF server, or Basic Authentication must be configured for the PI Vision web application for:

  • Acknowledging and annotating events
  • Event search criteria
  • Collection search criteria
  • Asset Comparison Table search criteria

In addition to those, the following prerequisites must be met to enable the XY Plot and the Events Table features:

  • Constrained delegation must be enabled between the PI Vision application servers, PI Data Archive and PI AF servers.
  • PI Vision and PI Web API must both have a third-party certificate or a domain certificate.

If PI Vision and PI Web API are configured to run on the same port, the same certificate can be used.

The following configuration is the one that works on most scenarios.

It uses a PI Vision service account and Kerberos Constrained delegation.

Configuration

What to do before running the PI Vision installation kit?

1. Create the PI Vision service account (domain account)

It can be created as the following example (Domain\piwebapi).

Make sure to set both options bellow:

 

1.png

 

You can also Deny this user from logging in a computer using a Local Security Policy:

 

2.png

2. Set permissions for this account

PI Data Archive

Mapping from this user to an identity that has read access for all PI Points that can be accessed by PI Vision (Data Security and Point Security).

 

3.png

 

Grant Read access to PIDBSEC, PIMAPPING, PIPOINT and PIUSER database tables for this PI Identity:

 

4.png

 

PI AF Server

PI System Explorer > Server Properties > Mappings > Create a mapping to an identity with Read access to the desired databases

 

5.png

 

In general this is not required because by default there is an “Everyone” identity that will map any domain authenticated user to World mapping.

 

If you don’t want to map to World Identity you should configure the following permissions for the AF Identity:

- Read access on each AF element, table, and event frame that you want to access through PI Vision

- Read access to AF database

For more information please consult “Grant the PI AF identity the required access permissions” session from PI Vision 2017 Installation and Administration Guide.

 

PI ProcessBook folder

Read access on folders that should be configured for import of PI ProcessBook displays.

Create a shared folder and assign the account running the PI Web API service to the folder with read permissions.

 

3. Enable server manager roles and features

You can do this by running the installation kit.

4. Make sure all parties have less than 5 minutes clock drift

Kerberos is very time sensitive and this is necessary for it to function correctly.

 

Use the following command simultaneously to check the clock drift between PI System nodes:

 

1

2

cd /d %pihome%\adm   or   cd /d %piserver%\adm

pidiag -tz *


5. Create SPNs

Create one SPN for the netbios name and one for the fully-qualified domain name of the PI Vision application server:

 

1

2

setspn -S HTTP/netbios-server-name domain\service-account

setspn -S HTTP/fully-qualified-DNS-name domain\service-account

 

For example:

 

1

2

setspn -S HTTP/IIS1 DOMAIN\piwebapi

setspn -S HTTP/IIS1.int DOMAIN\piwebapi

 

And also SPNs for AF Server service account as in KB00599 - Configuring Delegation for PI AF.


Be careful when using ALIAS: its TYPE determines the proper target host to use on SPN, please consult KB01574 - Configuring Kerberos for DNS Aliases (ANAME and CNAME).

6. Configure Kerberos Constrained Delegation

Go to AD Users and Computers (dsa.msc) > find the PI Vision service account > Properties > Delegation tab:

 

7.png

 

As you can see you need afserver “Service Type”.

If AF Server service is running under a Windows user you will need to add this user (instead of AF Computer):

 

8.png

 

But if AF Server is running with System or any other non-windows user account, like Network Service you need to add AF Computer:

 

9.png

 

Then choose “afserver” service type.

 

10.png

 

Repeat the process for the PI Data Archive node:

 

11.png

 

Chose PIServer service type:

 

12.png

 

If SQL Server is on another machine add the service MSSQLSvc on SQL Server computer. If it is on the same node as PI Vision this is not necessary.

Selecting Use any authentication protocol allows for a protocol transition. This allows PI Vision to authenticate users with NTLM (if necessary) and still be able to use Kerberos delegation to the services specified.

Unconstrained Delegation is not recommended!
Configuring unconstrained delegation for an account means you are granting that account permission to delegate to any service, provided all other steps necessary to initiate delegation are met. This option is the least secure from an IT security standpoint and therefore not recommended.
Please refer to KB01222 - Types of Kerberos Delegation.

7. Enable Kerberos authentication on client browsers

KB01223 - Kerberos and Internet Browsers

(Optional) Create a IIS Web Site only for hosting PI Vision:

Normally you could create a folder under “C:\inetpub\” called PIVision as a Physical Path

 

(Optional) Configure a custom certificate:

Generate or use a custom certificate that will be trusted by clients nodes.

 

What to do during and after running the PI Vision installation kit?

 

1. Set PI Vision service account for:

  • PI Web API: during installation
  • PI Web API Crawler: during installation
  • PIVisionServiceAppPool: after installation on IIS Manager > Application Pools
  • PIVisionAdminAppPool: after installation on IIS Manager > Application Pools

 

2. Set “useAppPoolCredentials”

Go to Configuration Editor on PIVision web application:

 

13.png

 

Set useAppPoolCredentials to True (located at system.webServer/security/authentication/windowsAuthentication) if PI Vision is running under a domain service account, not Network Service.

 

14.png

 

This ensures that the password hash of the Application Pool account is used to decrypt incoming Kerberos tickets, allowing Kerberos Authentication to work properly.

Kernel Mode should be left "On" by default as it is Microsoft's IIS.net documentation
recommendation.

 

3. Set the Providers

By default it uses Negotiate and NTLM, it will also work, and it is the recommended option!

However if Kerberos fails, it will transition to NTLM unnoticed. If this transition it is not desired you can set Providers to "Negotiate:Kerberos" only.

 

15.png

4. Create PI Vision database on SQL Server

The user that will create PI Vision database should have the following permissions on SQL Server:

◦ The db_creator server role

◦ ALTER ANY LOGIN permission (meaning you have been granted this permission by use of the statement GRANT ALTER ANY LOGIN TO "domain\account" or you are a member of the securityadmin server role).

 

16.png

 

If SQL Server is on the same node as PI Vision:

Make sure that the logged user on PI Vision admin page has the previous permissions

And on SQL Server the “Allow Triggers to Fire Others” is set to True.

 

17.png

If SQL Server is on another node:

Copy the “SQL” folder from “Program Files/PIPC/PIVision/Admin/SQL” to SQL Server and run:

1

Go.bat DBServer DBName PIVisionService

DBServer is the name of the SQL server
DBName is the name of the PI Vision database
PIVisionService is the name of the PI Vision service account

If the PI Vision Application Pool ID is changed after the PI Vision database has been created, then you need to modify the account used to access the PI Vision database. Run the following SQL commands:

 

1

2

3

4

ALTER USER "DVService" with

LOGIN="<domain>\<Application Pool ID>"

ALTER USER "<domain>\<Application Pool ID>" with

NAME="DVService"

5. PI Data Archive server authentication on mobile devices

You may need to use Basic authentication with SSL encryption for mobile device users.

On IIS go to PIVision web application > Authentication

 

Enable Basic Authentication

 

18.png

 

Make sure to select “Require SSL” on SSL Settings:

 

19.png


6. Checking CorsOrigins value

If you upgraded from previous PI Vision versions check if your CorsOrigins Values does not have a “<null>” in front of the URL value at the AF Configuration Database (OSIsoft\PI Web API\PI Vision Server Name\System Configuration element).

The URLs with PI Vision server hostname and domain should be listed, not just the asterisk "*". Also if a custom certificate for an Alias is used, the referenced URL should be listed here.

 

20.png

7. Checking the certificate in browser

The URL for PI Vision must be used accordingly with its certificate.

 

21.png

 

Otherwise, a PI Web API Error will show up: "PI Web API Error: The PI Web API server could not be reached".

 

22.png

 

That should be it!

 

 

By Wagner Lima and Eduardo Miller