Configuring Kerberos Authentication

Background

When choosing to enable integrated security, referred to as "Single Sign-on" (SSO), Locator uses, as the default, the NTLM authentication protocol.  However, you can also enable SSO using the Kerberos authentication protocol.  This document is a guideline for configuring SSO using the Kerberos authentication protocol, instead of the default NTLM authentication protocol.  The target audience is Locator Administrators and developers.

Kerberos Single Sign-on (SSO) requires that a domain user account or Managed Service Account be used as the identity of the ViaWorksAppPool application pool. The ViaWorksAppPool is the application pool used by all of the Locator IIS applications.

Using a Managed Service Account with the ViaWorksAppPool is preferred over a normal domain user account because a Managed Service Account provides several security advantages over domain user accounts. Managed Service Accounts passwords are managed automatically by the computer account they are associated with. When the Active Directory computer account object password is updated, the associated Managed Service Account object passwords are also updated. Managed Service Accounts are not user objects in Active Directory and as such cannot log on interactively. In order to use a Managed Service Account the Locator server, Active Directory forest and domain must be Windows Server 2008 R2 or later. 

For more information about Managed Service Accounts:  http://technet.microsoft.com/en-us/library/dd548356.aspx

VirtualWorks has developed two PowerShell scripts that automate most of the setup and configuration necessary to enable SSO using a Managed Service Account:

• New-ManagedServiceAccount.ps1 – This script creates a Managed Service Account.
• Configure-ViaWorksSSO.ps1 – This script installs the Managed Service Account on the local Locator server and reconfigures IIS to make use of the Managed Service Account. 

Requirements

• Active Directory Domain and Forest level at Windows Server 2008 R2 or later
• A Domain Admin account is required to create the Managed Service Account and associate it with the Locator server.
• Admin access to the Locator  server
• .NET 3.5 or later on the Locator server
• Locator server must be in the same domain as the Managed Service Account

• ServiceName <string> 
  • The name of the new managed service account. If not specified, the default is "msa%ComputerName%" for the local computer
• ComputerName <string>
  • The name of the computer that the managed service account will be associated with. If not specified, the local computer name will be used

• Adds the NET-Framework-Core and RSAT-AD-Tools features to the Locator server if they are not already installed
• Creates a Managed Service Account in Active Directory. If the account name is not specified  with the -ServiceName parameter, then the Managed Service Account name defaults to “msa” + the %ComputerName% from the local system environment
• Assigns the Managed Service Account to the local Locator server
• Creates the Service Principal Name necessary for Kerberos authentication

Configure-ViaWorksSSO.ps1

This script must be executed on the Locator server while logged on with a user account with local administrator privileges. PowerShell should be elevated (run as administrator). In order for the script to perform the necessary updates, NTrights.exe must be in the same directory as the script. Ensure that the "Enable SSO" setting is checked in Locator.

NOTE: This script must be rerun after updating Locator. 

Usage: Configure-ViaWorksSSO.ps1 [[-AccountName] <string>] [-DomUser] [-NTLM]

Parameters:

• AccountName <String>
  • The sAMAccountName of the existing domain account that will be used for Locator service and application pool. Defaults to msa%COMPUTERNAME%
• DomUser <switch>
  • Enable this switch to force the script to use a normal domain user account as opposed to a Managed Service Account. An AccountName must be specified.
• NTLM  <switch>
  • If specified, the system will be reverted to NTLM authentication

The script performs the following actions:

• Adds the .NET-Framework-Core and RSAT-AD-Tools features to the Locator server if they are not already installed
• If the account name is not specified with the -AccountName parameter, then the Managed Service Account with name “msa%ComputerName%" will be used (created by the New-ManagedServiceAccount.ps1 script)
• Changes the “Identity” of the ViaWorksAppPool in IIS to the Managed Service Account or specified domain user account.
• Changes the permissions on the ViaWorks “InstallDir” and “DataDir” such that the “IIS APPPOOL\ViaWorksAppPool” security principal has full control to each directory and its children.
• Grants the Managed Service Account or domain user account the "Log-on as a service" right
• Sets the “useKernelMode” and “useAppPoolCredentials” attributes to “True” for the RestService application and in the RestService web.config
• Updates the RestService web.config to use "Negotiate"

NTLM (Default)
   <location path="2/api/login/windows/session">
    <system.webServer>
     <security>
      <authentication>
       <windowsAuthentication enabled="true">
        <providers>
         <clear />
         <add value="NTLM" />
       </providers>
      </windowsAuthentication>
     </authentication>
    </security>
   </system.webServer>
  </location>

Kerberos (After)
 <location path="2/api/login/windows/session">
   <system.webServer>
    <security>
     <authentication>
      <windowsAuthentication enabled="true" useKernelMode="true" useAppPoolCredentials="true">
       <providers>
        <clear />
        <add value="Negotiate" />
        <add value="NTLM" />
       </providers>
      </windowsAuthentication>
     </authentication>
    </security>
   </system.webServer>
</location>
Rollback

The original ViaWorksServiceUser account and permissions are untouched by the script, therefore, to revert changes made by the script:

• To disable Kerberos SSO, uncheck the "Use Single Sign On" setting in Locator .
• To switch back to NTLM authentication, run the Configure-ViaWorksSSO.ps1 script with the -NTLM parameter
  • Configure-ViaWorksSSO.ps1 -NTLM

Alternatively, upgrading Locator will revert changes made to the service account and the IIS applications.

Additional References

http://technet.microsoft.com/en-us/library/dd548356(v=ws.10).aspx

http://blogs.technet.com/b/askds/archive/2009/09/10/managed-service-accounts-understanding-implementing-best-practices-and-troubleshooting.aspx

http://blogs.msdn.com/b/autz_auth_stuff/archive/2011/05/06/kernel-mode-authentication.aspx

http://blogs.msdn.com/b/distributedworld/archive/2012/04/24/troubleshoot-kerberos-in-wcf.aspx