DelegConfig - A Tool To help resolve Kerberos authentication and delegation issues

Overview

I wanted to create this blog to address one of the IIS Support teams top support issues.   The issue is with allowing the identity of the user logged into a client machine, to pass through the IIS Server, and onto a back end server.  The process of the identity moving from the client machine, to the IIS Machine, and then IIS passing these credentials to a back end server is sometimes referred to as Kerberos Delegation.  What follows in this post will contain information on the most common symptoms, root causes, and a tool to help web administrators make sense of it all.

The Reason to Delegate 

Organizations may want to use Windows Credentials to control access to certain resource on their intranet.   To make things as simple as possible, the following diagram illustrates this.

 

 

In this scenario the user that logs onto the client machine accesses a back end server as itself.   Unfortunately, setting up your machines to do this is not as easy as drawing the picture.  Next I will outline some of the most common symptoms, and root causes for delegation failure. 

Common Symptoms

There are many symptoms that would indicate the environment is not set up correctly to delegate credentials from the client to the back-end server.  Some of the most common are as follows:

  • Users are prompted for credentials on the client machine.
  • 401.X Errors returned to the browser
  • A user can browse to the IIS Content from the IIS Server, but not from the client machine.
  • Access Denied is returned from a custom application.

Common Root Causes

  • The same SPN Is registered for multiple accounts in the domain. This is known as a duplicate SPN issue.
  • The account the SPN is registered for is not trusted for delegation in Active Directory.
  • The Web server is configured to use NTLM authentication and not Negotiate.
  • The web browser was not able to get a Kerberos ticket from Active Directory, and it defaults back to NTLM Credentials.
  • An SPN Is not registered for the back end server, or there is more than one SPN registered for the back end server.
  • File ACLs or other permissions are not configured correctly on the back end.

The Tool to Make Sense of it All

Brian Booth, a Support Escalation Engineer for IIS at Microsoft, created an ASP.NET Application that will run some key checks on the client, server, and back end server to identify problem areas for kerberos delegation.  The following link will allow you to download the ASP.NET application that helps identify which common symptoms and Root causes you may be running into when attempting to configure an IIS Server to delegate credentials from the client to a back end server.

http://www.iis.net/downloads/default.aspx?tabid=34&g=6&i=1434

 

Setting up DelegConfig

Extract the files to a local directory on the IIS Server the client machine connects to.  Make sure the Everyone Account has access to this directory and ASP.NET  is set up correctly on the machine.  I am using the Everyone account in order to make this as simple as possible.  For more information on common problems with using this ASP.NET application, please read the readme.txt that extracts with the other files.  After extracting the files follow the 5 steps below.

  1. Open the IIS MMC and identify which application you want to delegate the client's identity
  2. Identify which application pool it is running in
  3. Create a new Application in the same web site as the real application, and configure it to run with the same version of ASP.NET, and in the same application pool
  4. Configure the new application to point to the directory that contains the files that were extracted
  5. Configure the new application for Windows Authentication only

Using the Tool

Now that the tool is set up, log on to the client machine as the domain user you are trying to delegate.  Browse to the Default.aspx page in the new web application that was created .  You should get a result page similar to the one below.  If you do not, first try browsing to the page from the IIS Server, making sure to use the machine name and not http://localhost.  Also, please see the readme.txt file that accompanies the tool for known issues.

When you are able to successfully browse to the page you will see output like the following. In my case, I have browsed locally on the IIS Machine, because when browsing from the client I kept getting prompted for credentials, and eventually it responded with a 401.

Turning Red to Green

The explanation in the detailed output has most of the information needed to resolve the issues.  I will go through each check box below with information on how to turn the Red 'x' into a Green check.

Authenticated User

The Authenticated-User Section explains who connected to the IIS Server, and whether it used NTLM or Kerberos credentials.  In the above case we are connected to the IIS Server using the negotiate header, but with NTLM Credentials.   This means that IE was not able to get a Kerberos ticket to connect to the IIS Server.  You can read the explanation for even more information.  Since I made the HTTP request from the IIS Server, it will always use NTLM, so in this case we can ignore this.  However, when you browse from the client machine to the IIS Server, and this check box is RED first make sure everything in the Process Identity section is green, and then make sure that NTAuthenticationProviders contains "Negotiate".  If it is not, the page output will look as follows:

If you are browsing locally on the IIS Server and are logged in as the Administrator, you can click the "Fix This" button to resolve the problem.  If not, you can run the following command to check this setting with the adsutil.vbs script that comes with IIS 6.0.

cscript.exe adsutil.vbs GET w3svc/siteid/root/DelegConfig NTAuthenticationProviders

Where "siteid" is the id of the web site.   Note, if NTAuthenticationProviders is not set at this level, check the value at the previous levels.  The default value is "NTLM, Negotiate", so unless you previously removed this, it should be fine.

Keep in mind that the browser is what decides how to send the credentials to the server.

Process Identity

The Process Identity section does a few different checks to see if Delegation will work for this IIS application pool.

First it checks to see if the Application Pool is configured as a domain account. This domain account can be a Computer, or User account in the domain.   Second, it checks to see if a valid Service Principal Name is configured for the domain account the application pool is configured for.  Third, it checks to see if the domain account is trusted for delegation.  Last, it checks for any duplicate SPN’s for host name(not shown above, but covered a little bit later in this blog post).

Application Pool Identity

This is probably the simplest issue to resolve. Simply make sure the identity the application pool runs as a Domain account.  There are two ways to do this:

