Provides an abstract base class for reading, writing, and deleting session cookies on an HTTP client.
public ref class CookieHandler abstract
public abstract class CookieHandler
type CookieHandler = class
Public MustInherit Class CookieHandler
The following example configures the SAM to use a custom cookie handler of type
<cookieHandler mode="Custom"> <customCookieHandler type="MyNamespace.MyCustomCookieHandler, MyAssembly" /> </cookieHandler>
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.
|CookieHandler() CookieHandler() CookieHandler() CookieHandler()||
Called from constructors in derived classes to initialize the CookieHandler class.
|Domain Domain Domain Domain||
Gets or sets the domain used for cookies.
|HideFromClientScript HideFromClientScript HideFromClientScript HideFromClientScript||
Gets or sets a value that indicates whether the cookie should be hidden from client script.
|Name Name Name Name||
Gets or sets the base name for cookies written by the handler.
|Path Path Path Path||
Gets or sets the virtual path for cookies written by the handler.
|PersistentSessionLifetime PersistentSessionLifetime PersistentSessionLifetime PersistentSessionLifetime||
The lifetime of persistent sessions. If zero, transient sessions are always used.
|RequireSsl RequireSsl RequireSsl RequireSsl||
Gets or sets a value that specifies whether the cookie should be used only with SSL.