Essential Tips On Kerberos for SharePoint Deployers

  • Article

Hi,

This definitely isn't the first blog post on this topic, and it certainly won't be the last - but hopefully it will bring some peace and understanding to those struggling to get Kerberos working in a live SharePoint deployment.

First off, I must credit Martin Kearn's excellent posts here that were invaluable in getting me started - and will be invaluable to you too.

Why Use Kerberos?

There are a number of good resources that aid understanding Kerberos - the best (imho) being from Keith Brown's .NET security guide, published on the web. If you want to know what Kerberos is, what SPNs are, what delegation is etc. go read items 59-63 of his book here:

https://www.pluralsight.com/wiki/default.aspx/Keith.GuideBook.HomePage

But to summarise the key points from a SharePoint perspective, if you want better authentication performance than NTLM, use Kerberos. If you want to pass your user's credentials through to back end resources (like for example accessing the database exposed through a Business Data Catalog) - then you'll need Kerberos delegation.

Crucial SPN Knowledge

Lets just define the parts of an SPN first - an SPN looks something like this ( a typical SPN for a SQL Server in this case ):

MSSqlSvc/bob.domain.local:1433

Where "MSSqlSvc" is the service class, "bob.domain.local" is the host and 1433 is the port. The port part (including the colon) is optional.

SPNs are basically arbitrary strings that applications "know" how to assemble. They are stored in AD in a multi-valued attribute called servicePrincipalName on user principals. (Multi-valued attributes are what they sound like, attributes that can have none or more values and are typically displayed as a comma-delimited list.)

SetSPN is the tool you should use to create SPNs. When you use SetSPN -A you are just setting this attribute. It's perfectly valid to do this with adsiedit.msc or any other AD editing tool - I don't recommend you do this because SetSPN does some validation to ensure the SPN follows syntax conventions that a direct edit would bypass - I'm just making the point that there is no magic going on and that SPNs are just strings. To set an SPN (with SetSPN or otherwise) you must have permission to write to ServicePrincipalName attribute on the target principal (and that is your least privilege requirement) - although it's a good idea to be able to read them as well.

When a client application wishes to authenticate to a server application with Kerberos, the client must acquire a ticket from the KDC ( = Key Distribution Center which is a role played by Domain Controllers in Windows). To do this, it must tell the KDC which SPN it wants a ticket for. The KDC will take this SPN and look for a principal that has a matching string in its servicePrincipalName attribute.

At the point a couple of things can go wrong: (1) The KDC is unable to find a match in the AD. (2) The KDC finds more than one match in the AD. In either case, you're stuffed and Kerberos authentication will fail. At this point most applications will silently fall back to NTLM authentication and everything will appear to work - unless you need delegation or you have demanded Kerberos authentication. Not many apps demand Kerberos, they usually "Negotiate" an authentication protocol. If you are trying to delegate, then what often happens is that the machine at the end of the second hop gets a NULL identity turning up (see Keith Brown's explanations linked to earlier).

So remember: you can not have two identical SPNs registed to different accounts in your forest. If you do this, neither will work.

So how does the client know which SPN to ask for? Well that's very interesting. It turns out the answer is largely "because it does". The service class and host + port parts of an SPN are completely arbitrary. The client must therefore "know" these things to correctly form an SPN. The one thing it doesn't know (or need to know) is the identity of the principal running the service - the KDC figures this out and passes back a ticket that only the principal against which the SPN is registered will be able to decrypt.

In the case of Internet Explorer, the SPN requested is formed by using a service class of HTTP and a host as specified in the URL, converted to an FQDN (fully qualified domain name) if possible.

Here's the rub: IE never appends the port number to the host name when contacting the KDC for a ticket - even if your server is on a port other than port 80! So for all those SharePoint sites you have on non-80 ports, if you've been specifying a port number in your setspn command, then you haven't been using Kerberos!

Because of the way IE works, its typical to register two SPNs for every web-site. One with the netbios Host name and one with the FQDN host name - this keeps all the bases covered. Just don't put in the port!

So if I ask for https://moss:10000/sites/test for example, then IE will pass an SPN of "HTTP/moss.sharepoint.local" to the KDC (assuming moss is resolved to a box in my sharepoint.local domain) or just "HTTP/moss" if it can't be resolved.

