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

How to configure Kerberos Authentication for PI Web API

1. 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>

3. Open PI System Explorer, select the configuration database that hosts PI Web API properties, navigate to \\<AFServer>\Configuration\OSIsoft\PI Web API\<PI Web API Instance>\System Configuration and make sure Kerberos is listed in AuthenticationMethods attribute and it is marked as Configuration Item.

How to configure Kerberos Authentication for backend servers

• 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.

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.
 

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.