---
title: Configuring cookie SameSite mode
related:
- https://docs.kentico.com/13/developing-websites/working-with-cookies.md
- https://docs.kentico.com/13/developing-websites/working-with-cookies/reference-xperience-cookies.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
SameSite is an attribute that is used to control browser behavior when sending cookies. Using the attribute, you can configure whether cookies are sent along with requests initiated by third party websites. This is mainly useful for mitigating [cross-site request forgery](https://owasp.org/www-community/attacks/csrf) attacks.
The _SameSite_ attribute enforces three levels of strictness:
- **Strict** – cookies marked as _Strict_ are only sent as part of same-site requests. In other words, each cookie is only sent if the request URL matches the domain set in the cookie.
- **Lax** – cookies marked as _Lax_ are sent as part of same-site requests and during requests that cause top-level navigation (change the URL in the browser's address bar) to the cookie's domain from a third-party site.
- **None** – _None_ enforces no cross-domain restrictions when sending cookies. However, each cookie needs to be paired with the _Secure_ attribute, which ensures it will only be sent if transmitted over a secure channel (typically using HTTPS). _SameSite=None_ cookies without the _Secure_ attribute are not included in regular requests.
> **Tip:** For an in-depth explanation of the _SameSite_ attribute, its associated modes, and resulting browser behavior, refer to the following article: [SameSite cookies explained](https://web.dev/samesite-cookies-explained/)
## Consequences for Xperience sites
An Xperience site consists of two applications – a front-end site used to present content and a corresponding administration application used to manage and configure the system. For the most part, both applications act completely independently and only communicate via a shared database. However, the [page preview mode](https://docs.kentico.com/13/developing-websites/retrieving-content/adding-preview-mode-support.md) feature, used by the Xperience administration to preview content from the live site application, relies on certain cookies transmitted between the two applications to work correctly.
To use the preview mode and other features that build upon this functionality (such as the [page builder](https://docs.kentico.com/13/developing-websites/page-builder-development.md)), you need to ensure the system and its hosting environment conform to the requirements imposed by _SameSite_. Depending on your environment, you may need to:
- Adjust the configuration of your hosting environment to ensure cookies between the two applications are sent correctly.
- Accordingly configure the _SameSite_ mode for any custom cookies used in your projects.
There are two main hosting configurations to consider, determined by the number of domains used to host your live site and administration. Each configuration comes with specific requirements summarized by the following diagram:
See the following sections for details:
- [Both applications running on a single domain](#single-domain-environment)
- [Each application running on a different domain](#multi-domain-environment)
## Single-domain environment
By default, the system sends all registered cookies using _SameSite=Lax_. If both the live site and administration applications run on a single domain, no additional configuration is necessary.
In the context of _SameSite_, a single domain is classified as:
- Any unique name registered directly under a top-level domain. For example, _sub.domain.com_ and _domain.com_ are recognized as belonging to a single domain. However, _domain.com_ and _microsoft.com_ are recognized as different domains. The same applies to port numbers – _domain.com:8080_ and _domain.com:8081_ are classified as different.
- A domain registered directly under a single _public suffix_. Such suffixes are aggregated into [lists](https://en.wikipedia.org/wiki/Public_Suffix_List) used by browsers when determining request origin. The most popular list of public suffixes used by the majority of browsers is maintained by the Mozilla Corporation and can be found [here](https://publicsuffix.org/list/). For example, _sub.mysite.github.io_ and _mysite.github.io_ are recognized as belonging to a single domain (_github.io_ is a known public suffix). However, _mysite.github.io_ and _yoursite.github.io_ are recognized as different domains.
Requests targeting domains that do not fulfill these specified criteria are classified as cross-domain (and require appropriate _SameSite_ configuration).
> **Info:** **Custom cookies**
>
> This section describes the behavior of default system cookies. Custom cookies used by the application are completely under your control. See [Working with cookies](https://docs.kentico.com/13/developing-websites/working-with-cookies.md) to learn how to set cookies with the desired _SameSite_ attributes using the Xperience API.
If you need to change the default _SameSite_ mode for specific system cookies (for example, you wish to enforce the _Strict_ mode), see [changing the SameSite of Xperience cookies](#changing-the-samesite-of-xperience-cookies).
## Multi-domain environment
In cases where the live site and administration applications are hosted on separate domains, requests between the two applications are classified as cross-domain. As a result, system cookies **must** be sent using _SameSite=None_ and paired with the _Secure_ attribute.
If your browser blocks third-party cookies, the system cookies must also be paired with the [Partitioned](https://developers.google.com/privacy-sandbox/3pcd/chips) attribute.
Cookies are essential for all system features based on the [preview mode](https://docs.kentico.com/13/developing-websites/retrieving-content/adding-preview-mode-support.md), such as the [page builder](https://docs.kentico.com/13/developing-websites/page-builder-development.md) or page [preview links](https://docs.kentico.com/13/managing-website-content/working-with-pages/sending-links-to-unpublished-pages.md). Under preview mode, the Xperience administration communicates directly with the live site application via special virtual context requests (containing contextual information about the requested page and validation hashes), which rely on specific cookies on the client.
> **Info:** **Note:** If your site does not use the [preview mode](https://docs.kentico.com/13/developing-websites/retrieving-content/adding-preview-mode-support.md) or any dependent features, you do not need to configure system cookies in any way.
**ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block.
Enable sending of application cookies under _SameSite=None_ by adding the **SetAdminCookiesSameSiteNone** call after _IServiceCollection.AddKentico_ in the **ConfigureServices** method of your application's startup class:
```csharp
public void ConfigureServices(IServiceCollection services)
{
services.AddKentico()
// Required when hosting the administration application and the live site on different domains.
// Sets the 'SameSite' attribute of system cookies to 'None' and pairs them with the 'Secure' and 'Partitioned' attributes
// when sent under preview mode. Both applications also need to use a secure connection (HTTPS)
// to ensure the cookies are not rejected.
.SetAdminCookiesSameSiteNone();
...
}
```
**MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block.
Enable sending of application cookies under _SameSite=None_ by adding the **CMSAdminCookiesSameSiteNone** key with the **true** value to your MVC application's _web.config_ file:
```xml
```
Additionally, **both** the applications that comprise a single Xperience site need to use a **secure connection** (HTTPS) to ensure the cookies are not rejected on the client.
> **Info:** **Custom cookies**
>
> This section describes the behavior of default system cookies. Custom cookies used by the application are completely under your control. See [Working with cookies](https://docs.kentico.com/13/developing-websites/working-with-cookies.md) to learn how to set cookies with the desired _SameSite_ attributes using the Xperience API.
If you need to change the default _SameSite_ mode for specific system cookies (for example, you wish to enforce the _Strict_ mode), see [changing the SameSite of Xperience cookies](#changing-the-samesite-of-xperience-cookies).
## Changing the SameSite of Xperience cookies
**ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block.
You can modify cookies by assigning a delegate to the **OnAppendCookie** property of **CookiePolicyOptions**. The delegate is invoked for each cookie added to requests. For this approach to work, the cookie policy middleware ([UseCookiePolicy](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/cookie#cookie-policy-middleware)) needs to be registered in the application's [middleware pipeline](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/starting-with-asp-net-core-development.md).
```csharp
public void ConfigureServices(IServiceCollection services)
{
...
services.Configure(o =>
{
o.OnAppendCookie = c =>
{
// Sets the 'SameSite' attribute of the CMSShoppingCart cookie to 'None' and pairs it with the 'Secure' attribute.
// Note that the request needs to be sent encrypted (typically using HTTPS) when using this configuration.
// Otherwise, the cookie is discarded by the browser.
if (c.CookieName == "CMSShoppingCart")
{
c.CookieOptions.SameSite = SameSiteMode.None;
c.CookieOptions.Secure = true;
}
};
});
}
```
**MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block.
You can register a custom handler for the **PreSendRequestHeaders** event. Inside the handler, you can access and modify [system cookies](https://docs.kentico.com/13/developing-websites/working-with-cookies/reference-xperience-cookies.md) sent as part of each request via the **CMSHttpContext**class.
The following example uses a custom [code-only module](https://docs.kentico.com/13/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md) to register a new handler for the _PreSendRequestHeaders_ event. The handler sets the _SameSite_ mode of a selected cookie to _None_ and adds the _Secure_ attribute.
```csharp
using System;
using CMS;
using CMS.Base;
using CMS.DataEngine;
using CMS.Helpers;
// Registers the custom module into the system
[assembly: RegisterModule(typeof(RegisterHandlers))]
public class RegisterHandlers : Module
{
public RegisterHandlers()
: base("RegisterHandlers")
{
}
// Contains initialization code that is executed when the application starts
protected override void OnInit()
{
base.OnInit();
// Registers an event handler for the PreSendRequestHeaders event
RequestEvents.PreSendRequestHeaders.Execute += ModifySameSiteCookieMode;
}
public void ModifySameSiteCookieMode(object sender, EventArgs e)
{
// Sets the 'SameSite' attribute of the CMSShoppingCart cookie to 'None' and pairs it with the 'Secure' attribute
// Note that the request needs to be sent encrypted (typically using HTTPS) when using this configuration.
// Otherwise, the cookie is discarded by the browser.
CMSHttpContext.Current.Request.Cookies["CMSShoppingCart"].SameSite = CMS.Base.SameSiteMode.None;
CMSHttpContext.Current.Request.Cookies["CMSShoppingCart"].Secure = true;
}
}
```