Kerberos Delegation

Kerberos Delegation can occur between middleware and backend systems to transfer user's credential, once user's been verified, without asking the user multiple times. A typical middle-tier services are PI Web API or PI Vision. A typical backend systems include Data Archive or Asset Framework servers.

Kerberos Authentication

Kerberos authentication is one of four types of supported authentication. As a security best practice, AVEVA recommends using Kerberos Authentication within a corporate network. When working with Kerberos authentication for PI Web API, there are two authentication processes:

1. Authentication to PI Web API
2. Authentication to backend servers such as AF Server and PI Data Archive

Set Service Principal Names (SPNs)

Option 1: Using Active Directory Management Console (GUI)

1.  Open Active Directory Management Console

2. In the toolbar, select View and enable Advanced Features.

3. Find your PI/AF Server > Properties > Attribute Editor and find the setting for servicePrinipalName. If not existing, add the following values:

AFServer/machine_name
AFServer/machine_fqdn

PIServer/machine_name
PIServer/machine_fqdn

Option 2: Manually setting SPNs via Command Line

Configure SPNs for AF Server and PI Data Archive.

• AF Server SPNs are:

AFServer/machine_name
AFServer/machine_fqdn

• If the AF Server is referred by a DNS alias: AFServer/alias_name, AFServer/alias_fqdn
• If the AF Server is behind a network load balancer (Cannot connect to a PI AF server through a Network Load Balancer) : AFServer/NLB_name, AFServer/NLB_fqdn

• PI Data Archive SPNs are:

PIServer/machine_name
PIServer/machine_fqdn

Note that each service has its own account. Therefore, SPNs are returned for their respective accounts.

• If the service account is a domain account:

setspn -l <domain>\<service_account>
e.g.: setspn -l mydomain\myaccount

• If the service account is the default service account NT SERVICE:

setspn -l <machine_name>
e.g.: setspn -l mymachine

• Verify if AFServer SPNs are created or registered to the wrong account:

setspn -q AFServer/<hostname or FQDN of server>

setspn -q PIServer/<hostname or FQDN of server>

• For AF Server

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

If using an alias or a network load balancer, replace the machine name/fqdn with alias or NLB name/fqdn.

• For PI Data Archive

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

If the service is running as the default service account NT SERVICE, the SPNs are created automatically after a service restart.

 Configure service principal names (SPNs) for PI Web API.

• PI Web API SPNs are:

HTTP/machine_name
HTTP/machine_fqdn

2. To confirm SPNs are properly created for PI Web API, you can run the following command in cmd for the PI Web API service account. 

• If the service account is a domain account:

setspn -l <domain>\<service_account>
e.g.: setspn -l mydomain\myaccount

• If the service account is the default service account NT SERVICE\piwebapi:

setspn -l <machine_name>
e.g.: setspn -l mymachine

• Verify if HTTP SPNs are created or registered to the wrong account.

setspn -q HTTP/<hostname or FQDN of server>

If SPNs for the server have been registered to a different account, they will need to be deleted with 'setspn -d' command.
 

• If it is not created, a domain administrator can run the following command to create it:

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

Configure PI Web API

How to configure Kerberos Constrained Delegation for PI Web API

Configure the PI Web API service account properties in Active Directory

• The account running PI Web API must be trusted for delegation and also be able to accept protocol transition as shown below.
• The services to which the account can delegate credentials should be all backend PIServer and AFServer services. This is why those SPNs are needed.
• Enabling delegation for these accounts will elevate their privileges as shown in Enable computer and user accounts to be trusted for delegation.

1. Open "Active Directory Users and Computers"
2. Find the service account that will be delegating credentials (PI Web API user).
   • If PI Web API is running as the default service account NT SERVICE\piwebapi, use the machine account.
   • If PI Web API is running as a domain service account, use that user.
   • If PI Web API is running as a gMSA account, follow the procedure in the next section, as gMSA account will not have a Delegation tab in Active Directory Users and Computers tool.
3. Open the Properties dialog of that account.
4. Click the Delegation tab.
5. Select Trust this user for delegation to specified services only.
6. Select Use any authentication protocol to allow protocol transition.
7. Add the AFServer and PIServer SPNs that the service account will be able to delegate credentials to:
   • If your Data Archive or PI AF is running as a built-in machine account, use the machine name to find the Service Type.
   • If your Data Archive or PI AF is running as a custom service account, use that custom domain user to find the Service Type.
   • If the AF is configured behind a Network Load Balancer (NLB), add the NLB name into the delegation as well.
8. Click Apply, and OK to save the change.

Verify connections to AF Server and  PI Data Archive

• For AF Server
  1. Access AF data via PI Web API.
  2. Open PI System Explorer, navigate to File > Server Properties > Connections. Verify the PI Web API service account authentication type is Kerberos.

• For PI Data Archive
  1. Access PI Point data via PI Web API.
  2. Open PI System Management Tools, navigate to Operation > Network Manager Statistics. Verify PI Web API is connecting to PI Data Archive via PI Mapping and not PI Trust.