AppFrame

How to: Setup Windows Authentication for AppFrameR3 Build 5

To configure the enviroment to enable Windows authentication requires involvement from the administrators of the Active Directory and IIS. This document describes the steps required.

Prerequisites

The following conditions must be true in order to make Windows Authentication work

  • SQL Server must be part of Active Directory domain
  • Web Server must be part of Active Directory domain
  • If you got more then one Web Server and have split TeamDoc PIMS Site and Remoting Site on them both needs to be part of Active Directory domain

Overview of How AppFrame and Windows Authentication

AppFrame uses Kerberos tickets and delegation to authenticate clients against the web server and the sql server. This is configured according to Best Practice from Microsoft.

The delegation functionality featured here can be used through multiple levels (for example if you have a web server, connecting to an application server, connecting to an SQL Server). The delegation done by the web server is repeated at each additional layer in the chain.

In the diagram above the following sequence of events takes place:

  1. The client browser supplies a Kerberos service ticket to the web server.
  2. The web server, whic are seeing the need to open a connection to SQL Server using the end user's credentials, obtains the necessary ticket from the KDC
  3. The KDC returns a ticket if the web server is permitted to delegate
  4. The server opens the connection, sending the ticket obtained from the KDC
  5. The SQL Server permits the connection to be opened, or returns a error indicating that the user is not permitted login to SQL Server
  6. The web server returns the web page to the end user

To get this to work there are several set of actions to perform:

  1. Recommended that SQL Service run as a Domain User, but not required.
  2. Set SPN on the Domain User that SQL Server runs under or SQL Server FQDN if service is running as Local System.
  3. Web Server or Identity on Aplication Pool needs to be set up with "Trust For Delegation"
  4. Set SPN for the URL that you will be writing in your Browser agains the Web Server

Get to know the definitions of words used in a Windows Authentication environment.

SPN:

A service can use Kerberos only if that service first registers a service principal name (SPN) in Active Directory. By default, Active Directory registers the NetBIOS, or computer, name of the server. But if the SPN is different you must manually register the service. Before Kerberos can authenticate a service, the service must be registered on only one account object. If the logon account name of a service instance changes, the service must be registered under the new account. Therefore, only one application pool that has the service registered can authenticate with Kerberos.

Trusted For Delegation:

Delegation is the act of allowing a service to impersonate a user account or computer account in order to access resources throughout the network. When a service is trusted for delegation, that service can impersonate a user to use other network services.

FQDN:

Fully qualified domain name

Step By Step Guide

  1. Best practise, change the user that runs SQL Server Service to a Domain User
  2. Set SPN for the Domain User that you set for running your SQL Server Service (Port number) or Set SPN on SQL Server FQDN if service is running as Local System.(Important, "MySQLServerFQDN" in the SPN command needs to be asect the same as what you have in the connection string in AppFrame.Config, if you have written SQLPIMS without domain then the SPN needs to be without domain)
  3. Set Delegation for the Web Server. You need to Search for the Domain User that is running SQL Server Service and then Choose the MSSQLSvc Service that was made in Step 2. (Possible to also choose Trus this computer for delegation to any service). If Application Pool Identity is a domain user, Trust for Delegation needs to be set on that domain user and not the Webserver.
  4. Set SPN for the WebSite URL agains your Web Server, this step needs to done for both Remoting Site and TeamDoc PIMS Site.
  5. IIS Configuration for the site: Enable Windows Authentication,this step needs to done for both Remoting Site and TeamDoc PIMS Site.
    - "Allow anonymous access" must be disabled
    - "Winodws Authentication" must be enabled (You need to enable Basic Authenticaion (Forms) if you are using Web2/3)
  6. AppFrame Configuration. (Inside Appframe.Config) Set the IntegratedSecurity="true" and verify that the Server Tag inside your Services.xml is the same that you entered in the SQL SPN command.
  7. If Services.xml file is placed on Remoting Site and you are using Services Auto ="true" in Appframe.Config on TeamDoc PIMS Site you need to place the Services.XML file inside a Folder and Make an Application of that folder and set "Allow anonymous access" to Enable. The reason for this is that TeamDoc PIMS Site do not need to use Windows Auth to access the Services.XML
  8. Browser settings on Client PC: Make sure the option "Enable Windows Integrated Security" is enabled or Include the WebSite URL in Local intranet.
  9. If your are using IIS 7.5 and don't want to set the user with password in Web.Config but still want to use Winows Authentication, you can set the Application Pool ID as a Domain User

Testing

Dowload Kerberos Test Utility

Copy this to a folder inside your Web Site Folder on Web Server.

Go to IIS and Make an Application of the Folder.

If this is a TeamDoc PIMS Site you may need to add some of the Dll's from BIN folder inside Web Site Folder.

Go to your Browser and try to open the Kerberos site. URL Example: http://MyWebSite/Kerberos
Use this site to Troubleshoot issues with Windows Authentication.

Helpful links:

How to troubleshoot the "Cannot generate SSPI context" error message
Brian Murphy Booth