Kerberos Technical Supplement for Windows

 

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Kerberos Technical Supplement for Windows

Web Service Security: Scenarios, Patterns, and Implementation Guidance for Web Services Enhancements (WSE) 3.0

Microsoft Corporation

patterns & practices Developer Center
Web Service Security: Home
December 2005

Download	Download this guide in PDF format
Community	Web Service Security Community Workspace [Content link no longer available, original URL:https://go.microsoft.com/fwlink/?LinkId=57044]

Contents

Overview
Local Security Authority (LSA)
Important Concepts
Kerberos Protocol Operations for Web Services
Troubleshooting
More Information

Overview

The Kerberos version 5 protocol represents a network-based authentication service that uses tickets as a proof of identity. In most cases, users are still required to present a user name and password for authentication. However, after users are authenticated, they are issued a security ticket that is used to access protected resources. In contrast, with NTLM authentication, a hashed copy of the user's password is used to perform challenge/response authentication for each protected resource that the person wants to access.

The Brokered Authentication: Kerberos design pattern in Chapter 1, "Authentication Patterns" provides a step-by-step description of the Kerberos authentication process, along with benefits and liabilities associated with using the Kerberos protocol. Understanding the Kerberos authentication process is important, but it is also very helpful to understand how that process is implemented. As a result, this supplement focuses on the implementation of the Kerberos protocol on the Windows platform. It also discusses topics that relate to Web service implementations.

Local Security Authority (LSA)

The LSA Subsystem Service (LSASS) is the security subsystem in Windows that is responsible for:

• User authentication.
• Local system security policy, which controls who can log on to the computer, password policies, privileges that are granted to users and groups, and the system security auditing settings.
• Sending security audit messages to the event log.

User authentication in the LSASS is performed with security packages that are dynamically loaded at run time. There are two basic types of security packages; one is an authentication package that is accessed through a set of APIs, which are referred to as the LSA API. The other is named Security Support Provider (SSP), which is accessed through the Security Support Provider Interface (SSPI).

The LSA API is used for local authentication on a workstation or server. This API is called when you enter a user name and password at the CTRL+ALT+DEL login prompt, or when you use the Win32 LogonUser function that is available through the advapi32dll.

In Microsoft Windows NT® and Windows 2000, users must have Trusted Computing Base (TCB) privileges to use the LogonUser function. This is because it uses a low level LSA API function named LsaLogonUser, which requires system-level rights. In Windows XP and Windows Server 2003, LogonUser was modified so that TCB or system-level rights are not required. This function is not available in Windows 95, Windows 98, and Windows Millennium Edition.

Accessing the LSA

Most of the LSA API functions used for authentication and security context management require system-level privileges. Windows NT and Windows 2000 allowed users with TCB privileges to access these functions. However, in the Windows XP and Windows Server 2003 operating systems, a process must execute under the SYSTEM identity to access these functions. The reason for this restriction is that these functions have access to confidential information, such as the user's hashed password, which should never be accessible outside of the system.

**Note   **The original version of KerberosToken in Web Service Enhancements (WSE) 1.0 and WSE 2.0 used the LSA API directly. Processes that used this token required either TCB or SYSTEM privileges, depending on the operating system. There were also issues related to signing and encryption when the original version of KerberosToken was used in Windows 2000. For these reasons, you should use KerberosToken2 in WSE 2.0 or KerberosToken in WSE 3.0, which both use SSPI.

When it comes to using the SSPI interface, it is not necessary for a process to run under the SYSTEM identity, or to have TCB privileges to perform authentication operations. This is good news for the Kerberos protocol because it means that applications that use the Kerberos SSP are not required to use a high-privilege level when they perform authentication. In other words, using TCB privileges or forcing a process to run as SYSTEM represents a significant security risk, which you can mitigate by using SSPI.

Security Support Provider Interface (SSPI)

SSPI defines a programming interface that security support providers (SSPs) must implement. Microsoft provides the following SSPs:

• Negotiate
• NTLM authentication
• Kerberos protocol
• Digest
• Secure Channel, such as transport layer security (TLS) and Secure Sockets Layer (SSL).

Negotiate is the preferred SSP for application developers to use because it attempts to first use the Kerberos protocol; if a Kerberos Key Distribution Center (KDC) is not available, it uses NTLM authentication. The Digest and Secure Channel SSPs are out of scope for this document.

To use SSPI, the first task is to load the desired SSP and access its security interface, which provides a table with function pointers to the appropriate SSPI operations. An application uses these function pointers to interact with the security support providers. The end result is that an application does not need to bind to a specific support provider. Instead, the operations are dynamically accessed through a function table.

SSPI is generally compatible with the Generic Security Services Application Programming Interface (GSSAPI), which has been published as Internet protocol specification (RFC 2743). GSSAPI represents a standard protocol that provides interoperability with other platforms that use the Kerberos protocol.

**Note   **Even though the GSSAPI has been implemented by the Kerberos SSP, there are some compatibility issues that you should consider. For more information about GSSAPI interoperability, see SSPI/Kerberos Interoperability with GSSAPI on MSDN.

The following section discusses important concepts that you should understand before learning the details of how applications use the SSP Interface for the Kerberos protocol.

Important Concepts

There are several concepts that are important to understand about implementing and using the Kerberos protocol. Because the Kerberos protocol is based on the use of shared secrets, understanding how shared secrets are created and accessed is very helpful. Other concepts that you should understand include service principal names (SPNs), and how the authenticator is used.

Shared Secrets

A main concept of the Kerberos protocol is how shared secrets are created and used for authentication. Essentially, a shared secret is nothing more than an encryption key that the Kerberos protocol uses to perform symmetric encryption. Symmetric encryption uses the same key to encrypt and to decrypt data. The Kerberos protocol uses several symmetric keys to encrypt different pieces of information as part of the authentication process. In addition, the Kerberos protocol supplies an encryption key that applications and services can use to sign and encrypt messages.

There are two main patterns related to using shared secrets: one uses a shared long term key to encrypt data, and the other uses long term keys and session keys. The following is a brief description of each pattern:

• A user's long term key is used to encrypt preauthentication data, which is decrypted by the domain controller that uses the same key.
• A service's long term key is used to encrypt a ticket, which contains a session key along with additional data. The session key is used to encrypt the authenticator. Both the ticket and authenticator are sent in a message. The receiving service uses its long term key to extract the session key and validate the authenticator.

**Note   **There are two types of tickets used by the Kerberos protocol: a ticket-granting ticket (TGT) used to access the ticket-granting service (TGS) and a service ticket used to access a service. Both keys are discussed later in this technical supplement.

Long Term Keys

Long term keys are stored in the credential store on a domain controller and in the credential cache of the LSA. Because these keys are associated with credentials, access to them is highly restricted, which means that access is limited to operations that run within the process of the LSA. In other words, client and server applications do not have access to the actual keys. Instead, LSA API operations use these keys to perform security operations.

Note   Long term keys are also referred to as master keys in many Kerberos protocol documents. When you see the term master key used in a document, remember it is referring to one of the long term keys in the following list.

The Kerberos protocol uses four long term keys to perform authentication:

• User keys. When a user is created, the user's password is used to create the user key. In Active Directory service domains, the user key is stored with the user's object in Active Directory. At the workstation, the user key is derived from the password when the user logs on.

• Service keys. Services use a key based on the password of the Windows account assigned to the process that is hosting the service. Typically this account is the host computer account. However, the process that is hosting a service can also be configured to use a user account.

  All KDCs in the same realm use the same service key, which is based on the password assigned to the krbtgt account. The krbtgt account is a disabled Windows user account that is created when an Active Directory domain is created.

• System keys. When a workstation or a server joins a Windows domain, a new computer account is created and a password is automatically generated. In the same manner as a user account, the computer account's password is used to create the system key.

• Inter-realm keys. To support cross-realm authentication, KDCs share an inter-realm key, which is the basis for transitive trust between domains.

As previously mentioned, a user or computer's password is converted into a long term key that is used for authentication with the Kerberos protocol. This is accomplished by performing a one-way hash on the plaintext password to create a cryptographic key. The default hash implementation in Windows creates a 128-bit key to support the RC4-HMAC encryption type.

When a user or computer account is created in Active Directory, the long term key is stored in the Security Accounts Manager (SAM) accounts database on the domain controller. This database is normally backed up, which means that offline attacks could be used to gain access to long term keys. As a result, a system key that is managed by administrators is used to encrypt the long term keys that are stored in the SAM.

When a user logs on to Windows, the plaintext password is converted into a cryptographic key and is immediately discarded. The cryptographic key, which is also the long term key, is then stored in a volatile memory-based credential cache on the local computer. If the password was typed correctly, the long term key should match the one stored in the SAM, which represents a shared secret between the local computer and domain controller.

Session Keys

Session keys are created for communication with the ticket-granting service (TGS) and the service. The Kerberos protocol uses the session key to encrypt an authenticator. The authenticator contains a timestamp and unique information that is used to authenticate the request. The authenticator also contains an optional sequence number field that can be used to provide message replay detection. Session keys are short term keys that can also be used to sign and encrypt messages.

Service Account

The term Service Account is used to describe the Windows account that a service uses when it performs operations with the Kerberos protocol. In other words, this is the account that the Kerberos protocol uses to retrieve a service's long term key from the credential cache. The actual account that is used is based on the application that is hosting the service and the configuration of that application. When a service ticket is requested from the TGS, the request must identify the service account so that the service ticket can be encrypted using the correct long term service key.

With Internet Information Services (IIS), the security configuration and IIS version plays an important role in determining what account will be used as the service account. Windows Integrated Security uses a different process than the one available when it implements the Kerberos protocol with message layer security. Also, IIS versions 5.x (which is used on Windows 2000 and Windows XP) has more limitations than IIS version 6.0 (which is used on Windows 2003).

Windows Integrated Security with IIS

When using Windows integrated security with IIS, the host computer account is used as the service account by default. With IIS version 6.0 you can override this behavior by creating a domain user account and using that account as the identity of the application pool that is used to host a Web service. This new account is the service account that a client application should use when it requests a service ticket from the TGS.

With IIS versions 5.x, Windows integrated security only uses the host computer account as the service account. This is important to remember because any client application that requests a service ticket for a service that is configured to use integrated security must use the service's host computer account as the service account in the request.

Message Layer Security with IIS

When you implement the Kerberos protocol with message layer security, the service account is based on the identity of the process that is used to host the Web service.

IIS version 6.0 uses an account named NETWORK SERVICE that has appropriate rights and which can be used for Kerberos authentication. With IIS 6.0 the identity of the application pool controls what account is used. By default this identity is set to NETWORK SERVICE. However, it is possible to use a domain user account or the SYSTEM account as the identity of the application pool.

With IIS versions 5.x, the default process account is ASPNET, which is a local account that does not have access to the network or the host computer account. To implement message layer security using the Kerberos protocol with IIS versions 5.x, you must modify the configuration of ASP.NET to use either the SYSTEM account or a domain user account as the process identity.

The "Kerberos Protocol Operations for Web Services" section later in this technical supplement provides detailed instructions that you can use to create and configure a domain user account as the service account used by Web services.

Service Principal Names

An SPN is a unique identifier that applications can use to request a service ticket instead of using the service account name. The Kerberos protocol implementation in Windows uses the SPN to retrieve a valid service account from Active Directory. In other words, an SPN is another type of identifier that can be assigned to an account in Active Directory.

Without the use of an SPN, client applications that request service tickets must know the name of the Windows identity that is used as the service account to request a service ticket.

By using SPNs you do not need to expose account names and you have the ability to implement mutual authentication. In other words, a valid service response provides authentication that the service account associated with the SPN was used to process the request. As a result, when you request a service ticket, the use of SPNs is strongly recommended over the use of service account names.

SPN Types

There are two types of SPNs that can be created: one that is host-based and another that is arbitrary. When a new computer account is created in Active Directory, host-based SPNs are automatically generated for built-in services. Examples of these services include HOST, LDAP, and HTTP. In reality, SPNs are only created for the HOST service and all built-in services use the HOST SPN. However, this implementation is transparent because built-in names act as an alias to the HOST service unless they have been specifically mapped to a Windows account.

**Note   **The HOST service represents the host computer. The HOST SPN is used to access the host computer account whose long term key is used by the Kerberos protocol when it creates a service ticket.

The syntax that is used to identify a host-based SPN contains information about the computer that the service is running on and the port that it uses. The actual name is structured with the following syntax:

<ServiceClass>/<Host>:<Port>.

The following list describes each section of the name:

• ServiceClass is the service you are accessing, such as HTTP.
• Host is the computer name for the computer that hosts the service.
• Port is optional and only used for nonstandard port configurations.

Arbitrary SPNs use the following syntax:

<ServiceClass>/<ServiceName>. 

As indicated in the previous example, this does not require the use of computer information.

The type of SPN that you use is based on the implementation of your service. With Web services, the same factors that affect what service account you can use also has an affect on the SPN that you use. For instance, when you use the host computer account as the service account, you should use a host-based SPN. When you use a domain user account as the service account, you should use an arbitrary SPN. However, in some cases, it may be necessary to define a host-based SPN that references a domain user account.

**Tip   **When you use Windows Integrated Security, both Internet Explorer and IIS use the HTTP SPN to request service tickets and to process a request. As a result, when you use a domain user account in IIS 6.0 as the process identity, you must map the host-based HTTP SPN to the domain account that is used by the service.

Service Classes

Service classes are arbitrary names that represent services, but are not linked to a specific service. Instead, the service class is nothing more than part of a unique key that is used to identify a service account. At the time of writing, a service class has not been defined for Web services. As a result, most examples use the HTTP service class. For instance, to access a service on a computer named London in a domain (a Kerberos protocol realm) named GLOBALBANK.net, the following SPN is used:

http/london.globalbank.net

The HTTP service class is one of the built-in services that act as an alias to the HOST SPN, which is mapped to the host computer account. This means that when you use the default HTTP service class, the Kerberos protocol uses the computer account as the service account when it requests a service ticket. This service class works well with the default configuration of IIS, regardless of which version you use. However, when you create new Web services, you should also create new service classes.

Because a service class is arbitrary, you can choose any name for a new service. However, it is not a good idea to use detailed names that are based on service actions, because the management of these names could become prohibitive. Instead, you should use a name that represents a suite of service actions, or even a suite of services.

When you configure constrained delegation in Windows Server 2003, the Service Type column contains the service class name. In other words, the service type that is used by constrained delegation is the same as a service class. As a result, service classes represent one of the primary identifiers that are used to control access with constrained delegation.

Defining an SPN

The tool that you use to create a new SPN is named setspn.exe. It can be found in the Windows Support Tools for Windows Server 2003.

To create a new SPN

1. From the WindowsSupport Tools menu, open the command prompt.
2. Type the following syntax:

setspn –a <ServiceClass>/<Host | ServiceName> <ServiceAccount>

When you create a new service class for a host-based SPN, you need to create the following two new SPNs:

setspn –a AcmeService/LONDON LONDON
setspn –a AcmeService/LONDON.globalbank.net LONDON

These commands create a new service class for a host-based SPN that is mapped to the host computer account named LONDON using the Pre-Windows 2000 Domain Name System (DNS) name and a Fully Qualified Domain Name (FQDN). Both of these entries are required for host-based SPNs.

When you use a domain user account as the process identity of an IIS 6.0 application pool, you must map the HTTP SPN to the new domain account to use Windows Integrated Security. Use the following commands to create the HTTP SPN:

setspn –a HTTP/LONDON WS_Account
setspn –a HTTP/LONDON.globalbank.net WS_Account

With this example you are adding a new HTTP SPN to the Windows domain account named WS_Account. Because built-in service classes are just aliases to the HOST SPN, these commands create two new SPNs. However, it is important to understand that if HTTP SPNs have already been created you must first delete them before you can map the HTTP SPNs to another Windows account.

Use the following command to create an arbitrary SPN that maps to a specific domain user account:

setspn –a AcmeService/GlobalBank WS_Account

This command creates an arbitrary SPN named AcmeService/GlobalBank that maps to the WS_Account domain user account. You should also notice that the syntax is different. Instead of using a host and a domain after the service class, this uses a service name, which is also arbitrary. A detailed example that uses setspn.exe to map a domain account to a service that is running on Windows XP is discussed later in this chapter.

Kerberos Tickets

The Kerberos protocol specification uses the following description to define a ticket:

"A record that helps a client authenticate itself to a server; it contains the client's identity, a session key, a timestamp, and other information, all sealed using the server's secret key. It only serves to authenticate a client when presented along with a fresh Authenticator."

This definition applies to both the ticket-granting ticket (TGT) and the service ticket, which were introduced in the discussion on shared secrets. Previous sections in this primer also describe how tickets are encrypted with a long term service key, which is the same as the "server's secret key" in the previous definition.

The most important concept to understand about Kerberos tickets is that tickets can only be accessed by the KDC and the service that a ticket was created for. This is because these are the only entities that have access to the service's long term key. Clients that use the Kerberos protocol do not have access to information that is contained in the ticket. However, clients do have a copy of the session key that is found in the ticket, which they use to encrypt the authenticator. A service authenticates the client by extracting the session key from the ticket and decrypting the authenticator.

Ticket Lifetimes

Each ticket issued by the Kerberos protocol has a start time and an expiration time. The ticket can be used as many times as necessary within that time frame. The Kerberos protocol itself does not keep records of tickets. This means that it is up to the ticket holder to renew tickets before they expire. If an expired ticket is presented to a service, an error is returned.

The recommended maximum lifetime for a ticket is one day. However, the default setting is 10 hours. This lifetime value is managed by Kerberos protocol policy settings. In addition, attributes on ticket-granting tickets (TGTs) can be used to enable the automatic renewal for a limited time to extend the lifetime of the TGT.

As previously mentioned, the TGT is used to request service tickets from a TGS. If the TGT is allowed to expire, it cannot be used to request a service ticket. On the other hand, service tickets are only used to authenticate new connections with a service. Ongoing operations are not interrupted if the service ticket expires during the connection.

**Note   **There is some inconsistency in how service tickets are described in many Kerberos protocol documents. Specifically there is a tendency to mix the names "service ticket" and "session ticket." In other words, when you read "session ticket" think "service ticket."

Something to keep in mind is that ticket lifetime is associated with tickets and not the authenticator, which is discussed in the next section.

Authenticator and Message Replay Detection

As mentioned previously, the Kerberos protocol uses two separate data structures to communicate with services. One is the actual ticket, which is created by either the authentication service (AS) for communication with the ticket-granting service (TGS), or by the TGS for communication with a service. The other structure is an authenticator. The authenticator contains two fields that can be used for message replay detection; one is the timestamp and the other is a sequence field.

A constraint imposed by the Kerberos protocol is that messages must be processed within a short time frame, usually five minutes, which is specified in the Kerberos protocol configuration. The way that the Kerberos protocol implements this behavior is through the use of a timestamp field on the authenticator. When a message is received, the authenticator is decrypted with the session key and the timestamp is examined to make sure it falls within the configured time frame on the target server. If it does not fall within the configured time frame, the message is rejected; this represents a type of message replay detection.

Another factor to consider is that the time on all computers within a realm must be synchronized for Kerberos protocol authentication to work properly. On the Windows platform, starting with Windows 2000, computers that are part of a domain are automatically synchronized with the domain controller.

Usually, relying on the timestamp for message replay does not protect against repeated messages that occur within the allowed time frame. As a result, the recommended approach for message replay detection is to use the sequence field in the authenticator. This is an optional field that is typically used for KERB_PRIV and KERB_SAFE messages, which are used to detect replays. This field can also contain a nonce (Number Once) value that can be cached by the service to implement replay detection. For more information about replay detection with the sequence field, see section "5.3.2 Authenticators" in RFC 1510, The Kerberos Network Authentication Service (V5).

**Note   **Windows does not use the authenticator's sequence field for message replay detection. Instead, Windows uses a message replay cache to implement replay detection. With this implementation, the timestamp is used as a unique value to protect against message replay attacks.

Delegation Configuration

Delegation on the Windows platform is implemented with the Kerberos authentication protocol. Windows 2000 Server supports unconstrained delegation while Windows Server 2003 supports both constrained and unconstrained delegation. The process of implementing delegation is beyond the scope of this chapter. However, it is important to understand basic requirements that relate to delegation configuration.

A key to correctly configure delegation is to understand what service accounts are being used by the application that attempts to perform the delegation, and what service is being called. For instance, suppose that you have an IIS Web application that attempts to access a Web service on a remote server using delegation. With delegation, the service account of the Web application is used to retrieve a service ticket to access the Web service. As a result the service account of the IIS Web application must be configured for delegation.

Delegation represents the ability of one service to request access to another service on behalf of a user. As a result, delegation is configured on the service account that requests access and not on the user account. The only exception is that the user account must be configured to support delegation. To do this, make sure the following account setting is not selected: Account is sensitive and cannot be delegated.

When using a domain user account as the service account, delegation must be configured on the domain user account and not on the computer account that hosts the service. To configure delegation in Windows Server 2003, you must first create an SPN for the domain user account. In other words, delegation options are not available on an account until that account is mapped to an SPN by using the setspn utility. On the Windows 2000 platform, delegation options are always available.

When you use constrained delegation, the service account of the application that is being called must be added to the list of allowed services in the delegation configuration dialog box on the service account that is implementing delegation.

For more information about constrained delegation, see Protocol Transition with Constrained Delegation Technical Supplement in Chapter 4, "Resource Access Patterns."

The next section describes the detailed process that is performed when applications use the SSPI interface to perform Kerberos authentication.

Implementing Kerberos with SSPI

Figure 1 illustrates the main operations performed by applications that use the SSPI interface to implement the Kerberos authentication protocol between a client application and a Web service.

Figure 1. SSPI implementation of the Kerberos authentication protocol

As illustrated in Figure 1, SSPI implementation of the Kerberos authentication protocol is described in the following steps:

1. Initial logon is performed outside of SSPI. However, it is important to understand that a logon operation must be implemented prior to using SSPI. The actual logon process is based on the type of client application in use. For Windows applications the logon occurs when a user logs on to a workstation. For Web applications the logon occurs when a user accesses the Web site.

   It is also important to understand that after the logon is complete, all service operations should be performed with the identity of the user who has logged on to the system. The user can be either a person who interacts with an application or a business identity that is used for trusted subsystem implementations. Impersonation is usually required in Web applications so that SSPI will use the correct identity.

2. As previously mentioned, starting with Windows 2000 the default authentication provider is the Kerberos protocol on the Windows platform. As a result, the next operation is an authentication request that is sent to the LSA on the domain controller. After this operation completes, it returns a set of credentials that can be used to access a TGS. The credentials include a session key and a TGT, which are stored in a credential cache on the local computer.

3. The next step is to call the AcquireCredentialsHandle operation, which returns a handle to the credentials of the current user that was stored in the credential cache during the authentication request in the previous step.

4. The credentials handle is then used to initialize a security context that will be used to call a specific service. With the Kerberos protocol, the security context represents a data structure that contains credentials that are used to access a service, such as a session key and service ticket. To initialize the new security context, the LSA on the client workstation interacts with the LSA on a domain controller to request a service ticket from the TGS.

5. When performing a ticket request, the TGT and an authenticator that is encrypted with the session key are sent to the domain controller. The authenticator is a data structure that contains a timestamp along with other information, such as the Kerberos protocol version number. The LSA on the domain controller interacts with the TGS to obtain a new session key and service ticket, which are returned to the LSA on the client workstation.

6. After the security context is initialized, it is then used to access the Web service in the same manner that a request was made to the TGS when it obtained the service ticket. In other words, the session key that was returned in Step 5 is used to encrypt an authenticator, which is sent with the service ticket to the Web service.

7. When a service receives a message with a Kerberos service ticket and authenticator, the first step is to acquire the service's credentials, which are typically the credentials of the server process. These credentials contain the service's long term key that was used to encrypt the service ticket.

8. Both the Kerberos security context and the service's credentials handle are used in a call to AcceptSecurityContext, which is the operation that validates the service ticket that is contained in the message. Validation is performed by using the service's long term key to decrypt the service ticket and access the session key. The session key is used to decrypt the authenticator. Successful decryption of the authenticator is how the service authenticates the client. In addition, the timestamp included in the authenticator is used to limit the lifetime of the authenticator.

9. Optionally, a service can send a response to the client application.

**Note   **This description focuses on SSPI operations that are used to implement the Kerberos authentication process. For more information about Kerberos authentication, see Brokered Authentication: Kerberos in Chapter 1, "Authentication Patterns."

In addition to using the Kerberos protocol for authentication, you can also use Kerberos session keys for signing and encryption.

Signing and Encryption

As mentioned earlier, the Kerberos protocol security context contains a session key. The session key is a short-term symmetric encryption key used to encrypt the authenticator during authentication operations. This same session key can also be used by applications to implement XML signing and encryption. For more information about using symmetric keys for XML signatures and encryption, seeData Origin Authentication and Data Confidentiality in Chapter 2, "Message Protection Patterns."

With SSPI, you can choose from several methods that use the session key for signing and encryption. The following steps describe how to sign and encrypt a message that is sent from a client to a server.

Client:

1. Sign the message with MakeSignature.
2. Encrypt the message with EncryptMessage.

Server:

1. Decrypt the message with DecryptMessage.
2. Validate the message with VerifySignature.

**Note   **Starting with KerberosToken2 in WSE 2.0, another SSPI function named QueryContextAttributes is used to access the session key directly for signing and encryption. Unfortunately, this operation is not available in Windows Server 2000. As a result, the only token in WSE 2.0, and earlier versions of WSE, that supports signing and encryption in Windows 2000 is KerberosToken.

Kerberos Protocol Operations for Web Services

This section provides information that you can use to perform different operations that relate to the Kerberos protocol and Web services.

Using a Domain Account with IIS 5.x (Windows 2000 and Windows XP)

Instead of using the default account that is defined in the <ProcessModel/> element of the Machine.config file, a service can use a domain user account as the process identity. The domain account needs additional privileges and if it is used for message layer security, an arbitrary SPN should be created.

To configure a domain account for the Kerberos protocol on a computer running IIS 5.x:

1. Create a new user account in the domain (KDC realm) and add that account to the user group. This account does not need additional privileges on the domain computer. This means that you are using an account with the fewest privileges.

2. On the computer running IIS 5.x, the new domain account requires the following rights, which can be assigned with the Local Security Settings configuration tool:

   • Log on as a service
   • Impersonate a client after authentication

3. Assign Full Control permissions to the new domain account for the following folder on the IIS 5.x host:

   C:\%WINDOWS%\Microsoft.NET\Framework\v1.1.4322\Temporary ASP.NET Files
   

4. Update the <ProcessModel/> element in the Machine.config file on the computer that is running IIS 5.x. Both the user name and password need to be updated to values associated with the new domain account. Restart IIS.

5. When using ASP.NET 2.0, the new domain account requires read access to the IIS metabase. On the computer running ASP.NET 2.0 and IIS 5.x, execute the following command:

   C:\%WINDOWS%\Microsoft.NET\Framework\v2.0.50727>aspnet_regiis –ga <domain account>
   

   **Note   **The following step is required when you are using message layer security with the Kerberos protocol. When you use standard Windows authentication, it is not necessary to create an SPN for the account unless the account will be used for Delegation.

6. Use the setspn.exe tool to create an arbitrary SPN for the domain account. This action is performed on the Active Directory domain controller, not on the computer that is running IIS 5.x. To perform this action, you must be an administrator or have SetPrincipalName permissions on the domain controller. The following example creates an arbitrary SPN named AcmeService/GlobalBank that maps to a Windows account named WS_Account:

   setspn –a AcmeService/GlobalBank WS_Account
   

When you create a domain account that will be used for delegation with Windows Integrated Security, it should map to the HTTP host-based SPN. If you use message layer security with WSE 3.0, use an arbitrary SPN as previously described. Finally, the process model used by IIS 6.0 in Windows Server 2003 is very different from IIS 5.x. As a result, the steps previously described will not work in Windows Server 2003.

For step-by-step instructions on creating a domain user account and using the application pool identity in Windows Server 2003, see Protocol Transition with Constrained Delegation Technical Supplement in Chapter 4, "Resource Access Patterns."

Web Farm Deployment with WSE 3.0

When you deploy Web services to a Web farm, you must use a domain account that maps to an arbitrary SPN for each Web server in the farm. When you configure services in a Windows 2000 Web farm, you can use the same technique that was previously described for using a domain account with IIS 5.x. When you configure services in a Windows 2003 Web farm, see Protocol Transition with Constrained Delegation Technical Supplement in Chapter 4, "Resources Access Patterns," as a guide for using a domain account in that environment.

When you use the Kerberos protocol to access services in a Web farm, you must use the arbitrary SPN as the target principal, and not the HOST SPN. For example, when you use WSE 3.0, you use the arbitrary SPN as the targetPrincipal to initialize a KerberosToken security token.

Troubleshooting

This section contains information that you can use to troubleshoot common problems with the configuration and the implementation of the Kerberos version 5 protocol. If you are unable to resolve an issue after reading this section, see Troubleshooting Kerberos Delegation for in-depth troubleshooting information about the Kerberos protocol implementation in Windows 2000 and Windows 2003.

Duplicate SPNs

When creating and using new SPNs with Web services, you may need to perform some troubleshooting. For instance, if you accidentally map the same SPN to two different accounts, the SPN will no longer work. It may also be necessary to list all of the SPNs that are associated with an account to determine if a specific SPN has been created.

Windows Support Tools for Windows Server 2003 contains a utility named Ldifde.exe that you can use to list all accounts that map to a specific SPN.

To perform a query with Ldifde.exe

1. From the Windows Support Tools menu, open the command prompt.

2. Type the following command:

   ldifde -f c:\spn_out.txt -d "DC=globalbank,DC=net" -l serviceprincipalname -r "(serviceprincipalname=HTTP/LONDON*)" -p subtree
   

This command searches for all of the SPNs in the globalbank.net domain that match the search mask HTTP/LONDON*. It writes the results to a text file named spn_out.txt on drive C.

You can also use the setspn utility to list all of the SPNs that map to a specific account.

To list SPNs associated with an account

1. From the Windows Support Tools menu, open the command prompt.

2. Type the following command:

   setspn –l LONDON
   

This command lists all of the SPNs that map to the LONDON computer account. The default list should contain two HOST entries and if SQL Server is installed, it will contain an MSSQLSvc entry.

If you need to remove an SPN—for instance if you have mapped the HTTP SPNs to a domain user account and need to remove that mapping—you can use the following commands:

setspn -d HTTP/LONDON WS_Account
setspn -d HTTP/LONDON.globalbank.net WS_Account

Notice that this is the same syntax that you use to create an account, However, the command line option is -d (delete) instead of -a (add). Also notice that both the DNS and FQDN based names have been removed.

Cached Tickets

When a user or computer logs on to a domain with the Kerberos protocol, their credentials and account information are stored in a cache on the local computer. This cache only resides in memory and is not persisted to disk. However, it will remain active while the user or computer is logged in. The end result is that any ticket created by the Kerberos protocol for a user or computer is stored in the cache until the user or computer either logs out, or the cache is manually purged.

This behavior has the following significant impacts:

• Changes to account information, such as Active Directory group membership and delegation configuration, are not updated until the cache is cleared.
• Changes to SPN configuration, such as modifying the HTTP host-based SPN to use a different Windows account, are not picked up until the cache is cleared.
• Changing the password of a service account causes cached tickets that are assigned to the account to become invalid.

As a result of this caching, changes to the configuration may cause issues with the Kerberos protocol that are difficult to determine. The following two approaches can be used to purge the cache:

• Users can log off their computers and then log on again to purge user information, and the computers can be restarted to purge computer information.
• You can use tools in the Windows Resource Kit to purge tickets from the cache.

KerbTray and KList

The Windows Resource Kit provides two tools, named KerbTray and KList, which provide the ability to list and purge tickets that are used by the Kerberos protocol.

The Kerberos Tray (KerbTray) is a graphical user interface tool that displays ticket information for a computer that runs the Kerberos version 5 protocol. You can view and purge the ticket cache by using the KerbTray tool icon located in the system tray on the desktop. By positioning the cursor over the icon, you can see the time left on the initial TGT associated with the logon session before it expires. The icon also changes in the last hour before the LSA renews the ticket.

Kerberos List (KList) is a command line tool that can be used to list service tickets and initial TGT associated with the current logon session. KList also provides the ability to purge tickets associated with the current logon session.

Caution   Purging tickets used by the Kerberos protocol can impact functionality in the current logon session. In most cases, you can recover functionality by repeatedly attempting an operation. However; this method does not always work. If you have purged tickets and are not able to recover after several attempts, your only option is to log off and then log on again to the computer.

IIS Caching and Delegation

Another area that tends to cause problems when configuring delegation is the caching implementation in IIS. As previously mentioned, changes to delegation usually require purging tickets that are associated with the account that was modified. However, with IIS this behavior is different.

The following information describes how IIS behaves when you modify a service account to disable or enable delegation:

• When delegation is disabled on an account, IIS immediately picks up the change and denies access to downstream resources.
• When delegation is enabled on an account, IIS does not recognize the change. Instead, IIS must be restarted to pick up the delegation change and allow access to downstream resources.

For more information about configuring delegation, see the "Delegation Configuration" section earlier in this technical supplement.

More Information

For information about compatibility issues between GSSAPI and the Kerberos SSP, see "SSPI/Kerberos Interoperability with GSSAPI" on MSDN.

For information about replay detection with the sequence field, see section "5.3.2 Authenticators" in RFC 1510.

For in-depth troubleshooting information for the Kerberos protocol implementation in Windows 2000 and Windows 2003, see "Troubleshooting Kerberos Delegation" on Microsoft TechNet.

For information about Kerberos authentication, see "What Is Kerberos Authentication?" on Microsoft TechNet.

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.