Session Management

[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.]

When a client first tries to access a protected resource that is hosted by a relying party, the client must first authenticate itself to a security token service (STS) that is trusted by the relying party. The STS then issues a security token to the client. The client presents this token to the relying party, which then grants the client access to the protected resource. However, you don’t want the client to have to re-authenticate to the STS for each request, especially because it might not even be on the same computer or in the same domain as the relying party. Instead, WIF has the client and relying party establish a session in which the client uses a session security token to authenticate itself to the relying party for all requests after the first request. The relying party can use this session security token, which is stored inside a cookie, to reconstruct the client’s IClaimsPrincipal. For more information, see the section “How the WSFAM Works” in WS-Federated Authentication Module Overview.

The STS defines what authentication the client must provide. However, the client might have multiple credentials with which it can authenticate itself to the STS. For example, it might have a token from Windows Live, a user name and password, a certificate, and a smartkey. In that case, the STS grants the client several identities, with each identity corresponding to one of the credentials that the client presents. The relying party can use one or more of these identities when it decides what level of access to grant the client.

The SessionSecurityToken is used to reconstruct the client’s IClaimsPrincipal, which contains all of the client’s identities in a ClaimsIdentityCollection. Each IClaimsIdentity in the collection contains the bootstrap tokens that are associated with that identity.

If a new session token is issued with the session ID of the original session token, SessionSecurityTokenHandler does not update the session token in the token cache. You should always instantiate a session token with a unique session ID.

Note

ReadToken throws a XmlException exception if it receives invalid input; for example, if the cookie that contains the session token is corrupted. We recommend that you catch this exception and provide application-specific behavior.

If a protected Web page contains lots of resources (such as small graphics) that are also in the protected domain, the client must re-authenticate itself to the relying party to download each of those resources. Use of a session authentication token avoids the need to authenticate to the STS for each request, but it still means that many cookies are being sent over. You might want to set up the Web page so that the important data and resources are stored in the protected domain while minor items are stored in an unprotected domain and linked to from the main Web page. Also, set the cookie path to reference only the protected domain.

Extensibility

You can extend the session management mechanism. One reason for this would be to improve the performance. For example, you could create a custom cookie handler that transforms or optimizes the session security token between its in-memory state and what goes into the cookie. To do so, you can configure the CookieHandler property of the SessionAuthenticationModule to use a custom cookie handler that derives from CookieHandler. ChunkedCookieHandler is the default cookie handler because the cookies exceed the allowable size for Hypertext Transfer Protocol (HTTP); if you use a custom cookie handler instead, you must implement chunking.