<cookieHandler>
Configures the CookieHandler that the SessionAuthenticationModule (SAM) uses to read and write cookies.
<configuration>
<system.identityModel.services>
<federationConfiguration>
<cookieHandler>
Syntax
<system.identityModel.services>
<federationConfiguration>
<cookieHandler name=xs:string
path=Path
mode="Chunked||Custom||Default"
persistentSessionLifetime=xs:string
hideFromScript=xs:boolean
requireSSL=xs:boolean
domain=xs:string
<chunkedCookieHandler size=xs:int />
<customCookieHandler type="MyNamespace.MyCustomCookieHandler, MyAssembly" />
</cookieHandler>
</federationConfiguration>
</system.identityModel.services>
Attributes and Elements
The following sections describe attributes, child elements, and parent elements.
Attributes
| Attribute | Description |
|---|---|
| name | Specifies the base name for any cookies written. The default is "FedAuth". |
| path | Specifies the path value for any cookies written. The default is "HttpRuntime.AppDomainAppVirtualPath". |
| mode | One of the CookieHandlerMode values that specifies the kind of cookie handler used by the SAM. The following values may be used: - "Default" — The same as "Chunked". - "Chunked" — Uses an instance of the ChunkedCookieHandler class. This cookie handler ensures that individual cookies do not exceed a set maximum size. It accomplishes this by potentially "chunking" one logical cookie into a number of cookies on-the-wire. - "Custom" — Uses an instance of a custom class derived from CookieHandler. The derived class is referenced by the <customCookieHandler> child element.The default is "Default". |
| persistentSessionLifetime | Specifies the lifetime of persistent sessions. If zero, transient sessions are always used. The default value is "0:0:0", which specifies a transient session. The maximum value is "365:0:0", which specifies a session of 365 days. The value should be specified according to the following restriction: <xs:pattern value="([0-9.]+:){0,1}([0-9]+:){0,1}[0-9.]+" />, where the leftmost value specifies days, the middle value (if present) specifies hours, and the rightmost value (if present) specifies minutes. |
| requireSsl | Specifies whether the "Secure" flag is emitted for any cookies written. If this value is set, the sign-in session cookies will only be available over HTTPS. The default is "true". |
| hideFromScript | Controls whether the "HttpOnly" flag is emitted for any cookies written. Certain web browsers honor this flag by keeping client-side script from accessing the cookie value. The default is "true". |
| domain | The domain value for any cookies written. The default is "". |
Child Elements
| Element | Description |
|---|---|
| <chunkedCookieHandler> | Configures the ChunkedCookieHandler. This element may only be present if the mode attribute of the <cookieHandler> element is "Default" or "Chunked". |
| <customCookieHandler> | Sets the custom cookie handler type. This element must be present if the mode attribute of the <cookieHandler> element is "Custom". It cannot be present for any other values of the mode attribute. The custom type must be derived from the CookieHandler class. |
Parent Elements
| Element | Description |
|---|---|
| <federationConfiguration> | Contains the settings that configure the WSFederationAuthenticationModule (WSFAM) and the SessionAuthenticationModule (SAM). |
Remarks
The CookieHandler is responsible for reading and writing raw cookies at the HTTP protocol level. You can configure either a ChunkedCookieHandler or a custom cookie handler derived from the CookieHandler class.
To configure a chunked cookie handler, set the mode attribute to "Chunked" or "Default". The default chunk size is 2000 bytes, but you may optionally specify a different chunk size by including a <chunkedCookieHandler> child element.
To configure a custom cookie handler, set the mode attribute to "Custom". You must also specify a <customCookieHandler> child element that references the type of your custom handler.
The <cookieHandler> element is represented by the CookieHandlerElement class. The cookie handler that was specified in configuration is available from the CookieHandler property of the FederationConfiguration object set on the FederatedAuthentication.FederationConfiguration property.
Example
The following XML shows a <cookieHandler> element. In this example, because the mode attribute is not specified, the default cookie handler will be used by the SAM. This is an instance of the ChunkedCookieHandler class. Because the <chunkedCookieHandler> child element is not specified, the default chunk size will be used. HTTPS will not be required because the requireSsl attribute is set false.
Warning
In this example, HTTPS is not required to write session cookies. This is because the requireSsl attribute on the <cookieHandler> element is set to false. This setting is not recommended for most production environments as it may present a security risk.
<cookieHandler requireSsl="false" />