Claims to Windows Token Service (c2WTS) Overview

  • Article

[Starting with the .NET Framework 4.5, Windows Identity Foundation (WIF) has been fully integrated into the .NET Framework. The version of WIF addressed by this topic, WIF 3.5, is deprecated and should only be used when developing against the .NET Framework 3.5 SP1 or the .NET Framework 4. For more information about WIF in the .NET Framework 4.5, also known as WIF 4.5, see the Windows Identity Foundation documentation in the .NET Framework 4.5 Development Guide.]

The Claims to Windows Token Service (c2WTS) is a feature of Windows® Identity Foundation (WIF) that extracts UPN claims from non-Windows security tokens, such as SAML and X.509 tokens, and generates impersonation-level Windows security tokens. This allows a relying party (RP) application to impersonate the user. This might be needed to access back-end resources, such as SQL Servers, that are external to the computer on which the RP application runs.

The c2WTS is a Windows service that is installed as part of WIF. For security reasons, however, the c2WTS works strictly on an opt-in basis. It must be started manually and it runs as the local system account. Furthermore, an administrator must manually configure the c2WTS with a list of allowed callers. By default, the list is empty. For more information, see How to: Request a Token from the c2WTS. WIF invokes the c2WTS using IPC, and the c2WTS does not open any network ports.

If your RP application runs as the local system account, it does not need to use the c2WTS. However, if your RP application runs as the network service account, or is an ASP.NET application, for example, it might need to use the c2WTS to access resources on another computer.

Suppose you have a Web farm that consists of a server that runs an ASP.NET application, which accesses a SQL database on a back-end server. You want to make this application claims-aware. However, the application cannot access the SQL database using the claim that it receives from an STS. Instead, it uses the c2WTS to convert the UPN claim to a Windows security token. This allows it to access the SQL database as before.

(Note that to allow an application to access resources on a different server, a domain admin must configure Active Directory to enable constrained delegation. For information on how to enable constrained delegation, see How To: Use Protocol Transition and Constrained Delegation in ASP.NET 2.0.)

Note

If the c2WTS is enabled, and the binding is cookie-mode secure conversation, the c2WTS will be used to rehydrate the Windows identity from the UPN that is serialized out into the secure conversation cookie. This means it is possible for authentication to fail when switching between cookie mode and session mode secure conversation, if the c2WTS is enabled but not properly configured.

Note

WIF installs the c2WTS as a manually started service. If you decide to configure it to start automatically, it is recommended that you also configure it to be dependent on the “Cryptographic Services” system service. Otherwise, c2WTS might not start as expected when the computer starts up. To do this, open a command prompt with administrator privileges and run the following command:

sc config c2wts depend= CryptSvc

How to Use the c2WTS to Obtain a Windows Security Token

There are two ways to use the c2WTS: mapToWindows or on-demand calling to the UpnLogon method. If your application always requires impersonation-level Windows security tokens, then you may choose to enable the mapToWindows property on samlSecurityTokenRequirement on the <securityTokenHandlers> element. On the other hand, if your application requires impersonation-level Windows security tokens only for certain use cases, then you may choose to programmatically call the UpnLogon method when required. Note that the useWindowsTokenService property must be set to true and c2WTS configuration must be added with an appropriate callers list for successful invocation of this method.

WIF provides a method, UpnLogon, which an RP application can call, passing in the UPN claim that it has received from the STS. WIF then invokes the local c2WTS using IPC. UpnLogon returns a WindowsIdentity that represents the user. The following illustration shows how this works:

e6a9def2-c55f-427c-a30f-1a4d8d299191

  1. A client request arrives at the RP application. This request requires the RP application to access an external resource. To do this, the RP application must impersonate the user.

  2. The RP application redirects the client to the IP-STS for authentication.

  3. The IP-STS authenticates the user and issues a SAML token that contains a UPN claim (that is, a claim of type https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn). Note that c2WTS requires a UPN string to perform its operations.

  4. The client submits the SAML token to the RP application.

  5. The RP application validates the SAML token and extracts the UPN claim.

  6. The RP application passes the UPN claim to the UpnLogon method as a parameter and gets back a Windows security token. This method call is automatically done by the Saml 1.1 and Saml 2 SecurityTokenHandlers when the mapToWindows property on the SamlSecurityTokenRequirement on these SecurityTokenHandlers is set to true and the value of useWindowsTokenService on the <windowsClaimsIdentity> element in the <microsoft.IdentityModel> is set to true.

  7. The RP application uses the Windows Identity to impersonate the user and accesses the resource.