Tuesday, October 31, 2006

Configuring Kerberos Delegation

One of the challenges to using something like System.DirectoryServices with web apps is managing the security context.  By default, your web application runs with the security context of a local account (often ASPNET or NETWORK SERVICE).  Those accounts are not domain accounts (unless you did something stupid like install IIS on a domain controller), so naturally any code that attempts to read or write to Active Directory is going to fail when the security context is unknown.

First of all, there are many approaches to getting your code in web apps to work.  I am not going to go into all of them, it would take far too long of a post.  Whenever possible, I tell people to use a trusted subsystem model, where the application runs with the desired security context.  When that is not possible, or the application requires fine-grain ACL control (or auditing), you need to actually get the client's security context down through the layers, which means we have to use delegation.

We can break down how to configure delegation based on the deployment of your IIS server.  I am talking about IIS6 here, but this would apply to some degree to IIS5 as well (sans App Pool).  I am also going to make the assumption that your IIS server is a member of a domain with appropriate trust relationships if necessary.  Kerberos delegation doesn't really work without this.

Step 1:  Determine the current security context of your IIS application

You should be able to rattle this off (it is that important to know), but if you are unsure, just open your IIS MMC (Start > Run > 'inetmgr'), find your application and check which application pool it is in (Properties > Virtual Directory > Application Pool).

Next, you should find this application pool in the MMC and check the identity (Properties > Identity).  It might be set to a predefined local account (e.g. NETWORK SERVICE), or it might be set explicitly to some other account.

This is your unmanaged security context.  Now, depending on the type of account this is, we will configure Kerberos delegation differently.  The next two steps 2 and 2a, work slightly differently depending on what your current security context has been determined to be.

Step 2: Is your current security context a local account (i.e. non-domain account like NETWORK SERVICE)?

If you are running IIS as a local account, you should understand that your application will still have an Active Directory identity on the network.  It will be that of the IIS machine account.  Keith Brown has a good write-up on this if you need more clarification why this happens.  Here are the steps to allow the current IIS server to delegate.

1. IIS server must be a member of the domain and <identity impersonate="true"/> should be in web.config
2. Set IIS server computer account in AD Users & Computers MMC as "Trusted for Delegation"
3. IIS Server must be rebooted for this policy to take effect.
4. Integrated Windows Authentication only must be selected for site / virtual directory
5. IIS must not have NTLM only set as authentication method (this is usually not a problem, NEGOTIATE is default, so unless you specifically ran a script to change this, don't worry about it).
6. IIS server name either must match exactly account name in AD, or SetSPN tool should be used in cases where IIS site is set as alternative name (e.g. server is called server01.domain.com, and website is called www.application.com).

Step 2a: Is your current security context a domain account?

1. IIS server must be a member of the domain and <identity impersonate="true"/> should be in web.config
2. Set Domain's App Pool Identity account in AD Users & Computers MMC as "Trusted for Delegation"
3. SetSPN must be used to add SPN to domain service account (e.g. "HTTP/www.myapplication.com").
4. Integrated Windows Authentication only must be selected for site / virtual directory
5. IIS must not have NTLM only set as authentication method (this is usually not a problem, NEGOTIATE is default, so unless you specifically ran a script to change this, don't worry about it).

Step 3:  Make sure your clients are configured to use Kerberos

The final step to getting this all to work is to make sure your clients are configured such that they will attempt Kerberos.  This requires a few items to check.

1. Client must be using IE 5.x+. If client is running IE 6, ensure that "Enable Integrated Windows Authentication (requires restart)" is selected from Tools > Internet Options > Advanced.
2. Web site MUST be recognized as Local Intranet (not Internet Zone) or Trusted site to client. Since Kerberos is not really considered an internet protocol, IE does not even try Kerberos if the current zone is determined to be Internet.  If necessary, specifically add this to Local Intranet sites list.
3. Client account must not be marked as "Sensitive, Do not Delegate" in AD Users and Computers MMC.  Smart administrators often mark their admin accounts with this option to prevent them from being abused.  Delegation will fail if you (the client) are trying to delegate one of these types of credentials.

Troubleshooting

The service principal name (SPN) can be a tripping point for a lot of applications.  Load balancing IIS servers adds additional complication as well.  I would really recommend reading Keith's explanation of Kerberos and how it works.  This should make it clear what the SPN is and why it is necessary.

Finally, Microsoft has a support article out there that is fairly decent.  Check it out if you have problems.

Comments [0] October 31, 2006