UPDATE: Thanks to Brad Turner for his research on this point - it turns out that there was a fix released for IE that enabled a special registry key setting that changes IE's behaviour so the port number IS included. However, I don't recommend you do this because it is a client side fix, and it's probably hard to guarantee all your clients will have this setting. Even if you use Group Policy to enforce a registry setting, I still don't like it. If you really want to know the details, drop me a line; but be aware I will raise my eyebrow at you!

If you are using host-headers on your website, then use those in your SPN. Remember it's whatever is in the address bar that IE will use to request the SPN. A host-header is set on the dialog you get from the "Advanced..." button on the "Web Site" tab of a web site in IIS 6.0 Manager. It allows IIS to have multiple web-sites on the same port and IIS looks at the address (host header) requested by the client to work out which website to direct the request to. For example, in my MOSS installation I have something like:

portal.sharepoint.local, mysite.sharepoint.local, ssp.sharepoint.local etc. all pointing to the same IP address. The host header can be specified in Central Admin when creating web applications.

You Probably Need Multiple Host Headers

This throws up an interesting point that in most cases this means you will need multiple host-headers in order to be able to use Kerberos in a least privilege environment. Every application pool in a least privilege environment has its own identity. This means that your web applications, which are sitting in different application pools, can't be differentiated by simply using different ports. If you did this, since IE ignores the port when forming its SPN request, the SPNs for each application pool identity would have to be the same - and you can't register the same SPN against multiple accounts! (Oh how I wish this would throw an error!) Thus, a different host header is required to get a Kerberos ticket for each application pool identity in which your SharePoint web applications reside.

How Do I Know Its Working?

