Differences between KerberosToken and KerberosToken2

The KerberosToken2 security token has three main features that the KerberosToken security token does not have:

• The KerberosToken2 security token, which uses the Security Support Provider Interface (SSPI), does not require elevated privileges like the KerberosToken security token does to impersonate the client's identity.
• The KerberosToken2 security token can be used to secure SOAP messages sent to a Web service running in a Web farm.
• The identity associated with the KerberosToken2 security token can be impersonated and used for constrained delegation.

Operating System Support

The following table lists the minimum permissions or group membership required by the identity under which WSE is running to use the KerberosToken2 security token features.

The following table lists the minimum permissions or group membership required by the identity under which WSE is running to use the KerberosToken security token features.

Using the KerberosToken2 security token in a Web farm

To secure SOAP messages sent to a Web service that run in a Web farm using a KerberosToken2 security token you must do the following steps:

1. Change the account that the Web service is running under to a domain user account.
   For Web services created using ASP.NET, the account the ASP.NET worker process runs under is controlled by the <processModel> element in the Machine.config file, unless the Web service is running under Internet Information Services (IIS) version 6.0. Set the userName attribute of the <processModel> element to specify the account ASP.NET runs under. By default, the userName attribute is set to the special Machine account, which maps to the low-privileged ASPNET user account created when the .NET Framework SDK is installed. IIS 6 uses application pools to determine the process identity, and the default account a Web service runs under is Network Service. Therefore, for a Web service running under IIS 6, the default user account is Network Service; otherwise the default is the ASPNET user account.

2. Add the account that the Web service is running under to the IIS_WPG group.

3. A service principal name must be registered on all computers within the Web farm.
   The service principal name can be registered using the SetSpn.exe tool. For details about registering service principal names, see SetSpn.exe.
   Once the service principal name is registered correctly, a client application can create a new instance of KerberosToken2 using one of the constructors that take a target principal name and then use that security token to sign or encrypt a SOAP message that is sent to the Web service. The format of the target principal name is (domain is optional):

   ServicePrincipalName[@domain-name]
   

Impersonating a KerberosToken2 security token

The recipient of a SOAP message that contains a KerberosToken2 security token can impersonate the identity associated with the token or impersonate the identity and use the identity for constrained delegation. Impersonating the identity allows the recipient to access resources on the same computer as the recipient using the security token's identity. Constrained delegation allows the recipient to access resources on remote computers that can be accessed through constrained delegation, as specified in Active Directory. Constrained delegation requires the SOAP message sender to allow the identity to be impersonated and the domain controller must be configured for constrained delegation.

Impersonation

The following code example demonstrates the XML elements that must be added to a client's policy file in order for a recipient Web service to impersonate the identity of the client using policy.

<SecurityToken xmlns="https://schemas.xmlsoap.org/ws/2002/12/secext">
   <wssp:TokenType>https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5_AP_REQ</wssp:TokenType>
   <wssp:TokenIssuer>cohowinery.com</wssp:TokenIssuer>
   <wssp:Claims>
      <wssp:ServiceName>host/WineLabelServer</wssp:ServiceName>
      <wse:ImpersonationLevel>impersonation</wse:ImpersonationLevel>
   </wssp:Claims>
</SecurityToken>

For more details about the <ImpersonationLevel> element, see <ImpersonationLevel> Element.

The following code example demonstrates a Web service that impersonates the identity associated with a KerberosToken2 security token received in a SOAP message and then accesses a file on the recipient's computer using the impersonated identity.

<WebMethod()> _
Public Function HelloWorld() As String
   Dim kerbToken As KerberosToken2
   ' Call a user-defined method to get the security token
   ' that signed the SOAP message.
   kerbToken = GetSigningToken(RequestSoapContext.Current) 

   If kerbToken.ImpersonationLevel = ImpersonationLevel.Impersonation Then
      Dim identity As WindowsIdentity = _
        CType(kerbToken.Principal.Identity, WindowsIdentity)
      Dim context As WindowsImpersonationContext = _
        identity.Impersonate()

      Dim stream As FileStream = File.Open("C:\Temp\test.txt", _
        FileMode.Open, FileAccess.Read, FileShare.None)
      stream.Close()
      context.Undo()
   End If
   Return "Hello World"
End Function

[WebMethod]
public string HelloWorld()
{
   KerberosToken2 kerbToken = AppBase.GetSigningToken(RequestSoapContext.Current) as KerberosToken2;
   if (kerbToken.ImpersonationLevel == ImpersonationLevel.Impersonation)
   {
      WindowsIdentity identity = kerbToken.Principal.Identity as WindowsIdentity;
      WindowsImpersonationContext context = identity.Impersonate();

      // Access the file on the local computer using the token's
      // identity.
      FileStream stream = File.Open(@"C:\Temp\test.txt", FileMode.Open,
         FileAccess.Read, FileShare.None);
      stream.Close();
      // Revert back to the original identity.
      context.Undo();
   }
   return "Hello World";
}

Constrained Delegation

To enable constrained delegation, the sender, receiver, and the domain controller must be configured to do so. The following steps enable constrained delegation are:

1. On the domain controller, unselect the Account is sensitive and cannot be delegated for the account under which the client application is running.
2. On the domain controller, select the Account is trusted for delegation for the account under which the client application is running.
3. On the domain controller, configure the middle tier computer so that it is trusted for delegation, by selecting the Trust computer for delegation option.
4. On the domain controller, configure the middle tier computer to use constrained delegation, by selecting the Trust this computer for delegation to specified services only option.

For more detailed instructions about configuring constrained delegation, see the following topics on MSDN:

• Troubleshooting Kerberos Delegation
• Kerberos Protocol Transition and Constrained Delegation

See Also

Reference

<ImpersonationLevel> Element

Other Resources

Kerberos Ticket