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.
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:
You can also Deny this user from logging in a computer using a Local Security Policy:
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).
Grant Read access to PIDBSEC, PIMAPPING, PIPOINT and PIUSER database tables for this PI Identity:
PI AF Server
PI System Explorer > Server Properties > Mappings > Create a mapping to an identity with Read access to the desired databases
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:
5. Create SPNs
Create one SPN for the netbios name and one for the fully-qualified domain name of the PI Vision application server:
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:
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):
But if AF Server is running with System or any other non-windows user account, like Network Service you need to add AF Computer:
Then choose “afserver” service type.
Repeat the process for the PI Data Archive node:
Chose PIServer service type:
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:
Set useAppPoolCredentials to True (located at system.webServer/security/authentication/windowsAuthentication) if PI Vision is running under a domain service account, not Network Service.
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.
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).
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.
If SQL Server is on another node:
Copy the “SQL” folder from “Program Files/PIPC/PIVision/Admin/SQL” to SQL Server and run:
◦ 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:
ALTER USER "DVService" with
LOGIN="<domain>\<Application Pool ID>"
ALTER USER "<domain>\<Application Pool ID>" with
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
Make sure to select “Require SSL” on SSL Settings:
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.
7. Checking the certificate in browser
The URL for PI Vision must be used accordingly with its certificate.
Otherwise, a PI Web API Error will show up: "PI Web API Error: The PI Web API server could not be reached".
That should be it!
By Wagner Lima and Eduardo Miller