Good question. The easiest way is to download Kerbtray.exe (don't worry this says Windows 2000 - it works on all versions). This tool lets you examine the Kerberos tickets for the logon session of the current interactive user only. This means that you can't do something like "Run As" to see the tickets of a service - because you'll be in a different logon session even though its the same principal. However, you can run this tool in a couple of useful places:

  • Run it during initial set up of the farm. At this point the setup account connects to SQL server so you should see a ticket for your SQL box - MSSqlSvc/sql.sharepoint.local:1433 for example.
  • Run it on any client machine connecting to a SharePoint web site. You should see a ticket for the web site in the list - HTTP/portal.sharepoint.local for example.

Also, on SQL Server 2005 you can run a query to check how clients are authenticating. You should see "KERBEROS" in the auth_scheme column:

SELECT login_name, program_name, host_name, auth_scheme
FROM sys.dm_exec_connections C INNER JOIN sys.dm_exec_sessions S
ON C.session_id  = S.session_id

Delegation

If you want to delegate then you need to do more than just create SPNs. You must allow the services that will delegate right to do so. This is described in Keith Brown's guide again. For SharePoint, the services that are most likely to need rights to delegate are the application pool accounts and the SSP service account. You almost certainly don't need to give the computer accounts delegation rights!

A common scenario is BDC delegation where you want your end-users to authenticate against a database directly when querying a BDC web-part for auditing purposes. In this case you just need the application pool hosting the site hosting the web part to have delegation rights - and that's it!

Hope that helps!

James

 ADDENDUM:

Since writing this article the infrastructure update has added some new functionality that includes custom SPNs for SSPs. It's covered in a new technet article and you can read all about it here: https://technet.microsoft.com/en-us/library/cc263449.aspx#section14

Comments

  • Anonymous
    August 20, 2007
    PingBack from http://blogs.msdn.com/martinkearn/archive/2007/04/23/configuring-kerberos-for-sharepoint-2007-part-1-base-configuration-for-sharepoint.aspx

  • Anonymous
    August 20, 2007
    Link Listing - August 20, 2007

  • Anonymous
    August 20, 2007
    I had a great follow-up question from my last post on Kerberos in SharePoint : "We are using Kerberos

  • Anonymous
    August 24, 2007
    Under what circumstances would you want to trust the computer accounts for delegation?  What are the risks if you do?

  • Anonymous
    August 24, 2007
    A computer account is a principal that acts very much like a user account. When you are running a service as "System" or "Network Service" the computer presents itself as this principal to other machines on the network, including the KDC. If you want a service running under these special accounts to be able to impersonate a client on another machine, then you must trust the computer account for delegation. This carries a risk that if the computer is compromised by a malicious agent, that agent can use client credentials on the machine to access other systems as the owner of those credentials. Since typically there are many services that run under the "System" and "Network Service" accounts that do not require to have delegation rights, this approach violates the principal of least-privilege, which is why it is recommended that you use a dedicated service account instead. In Windows 2000, delegation was a rather powerful "on/off" switch since once turned on, you could delegate to any other service on the network. Under Windows 2003, constrained delegation (only available running at the Native domain functional level) allows you to specify precisely to which services, identified by SPNs, you will allow an account to delegate. This mitigates a lot of the risk and is advisable when you feel compelled to run a service that requires delegation under the computer account. Despite this, I rarely come across situations where use of the computer account to delegate credentials is required.

  • Anonymous
    October 21, 2007
    Great article James. I have one question. Is it required to have the Security policy "Impersonate a client after authentication" in order for Kerberos Contrained Delegation to work? Or is it only required in the Protocol Transition case, which I believe also requires "Act as part of Operating System".

  • Anonymous
    December 13, 2007
    The comment has been removed

  • Anonymous
    December 13, 2007
    Sure thing: setspn -a HTTP/portal.mydomain.com DOMAINServiceA setspn -a HTTP/portal.mydomain.com DOMAINServiceB These commands add two identical SPNs to the principals ServiceA and ServiceB. Because of this, the key distribution center will not be able to provide a Kerberos ticket for requests to portal.mydomain.com because it can't uniquely resolve the SPN to a single principal. So, after setting up the SPNs like this, you'll never get kerberos authentication. Unfortunately, some texts have given examples that imply configuring SPNs for SharePoint in just this manner - they'll never work.

  • Anonymous
    February 11, 2008
    If you've been through the install, you're probably ready to get Kerberos authentication. Now

  • Anonymous
    February 11, 2008
    If you've been through the install, you're probably ready to get Kerberos authentication. Now

  • Anonymous
    March 20, 2008
    hi in regards to setting a the SPN with 2 different accounts.. is there any way around this? or DR farm uses different service accounts but the same URLS for the sites. any ideas?

  • Anonymous
    April 25, 2008
    I ran the query against sqlserver and did not see Kerberos.  Do I need to change something about MSSLQSvc account?  

  • Anonymous
    May 29, 2008
    It's truly great article James I have a question what about Publishing web site? I know that Kerberos doesn't work over the internet but what about the communication between the MOSS, SQL and active directory servers? Can I use it in order to improve performance (and not for delegation)?

  • Anonymous
    June 02, 2008
    The comment has been removed

  • Anonymous
    June 11, 2008
    This is a reply to mattaniah's question - the domain account you are using for the MSSQL service may not have write permission on its servicePrincipalName attribute. You can check this with adsiedit.msc (in the windows 2003 support tools). Once you have launched adsiedit.msc, locate the sqlserver account, right-click it and select Properties. Go to the Security tab highlight SELF and click Advanced. The Advanced Security Setings dialog opens. On the Permissions tab click Add..., enter SELF as the object name and hit OK. Then go to the Properties tab and tick Read servicePrincipalName and Write servicePrincipalName permissions. Then OK yourself out of all the dialogs. If you now restart the MSSQL service on the database server and check the servicePrincipalName attribute value in adsiedit.msc, you should see that it has created an SPN. Hope that helps, James.

  • Anonymous
    June 16, 2008
    I sent out a collection of links that I have book marked on Kerberos and thought I would share them with

  • Anonymous
    July 01, 2008
    If you want your credentials to pass throughout all your servers for PPS to work correctly, you really

  • Anonymous
    July 11, 2008
    Coraz częściej w pracy stykam się z koniecznością ustawienia autentykacji poprzez protokół Kerberos ,

  • Anonymous
    July 11, 2008
    Coraz częściej w pracy stykam się z koniecznością ustawienia autentykacji poprzez protokół Kerberos ,

  • Anonymous
    July 29, 2008
    Thanks for a good article about a complex subject! I have a question. :) I know that the RSS viewer webpart in MOSS requires Kerberos authentication to display feeds from other internal MOSS sites. I'm running a single virtual machine with MOSS 2007 & SQL Server 2005 on it, and my cross-site RSS feeds work as expected when I enable Kerberos. What I don't understand is how Kerberos can work on a single workgroup server? (And I don't think it actually is in use on my server, because I can't find any mention of Kerberos in my security Event Log.) I thought that Kerberos needed a KDC (a Windows DC) and an AD infra structure. Thanks for any insights!

  • Anonymous
    December 03, 2008
    Kerberos The basics of using Kerberos in a Sharepoint environment. http://www.windowsecurity.com/articles