Configure Kerberos Authentication & Delegation for PI Vision & PI Web API

Kerberos Delegation Overview

Kerberos Delegation allows middleware services to seamlessly pass an authenticated user's credentials to backend systems. This process ensures that the user is verified only once and does not need to authenticate multiple times. Typical middle-tier services include AVEVA PI Web API and PI Vision, while typical backend systems include PI Data Archive and PI Asset Framework (AF) servers.

Kerberos Authentication Overview

Kerberos is one of the supported authentication methods for AVEVA products. As a security best practice, AVEVA recommends using Kerberos Authentication within a corporate network. When working with Kerberos authentication for PI Web API and PI Vision, two distinct authentication processes (or "hops") occur:

1. Authentication from the client to the middle-tier service (PI Web API or PI Vision).
2. Authentication from the middle-tier service to the backend servers (PI AF Server and PI Data Archive).

Note on Prerequisites: For Kerberos to function correctly, ensure that the clocks on the client, middleware, and backend servers are synchronized (typically within a 5-minute skew) and that DNS A-records (not CNAMEs) are used for server resolution.

1. Configure PI Vision in IIS

First, configure the Internet Information Services (IIS) application pool to run under a custom domain service account.

1. Open Internet Information Services (IIS) Manager and click on Application Pools.
2. Select the PI Vision application pool and change its Identity to run as your dedicated domain user account.

Next, configure the authentication methods for the PI Vision website:

1. Select the PIVision web site in IIS and double-click Authentication.
2. Enable Windows Authentication. You may optionally enable Basic Authentication as a fallback.
3. Right-click Windows Authentication and select Advanced Settings. Verify that Negotiate and NTLM (strictly in that order) are available.
4. Important: Because you are using a custom domain account, ensure that Enable Kernel-mode authentication is unchecked (disabled).

Finally, set the application to use the application pool credentials:

1. Go back to the PIVision site home page in IIS and double-click Configuration Editor.
2. Navigate to the section: system.webServer/security/authentication/windowsAuthentication.
3. Set useAppPoolCredentials to True.
4. Click Apply and restart IIS.

2. Configure the PI Web API Service Account

If PI Web API is running on the same server, or using the same domain account, update its service to use the matching user credentials.

1. Open the Windows Services console.
2. Locate the PI Web API Service.
3. Right-click the service, select Properties, and go to the Log On tab.
4. Enter the credentials for the custom domain user account and restart the service.

3. Set Service Principal Names (SPNs)

To use Kerberos, Service Principal Names (SPNs) must be registered for the service account hosting PI Vision and PI Web API.

1. Open Active Directory Users and Computers (ensure Advanced Features are enabled under the View menu).
2. Locate the service account on which you want to enable delegation.
3. Right-click the user, go to Properties > Attribute Editor, locate the servicePrincipalName attribute, and add the following two entries (replace placeholders with your actual server names):
   • HTTP/<machine_name>
   • HTTP/<machine_fqdn>

Alternatively, you can open a command prompt as an Administrator and use the setspn tool to register the SPNs:

setspn -s HTTP/<machine_name> <domain>\<service_account>
setspn -s HTTP/<machine_fqdn> <domain>\<service_account>

4. Configure Active Directory Delegation

After setting the SPNs, you must configure the service account to delegate credentials to the backend servers.

1. In Active Directory Users and Computers, open the Properties of your service account again.
2. Navigate to the Delegation tab.
3. Select Trust this user for delegation to specified services only (Constrained Delegation) and choose Use any authentication protocol (Protocol Transition).
4. Click Add..., then Users or Computers..., and search for the machine account or custom service account running your PI Data Archive and PI AF Server.
5. Select the AFServer and PIServer service types from the available services list, and click OK.
6. Click OK to apply and save the delegation settings.

5. Configure Authentication Methods in PI Web API

Ensure that the PI Web API Configuration explicitly allows Kerberos authentication.

1. Open PI System Explorer as an Administrator.
2. Select the Configuration database that hosts the PI Web API properties.
3. Navigate to the following path:
   \\<AFServer>\Configuration\OSIsoft\PI Web API\<PI Web API Instance Name>\System Configuration
4. Locate the AuthenticationMethods attribute. Make sure Kerberos is listed in the array of values and that the attribute is marked as a Configuration Item.

Alternatively, you can run the PI Web API Admin Utility and check the authentication methods in the graphical interface:

6. Client Configuration: Local Intranet Zones

For Kerberos Authentication to seamlessly authenticate users without prompting for credentials, the domains for PI Vision and PI Web API must be included in the client machine's Local Intranet Security Zone.

1. On the client machine, open Internet Options.
2. Go to the Security tab, select Local intranet, and click Sites > Advanced.
3. Add the website URLs used for PI Vision and PI Web API.

7. Alternative: Configure Delegation for a Group Managed Service Account (gMSA)

If you are using a Group Managed Service Account (gMSA) instead of a standard domain account, the Delegation tab will not appear in Active Directory Users and Computers. Refer to the Microsoft article on Configuring Kerberos delegation for group Managed Service Accounts.

To configure delegation for these special accounts, you must manually set the following two attributes:

• userAccountControl: Defines the type of delegation.
• msDS-AllowedToDelegateTo: Defines the list of backend resource SPNs to which credentials can be delegated.

Update userAccountControl Property

To enable Kerberos Constrained Delegation with Protocol Transition, run the following PowerShell command as a domain administrator (replace <piwebapigMSA$> with your actual gMSA name):

Set-ADAccountControl -Identity <piwebapigMSA$> -TrustedForDelegation $false -TrustedToAuthForDelegation $true

Update msDS-AllowedToDelegateTo Attribute

You must manually add the backend server SPNs to the front-end gMSA account.

1. In Active Directory Users and Computers, click View > Advanced Features.
2. Locate your PI Web API's managed service account, right-click it, and select Properties.
3. Go to the Attribute Editor tab and find the msDS-AllowedToDelegateTo attribute.
4. Click Edit and add the respective SPNs for your backend resources:

For example, the SPNs for an AF Server and a PI Data Archive backend look like this:

• AFSERVER/<AF-hostname>
• AFSERVER/<AF-FQDN>
• PISERVER/<DA-hostname>
• PISERVER/<DA-FQDN>

8. Verify Connections to AF Server and PI Data Archive

Finally, verify that your middle-tier services are connecting to the backend systems using Kerberos.

Verify PI AF Server Connection

1. Access AF data via PI Web API or PI Vision to establish a connection.
2. Open PI System Explorer on the AF Server and navigate to File > Server Properties > Connections.
3. Verify that the incoming connection belonging to the PI Web API service account shows Kerberos as the Authentication type.

Verify PI Data Archive Connection

1. Access PI Point data via PI Web API or PI Vision.
2. Open PI System Management Tools (SMT) and navigate to Operation > Network Manager Statistics.
3. Verify that the service account is connecting to the PI Data Archive via PI Mapping (not PI Trust) and that the authentication protocol reflects a Kerberos connection.