Active Directory and Kerberos Service Principal Names

I had to recently modify a web service container (Apache Axis 2) to support the WS-Security Kerberos token profile.

To achieve this, I had to go from knowing absolutely nothing about Kerberos, to being a near expert in it and its related technologies. This involved having to do my own builds of the Apache WS-Security implementation, getting a complete understanding of the WS-Security Kerberos token profile for SOAP messages, learning how to configure and setup Key Distribution Centers (KDCs) such as Active Directory and Apache Directory and finally learning the ins and outs of the Java JAAS/GSS APIs to implement all this.

Part of this process involved me having to get a complete understanding of how the Kerberos algorithm works, including what on earth Service Principal Names (SPNs) are.

Googling around for this, and trawling through the Sun Java forums was only enough to give me bits and pieces of info. Even talking to so called "experts" in the Sun forums was not enough to answer these questions. The ironic thing about this is, that the answers are extremely simple, once you understand the Kerberos algorithm.

Note that this blog is specific to Windows domains running Active Directory. I will do a blog in the future about setting up Apache Directory Server as your KDC.

1. What is a SPN?

A service that is being secured by Kerberos, is required to have an identity within the realm that the system exists. On a Windows network, your service must have an identity in Active Directory (if AD is the domain controller), in the same way a user logging in to your client application must also have an identity in AD (user account).

In Kerberos, when a client identifies the service they are wanting to talk to, a Kerberos naming convention is used to identify that service. This convention is different from how AD would identify that service's user account. Whereas AD would know the account by a simple username, the Kerberos standard includes information such as the machine and the domain that the service runs on.

An SPN, is simply a way of telling AD that the Kerberos identity x maps to the AD account y. Then when Kerberos requests are made to AD, it can translate the Kerberos identities to the correct AD accounts.

2. What does a Kerberos SPN look like?

This is the part where it is quite confusing. The actual format for SPNs is supposed to be something like:

< service type >/< instance name >:< port number >/< service name >

However, not all this information is needed. I never specify the port number, as there is only ever one web services container running on the target machine. Additionally, I don't usually specify the realm as my stuff only runs within one realm anyway, and the JAAS library appears to append this information anyway.

For me, the best answer to this question is "Something that works!". Hence I use one of the following :

< service name >/< instance name >
< service name >/< instance name > @ < realm name >

These have worked fine for me with both an AD domain and an Apache Directory domain.

E.g. mywebservice/testmachine or mywebservice/testmachine@example.com

Note that in some cases, computers are also given Kerberos identities to prevent spoofing of machines. The format for a computer on a network is:

host / < machine name >.realm.com@REALM.COM

3. How do I set up SPNs in Active Directory?

Most of the info I found on the net pointed to the ktpass tool for setting up Kerberos SPNs. I had real trouble getting this to work correctly in Active Directory, specifically with the encryption types being incompatible.

Then I found the setspn.exe program that comes with Active Directory, and it sorted all my problems out.

Setspn.exe lets you set your Kerberos to AD mappings up and also will list the SPNs for a given AD account. It is simple to use, and you don't have to worry about DesMd5 vs ArcFourHmac encryption errors.

The following command adds an SPN for a user account:

setspn -A servicename/machine ad-service-account-name

e.g. setspn -A datawebservice/testserver datawebservice

where datawebservice is the AD identity/account for the web service.

Use the -l parameter to list the SPNs for a given account.

4. Sidestep SPNs.

I also found that it is possible to simply ignore SPNs when using the Java GSS API. When specifying a GSS server name to create a context with, simply specify it as an NT_USERNAME instead of an NT_HOSTBASED_SERVICE.

e.g. GSSName serverName = manager.createName( "datawebservice", GSSName.NT_USER_NAME);

Note that if you are having to interop with .NET services, you may not be able to do this. Additionally, .NET Kerberos applications may not be as flexible in their Kerberos naming rules.