<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" />  

See also

• CookieHandler
• ChunkedCookieHandler
• SessionAuthenticationModule