Many of us find troubleshooting Kerberos configured for a website on IIS Server quite a tedious task since it involves multiple levels of troubleshooting. This blog is meant to demystify the art of troubleshooting Kerberos on IIS Server.

Why is Kerberos painful at times?

1. First, understanding Kerberos is quite tricky.
2. Configuration takes a lot of time as we need to look at configuration of IIS server, Domain controller and Client side.
3. Once a site breaks because of some configuration related issues, it’s really difficult to identify the exact cause because of the complexity.

Let’s see what exactly happens “Under the Hood”:

At a high level, the following steps needs to be followed to configure Kerberos for a website:

On IIS Server:

1. Disable all the authentication methods except windows authentication
2. In windows authentication section, in Providers we should see negotiate should be a priority
3. Based on the Application pool credentials,
   • useAppPoolCredentials to true if we are using a custom account
   • useAppPoolCredentials to false and useKernelMode to true if we are using a machine account

On Domain Controller:

1. Based on the Application pool credentials on the IIS we set Service Principle names on the DC.
   • If we use a Machine account, set SPNs on Machine account
   • If we use a custom account, set SPNs on custom account
2. The above also depends on whether we are using a hostname or machine to browse the website

On Client Browser(Internet Explorer):

1. Based on whether we use hostname or not, we need to add the host/machine name to Trusted sites/Local Intranet Zone.

You can find more information regarding Configuration of Kerberos in the following blogs:

1. https://blogs.msdn.microsoft.com/chiranth/2013/09/20/all-about-kerberos-the-three-headed-dog-with-respect-to-iis-and-sql/
2. https://blogs.msdn.microsoft.com/chiranth/2014/04/17/setting-up-kerberos-authentication-for-a-website-in-iis/

Now just imagine if we can automate the above process through a nifty application which can help us troubleshoot/configure Kerberos in just a few minutes – Is it possible? The good news is that NOW IT IS POSSIBLE

I have developed a simple troubleshooter “Kerberos Configuration Manager for IIS” which allows one to do the following tasks:

1. Review the current settings related to Kerberos for any specific website in IIS.
   • Checks and displays the site properties
   • Checks and displays Application pool properties like Application pool identity
   • Checks and displays Anonymous authentication properties
   • Checks and displays Basic authentication properties
   • Checks and displays Digest authentication properties
   • Checks and displays ASP.NET Impersonation properties
   • Checks and displays Windows authentication
     • whether Windows authentication is enabled or disabled
     • What are the Providers settings
   • Checks and displays Configuration editor settings for windows authentication
     • UseAppPoolCredentials settings
     • UseKernelMode settings
   • Based on the Application pool identity,
     • Checks for the existing SPNs for that identity and displays them
     • Displays the necessary SPNs required for Kerberos to work

2. Configures Kerberos for the affected website:
   • Disables Anonymous authentication if enabled
   • Disables Basic authentication if enabled
   • Disables Digest authentication if enabled
   • Disables ASP.NET Impersonation if enabled
   • Enables Windows authentication if disabled
     • Once the above is enabled, checks whether we have Negotiate on priority or no. If not, Negotiate is moved to the top
   • Based on the application pool credentials,
     • Either it will enable useAppPoolCredentials or disables it
     • Either it will enable useKernelMode or disables it
   • Based on the Application pool identity,
     • Checks for the existing SPNs for that identity and displays them
     • Displays the necessary SPNs required for Kerberos to work
   • Generates the script for setting the required SPNs in the same directory

3. It also has a provision to revert the changes made just in case there is a requirement.
4. It also has a feature of auditing through a log file which would capture the below details:
   • Logged in user who used the tool and made changes
   • Timestamp when the changes were made
   • Review, Configure and Revert logs (All settings which were added/modified)

Note: As of now this tool configures Kerberos Single Hop only. In the upcoming versions, it will support double hop as well.

Why should I use tool?:

1. Troubleshooting Kerberos just becomes much simpler with this tool and it optimizes the time taken to troubleshoot from few hours to few minutes.
2. You can review the Kerberos Configuration for any of your web sites and share the generated log files with support to save precious troubleshooting time.
3. No need to install the tool -  it’s a standalone executable.
4. Disk space utilization is minimal.
5. Open source, free to download and modify.
6. Auditing support which makes troubleshooting Kerberos easier.

Where do I get it from and how do I use it?

The tool can be downloaded from the open source github repo:

https://github.com/SurajDixit/KerberosConfigMgrIIS/releases/download/v1.0/KerberosConfigMgrIIS.exe

The GUI has a fairly simple layout with the options to Review, Configure, Generate Script and Revert.

Instructions for use:

1. Create a folder called KCMI and copy the executable file “KerberosConfigMgr.exe”.
2. Run the executable “KerberosConfigMgrIIS.exe” as an “Administrator” by right clicking on the file and choosing the option to “Run as Administrator”.
3. When you execute the file, you will see the below screen:
   
4. Select the website from the drop down menu for which you want to configure Kerberos, and click on the review button.
5. Once you click on the Review button you will see the current Kerberos configuration for the selected website.
6. In-between you will see the Dialogue which is shown below to ask whether we are making use of “Hostname” to browse the website?
7. If we click “Yes”,  we will see one more Dialogue box to input the hostname. If we click “No”,  we don’t see any dialogue box and execution will continue.
8. The Kerberos configuration would show all the recommended and non-recommended settings. Please review it carefully.
9. Once you have reviewed the setting and you are ready to “Fix” the problem, please click on “Configure” button to make the necessary changes
10. Once the configuration is implemented, you will see 2 buttons enabled, One is Generate script and other is Revert. Also you will notice that the dropped down will be locked so that we don’t revert the changes for a wrong site by mistake.
11. Once you click the Generate Script you will see a .cmd file in the current folder which has the commands to add SPN on the Domain controller.
12. In case you want to revert the changes, simply click on “Revert” button and all the changes which were made earlier will be reverted back with respect to IIS (Note: If you have executed the .cmd file, it will not be reverted).
13. As soon as you start the application, a Log file is generated in the same folder as the executable with the system date timestamp. This log file would capture the timestamp, logged on user and all the series of configuration changes implemented during the session.
14. In case you want to review changes for new website, Close the tool and reopen it as administrator and follow the above steps from step# 1.

And that’s all, you will have your site configured with Kerberos on IIS!

Any pre-requisites?

Operating System : Windows Vista & above
.NET Framework  : 4.5.2 & above

Feedback:

If you have any feedback, inputs, bugs to report about the tool, please comment below.

Happy Troubleshooting!