Direkt zum Inhalt
Software AthleteSoftware Athlete
How to configure Kerberos for PI Web API

How to configure Kerberos for PI Web API

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

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

Configure SPNs for AF Server and PI Data Archive.
  • AF Server SPNs are:
AFServer/machine_name
AFServer/machine_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.

To confirm SPNs are properly created, you can run the following command in cmd for both PI Data Archive and AF Server service 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>
If using an alias or a network load balancer, replace the machine name/fqdn with alias or NLB name/fqdn.
If SPNs for the server have been registered to a different account, they will need to be deleted with 'setspn -d' command.
  • Verify if PIServer SPNs are created or registered to the wrong account:
setspn -q PIServer/<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 any of those is not created, a domain administrator can run the following commands to create them.
  • 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

If you have multiple domains, please review Kerberos Delegation across multiple domains before you continue reading this article.
 

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.
 
 


Configure Kerberos delegation for PI Web API's group Managed Service Account (gMSA)

 

Refer to Microsoft article on Configuring Kerberos delegation for group Managed Service Accounts.
For Managed Service Accounts, the Delegation tab doesn't appear.
To configure delegation for these special accounts, you need to set the following two attributes on these accounts:

  • userAccountControl defines the type of delegation
  • msDS-AllowedToDelegateTo defines the list where the backend resource SPNs for delegation will be added
These attributes can be set via PowerShell or manually updated 

Set userAccountControl property
Using the powershell commands from the section
Kerberos Constrained Delegation with Protocol Transition/Trust this computer for delegation to specified services only (Use Any Authentication Protocol) section of the article
 
In Powershell,
  • Set-ADAccountControl -Identity <piwebapigMSA$>  -TrustedForDelegation $false  -TrustedToAuthForDelegation $true
 
Set msDS-AllowedToDelegateTo attribute
 
Need to add the list  Backend Service SPNs in msDS-AllowedToDelegateTo attribute of the frontEndgMSA account
This can be done manually 
  1. In the Active Directory, click on View > Advanced Features
  2. Go to the PI Web API's's managed service account and Right click > Properties > Attribute Editor > msDS-AllowedToDelegateTo.
  3. Add Value and type in the respective SPN for the backend resource server:
<service class>/<machine hostname>
<service class>/<machine FQDN>
 
  •  For example, the SPNs for AF SERVER backend resource server and PI DataArchive backend resource server is as below.

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

 

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.
 
 
Hinterlasse einen Kommentar

Deine Email-Adresse wird nicht veröffentlicht..

Warenkorb 0

Dein Warenkorb ist leer

Beginn mit dem Einkauf