·         Set the identity to Network Service, in which case the domain account is the actual Computer Account.

·         Set the identity to a Domain User.  When doing this the user needs to be added to the IIS_WPG group as well.

Has a Valid SPN

An SPN needs to be registered for the application pool identity for the HTTP Service.  By default, the machine account will have a HOST SPN Registered which includes HTTP.  To register an SPN you can use the SetSPN.aspx page that comes with the DelegConfig tool, or you can use the SetSpn.exe tool which can be downloaded from Technet here:

When using SetSPN.aspx, you have to view the page on the IIS Server.

To explain my setup a little bit better I have the following configuration for my Web Application.

·         Application Pool Identity – BB115730\AppPool

·         IIS Machine name BB115730IIS

·         Default Web Site with no host header

 

The DelegConfig tool is telling me I do not have a valid SPN for my BB115730\AppPool account.   To verify this with the setspn.exe tool, use the -L switch.

Setspn.exe –L  BB115730\AppPool

Where BB115730\AppPool is the machine account, or user account you want to verify SPN's for.

Since I do not have an SPN for my domain user account which the application pool is running as, I can add it using either SetSPN.aspx (used below for deleting duplicate SPN's), or the SetSPN.exe.  For this example, I will use SetSPN.exe as follows :

Setspn.exe -A   HTTP/BB115730IIS BB115730\AppPool
Setspn.exe -A   HTTP/BB115730IIS.BB115730.COM BB115730\AppPool

In the case of IIS, the service the SPN needs to be registered for is HTTP.  The information following the HTTP/ is the host name the SPN is being registered for.  This host name is what is passed in the HOST header of the HTTP request to the IIS Server.  So it depends on how the client application creates the host header.     Typically you should register both the machine name, and the fully qualified domain name when using the default web site.   If the web site is using host headers, you need to register the appropriate host header. 

Once I register my SPN for the application pool identity, if I refresh the DelegConfig Default.aspx page, it will indicate there are Duplicate SPN's:

 

This section identifies other Domain Accounts that the HTTP/BB115730IIS and HTTP/BB115730IIS.BB115730.COM SPN's are registered for.  For this example, since I only have this one Application Pool that requires delegation, I will remove the duplicate SPN's listed in the DelegConfig output.  This can be done by clicking "Fix This", which will bring up the SetSpn.aspx page, or using SetSPN.exe.  When browsing to SetSPN.aspx on the IIS Server, the following is displayed:

The SetSPN.aspx page can be used to view, add, and delete SPN's.  The above example shows how to delete the duplicate SPN "http/BB115730IIS.BB115730.COM" for my configuration.   The SetSPN.exe tool can also be used to delete the duplicate SPN's.  The commands used to delete the duplicate SPN's listed above are as follows:

Setspn.exe –D      HTTP/BB115730IIS   BB115730\BB115730IIS$
Setspn.exe –D      HTTP/BB115730IIS.BB115730.COM    BB115730\BB115730IIS$

The side affect of doing this  is that if there are other application pools, running as the identified account in the Duplicate SPN's section, and those application Pools also need to support delegation, then you have a problem.  This is an issue that has to be resolved on a need by need basis.  For more detailed information on Duplicate SPN's please see the following blog post:

http://blogs.iis.net/brian-murphy-booth/archive/2007/03/09/the-biggest-mistake-serviceprincipalname-s.aspx

Trusted for Delegation

This is another simple configuration change.  In Active Directory Users and Computers you need to select the Computer Account, or User Account the application pool is running as, and check the box that says "Trust this account for delegation".  For a user account you must also uncheck the checkbox "Account is sensitive and cannot be delegated".  For a Windows 2003 Domain you can also configure constrained delegation which is outside the scope of this blog post.  Please see the references section for a detailed troubleshooting article on Kerberos delegation.

Back End Server

Lastly, you can click the DelegConfig "Add Backend" button, located at the top of the page, to quickly check the Domain Account and SPN's for a back end server.   It allows you to specify the remote address of the machine, the service type that needs to be checked, the listening port for that service, and the account the service is running as.  After filling in the information on the page for the type of back end server(I used a SQL Server for the output below), you will get output similar to this:

 

 

 The same goes for the back end server service the IIS Server is trying to delegate credentials too.  It must be running as a domain account, and valid SPN's must be registered for that Service.

 The End Result

After turning all the red check boxes to green, delegation should work and the output of default.aspx should look as follows when browsing from the client machine:

 

In the above example, I used a SQL Server as my back end machine.  Since everything is green, I can now delegate the client credentials from the client machine, to the IIS Server, and then to my back end SQL Server.

Closing Comments

The above example illustrated how to use DelegConfig to configure an IIS Server to delegate credentials to a back end server.  The tool can also be used to verify process identity, and SPN's used for Kerberos Authentication as well.   If there are problems with the site or application, after using this tool to verify Kerberos is working correctly, the problem is most likely permissions on the files, or server the applications uses.  For example, a file server might not grant access to the user, or SQL server may not allow access to a table or stored procedure.  Verify the permissions are correct on the resources the user is trying to access.

Additional Resources

This is the end of the road for this blog post.  The following are links referred to in this blog post with more information on resolving the double-hop issues with windows credentials.

1 Comment

  • Thank you for this excellent blog. The tool works very well in a non network load balancer setting. With NLB, you may need add extra steps in NLB. Also the FIX IT option does not work in the NLB. I did manual SPN -D command to remove duplicate SPNs.

Comments have been disabled for this content.