Versions Compared

Old Version 1

changes.mady.by.user Former user

Saved on

compared with

New Version 2

changes.mady.by.user Roar Hansen (Deactivated)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Background

When choosing to enable integrated security, referred to as "Single Sign-on" (SSO), ViaWorks 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 ViaWorks 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 ViaWorks 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 ViaWorks 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:

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 ViaWorks Locator server.
  • Admin access to the ViaWorks Locator  server
  • .NET 3.5 or later on the ViaWorks Locator server
  • ViaWorks Locator server must be in the same domain as the Managed Service Account
New-ManagedServiceAccount.ps1 

NOTE: Only run this script if you want to use a Managed Service Account. This script is not needed if using a domain user account.
 
This script must be executed on the ViaWorks Locator server while logged on with a user account with domain administrator privileges. PowerShell should be elevated (run as administrator). 

Usage: New-ManagedServiceAccount.ps1 [[-ServiceName] <string>] [[-ComputerName] <string>]

Parameters:
  • 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
The script performs the following actions:
  • Adds the NET-Framework-Core and RSAT-AD-Tools features to the ViaWorks 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 ViaWorks Locator server
  • Creates the Service Principal Name necessary for Kerberos authentication

Configure-ViaWorksSSO.ps1

This script must be executed on the ViaWorks 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 ViaWorks.

NOTE: This script must be rerun after updating ViaWorks. 

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

Parameters:

  • AccountName <String>
    • The sAMAccountName of the existing domain account that will be used for ViaWorks 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 ViaWorks 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 ViaWorks Locator .
  • To switch back to NTLM authentication, run the Configure-ViaWorksSSO.ps1 script with the -NTLM parameter
    • Configure-ViaWorksSSO.ps1 -NTLM

Alternatively, upgrading ViaWorks 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