CookieHandler Class

Definition

public ref class CookieHandler abstract

public abstract class CookieHandler

type CookieHandler = class

Public MustInherit Class CookieHandler

Inheritance

Object

CookieHandler

Derived

System.IdentityModel.Services.ChunkedCookieHandler

Examples

The following example configures the SAM to use a custom cookie handler of type MyNamespace.MyCustomCookieHandler.

<cookieHandler mode="Custom">  
    <customCookieHandler type="MyNamespace.MyCustomCookieHandler, MyAssembly" />  
</cookieHandler>  

Remarks

The SessionAuthenticationModule (SAM) uses an instance of the CookieHandler class to read, write, and delete the cookie or cookies that contain the SessionSecurityToken on the HTTP client. The cookie (or cookies, in the case where the session token is split across several cookies) that contains the session token is known as the session cookie.

Windows Identity Foundation (WIF) ships with a cookie handler called the chunked cookie handler that is implemented by the ChunkedCookieHandler class. The chunked cookie handler splits the session token across one or more cookies according to a specified chunk size. This is to meet size limitations on individual cookies imposed by many browsers.

You can derive from CookieHandler to create your own cookie handler. When you do so, you must override the DeleteCore, ReadCore, and WriteCore methods to perform the actual work of deleting, reading, and writing the session cookie. These methods typically read the cookie from the HttpRequest.Cookies collection and write or delete cookies through the HttpResponse.Cookies collection. The HttpContext object through which you can access the request and response is provided as a parameter to each of these methods. In addition to the required methods, you can optionally override other virtual methods properties exposed by the CookieHandler class to customize the behavior of your handler.

Several properties are exposed by the CookieHandler class that specify default behavior and properties for the session cookie. The Name, Domain, and Path properties supply the base name for the cookie, the domain in which it is valid and the path under which it is stored on the client. The HideFromClientScript property specifies whether the cookie is accessible to client-side scripts. The RequireSsl property specifies whether the cookie should be transmitted only over secure (HTTPS) connections. If set, the PersistentSessionLifetime property is used to set the expiration time for persistent sessions, that is for sessions that remain valid even after the browser is closed. All of these properties have equivalent properties that are typically set on the underlying HttpCookie object (or objects) by the "core" methods of the handler. For more information see the documentation for each property.

The cookie handler that is used by the SAM can be specified in configuration through the <cookieHandler> element. The cookie handler set by this element can be modified in an event delegate for the FederatedAuthentication.FederationConfigurationCreated event or it can be set or accessed directly through the SessionAuthenticationModule.CookieHandler property.

Constructors

Properties

Methods

Applies to

See also

• ChunkedCookieHandler
• <cookieHandler>