Rowan Merewood on web.dev

Migrate to User-Agent Client Hints

2021-05-19T00:00:00Z

The User-Agent string is a significant passive fingerprinting surface in browsers, as well as being difficult to process. However, there are all kinds of valid reasons for collecting and processing user-agent data, so what's needed is a path to a better solution. User-Agent Client Hints provide both an explicit way to declare your need for user-agent data and methods to return the data in an easy-to-use format.

This article will take you through auditing your access to user-agent data and migrating user-agent string usage to User-Agent Client Hints.

Audit collection and use of user-agent data #

As with any form of data collection, you should always understand why you are collecting it. The first step, regardless of whether or not you will be taking any action, is to understand where and why you are using user-agent data.

If you don't know if or where user-agent data is being used, consider searching your front-end code for use of navigator.userAgent and your back-end code for use of the User-Agent HTTP header. You should also check your front-end code for use of already deprecated features, such as navigator.platform and navigator.appVersion.

From a functional point of view, think about anywhere in your code where you are recording or processing:

Browser name or version
Operating system name or version
Device make or model
CPU type, architecture, or bitness (for example, 64-bit)

It's also likely that you may be using a third-party library or service to process the user-agent. In this case, check to see if they are updating to support User-Agent Client Hints.

Are you only using basic user-agent data? #

The default set of User-Agent Client Hints includes:

Sec-CH-UA: browser name and major/significant version
Sec-CH-UA-Mobile: boolean value indicating a mobile device
Sec-CH-UA-Platform: operating system name
- Note that this has been updated in the spec and will be reflected in Chrome and other Chromium-based browsers shortly.

The reduced version of the user-agent string that is proposed will also retain this basic information in a backwards-compatible way. For example, instead of Chrome/90.0.4430.85 the string would include Chrome/90.0.0.0.

If you are only checking the user-agent string for browser name, major version, or operating system, then your code will continue to work though you are likely to see deprecation warnings.

While you can and should migrate to User-Agent Client Hints, you may have legacy code or resource constraints that prevent this. The reduction of information in the user-agent string in this backwards-compatible way is intended to ensure that while existing code will receive less detailed information, it should still retain basic functionality.

Strategy: On-demand client-side JavaScript API #

If you are currently using navigator.userAgent you should transition to preferring navigator.userAgentData before falling back to parsing the user-agent string.

if (navigator.userAgentData) {
  // use new hints
} else {
  // fall back to user-agent string parsing
}

If you are checking for mobile or desktop, use the boolean mobile value:

const isMobile = navigator.userAgentData.mobile;

userAgentData.brands is an array of objects with brand and version properties where the browser is able to list its compatibility with those brands. You can access it directly as an array or you may want to use a some() call to check if a specific entry is present:

function isCompatible(item) {
  // In real life you most likely have more complex rules here
  return ['Chromium', 'Google Chrome', 'NewBrowser'].includes(item.brand);
}
if (navigator.userAgentData.brands.some(isCompatible)) {
  // browser reports as compatible
}

If you need one of the more detailed, high-entropy user-agent values, you will need to specify it and check for the result in the returned Promise:

navigator.userAgentData.getHighEntropyValues(['model'])
  .then(ua => {
    // requested hints available as attributes
    const model = ua.model
  });

You may also want to use this strategy if you would like to move from server-side processing to client-side processing. The JavaScript API does not require access to HTTP request headers, so user-agent values can be requested at any point.

Strategy: Static server-side header #

If you are using the User-Agent request header on the server and your needs for that data are relatively consistent across your entire site, then you can specify the desired client hints as a static set in your responses. This is a relatively simple approach since you generally only need to configure it in one location. For example, it may be in your web server configuration if you already add headers there, your hosting configuration, or top-level configuration of the framework or platform you use for your site.

Consider this strategy if you are transforming or customizing the responses served based on the user-agent data.

Browsers or other clients may choose to supply different default hints, so it's good practice to specify everything you need, even if it's generally provided by default.

For example, the current defaults for Chrome would be represented as:

⬇️ Response headers

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

If you also wanted to receive the device model in responses, then you would send:

⬇️ Response headers

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA

When processing this on the server-side you should first check if the desired Sec-CH-UA header has been sent and then fallback to the User-Agent header parsing if it is not available.

Strategy: Delegating hints to cross-origin requests #

If you are requesting cross-origin or cross-site subresources that require User-Agent Client Hints to be sent on their requests then you will need to explicitly specify the desired hints using a Permissions Policy.

For example, let's say that https://blog.site hosts resources on https://cdn.site which can return resources optimized for a specific device. https://blog.site can ask for the Sec-CH-UA-Model hint, but needs to explicitly delegate it to https://cdn.site using the Permissions-Policy header. The list of policy-controlled hints is available in the Clients Hints Infrastructure draft

⬇️ Response from blog.site delegating the hint

Accept-CH: Sec-CH-UA-Model
Permissions-Policy: ch-ua-model=(self "https://cdn.site")

⬆️ Request to subresources on cdn.site include the delegated hint

Sec-CH-UA-Model: "Pixel 5"

You can specify multiple hints for multiple origins, and not just from the ch-ua range:

⬇️ Response from blog.site delegating multiple hints to multiple origins

Accept-CH: Sec-CH-UA-Model, DPR
Permissions-Policy: ch-ua-model=(self "https://cdn.site"),
                    ch-dpr=(self "https://cdn.site" "https://img.site")

Strategy: Delegating hints to iframes #

Cross-origin iframes work in a similar way to cross-origin resources, but you specify the hints you would like to delegate in the allow attribute.

⬇️ Response from blog.site

Accept-CH: Sec-CH-UA-Model

↪️ HTML for blog.site

<iframe src="https://widget.site" allow="ch-ua-model"></iframe>

⬆️ Request to widget.site

Sec-CH-UA-Model: "Pixel 5"

The allow attribute in the iframe will override any Accept-CH header that widget.site may send itself, so make sure you've specified everything the iframe'd site will need.

Strategy: Dynamic server-side hints #

If you have specific parts of the user journey where you need a larger selection of hints than across the rest of the site, you may choose to request those hints on demand rather than statically across the entire site. This is more complex to manage, but if you already set different headers on a per route basis it may be feasible.

The important thing to remember here is that each instance of the Accept-CH header will effectively overwrite the existing set. So, if you are dynamically setting the header then each page must request the full set of hints required.

For example, you may have one section on your site where you want to provide icons and controls that match the user's operating system. For this, you may want to additionally pull in Sec-CH-UA-Platform-Version to serve appropriate subresources.

⬇️ Response headers for /blog

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

⬇️ Response headers for /app

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA

Strategy: Server-side hints required on first request #

There may be cases where you require more than the default set of hints on the very first request, however this is likely to be rare so make sure you've reviewed the reasoning.

The first request really means the very first top-level request for that origin sent in that browsing session. The default set of hints includes the browser name with major version, the platform, and the mobile indicator. So the question to ask here is, do you require extended data on the initial page load?

For additional hints on the first request there are two options. First, you can make use of the Critical-CH header. This takes the same format as Accept-CH but tells the browser that it should immediately retry the request if the first one was sent without the critical hint.

⬆️ Initial request

[With default headers]

⬇️ Response headers

Accept-CH: Sec-CH-UA-Model
Critical-CH: Sec-CH-UA-Model

🔃 Browser retries initial request with the extra header

[With default headers + …]
Sec-CH-UA-Model: Pixel 5

This will incur the overhead of the retry on the very first request, but the implementation cost is relatively low. Send the extra header and the browser will do the rest.

For situations where you require really do require additional hints on the very first page load, the Client Hints Reliability proposal is laying out a route to specify hints in the connection-level settings. This makes use of the Application-Layer Protocol Settings(ALPS) extension to TLS 1.3 to enable this early passing of hints on HTTP/2 and HTTP/3 connections. This is still at a very early stage, but if you actively manage your own TLS and connection settings then this is an ideal time to contribute.

Strategy: Legacy support #

You may have legacy or third-party code on your site that depends on navigator.userAgent, including portions of the user-agent string that will be reduced. Long-term you should plan to move to the equivalent navigator.userAgentData calls, but there is an interim solution.

UA-CH retrofill is a small library that allows you to overwrite navigator.userAgent with a new string built from the requested navigator.userAgentData values.

For example, this code will generate a user-agent string that additionally includes the "model" hint:

import { overrideUserAgentUsingClientHints } from './uach-retrofill.js';
overrideUserAgentUsingClientHints(['model'])
  .then(() => { console.log(navigator.userAgent); });

The resulting string would show the Pixel 5 model, but still shows the reduced 92.0.0.0 as the uaFullVersion hint was not requested:

Mozilla/5.0 (Linux; Android 10.0; Pixel 5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.0.0 Mobile Safari/537.36

Further support #

If these strategies do not cover your use case, please start a Discussion in privacy-sandbox-dev-support repo and we can explore your issue together.

Photo by Ricardo Rocha on Unsplash

Schemeful Same-Site

2020-11-20T00:00:00Z

Schemeful Same-Site modifies the definition of a (web)site from just the registrable domain to the scheme + registrable domain. You can find more details and examples in Understanding "same-site" and "same-origin".

The good news is: if your website is already fully upgraded to HTTPS then you don't need to worry about anything. Nothing will change for you.

If you haven't fully upgraded your website yet then this should be the priority. However, if there are cases where your site visitors will go between HTTP and HTTPS then some of those common scenarios and the associated SameSite cookie behavior are outlined below.

You can enable these changes for testing in both Chrome and Firefox.

From Chrome 86, enable about://flags/#schemeful-same-site. Track progress on the Chrome Status page.
From Firefox 79, set network.cookie.sameSite.schemeful to true via about:config. Track progress via the Bugzilla issue.

One of the main reasons for the change to SameSite=Lax as the default for cookies was to protect against Cross-Site Request Forgery (CSRF). However, insecure HTTP traffic still presents an opportunity for network attackers to tamper with cookies that will then be used on the secure HTTPS version of the site. Creating this additional cross-site boundary between schemes provides further defense against these attacks.

Common cross-scheme scenarios #

Navigating between cross-scheme versions of a website (for example, linking from http://site.example to https://site.example) would previously allow SameSite=Strict cookies to be sent. This is now treated as a cross-site navigation which means SameSite=Strict cookies will be blocked.

Cross-scheme navigation from HTTP to HTTPS.

	HTTP → HTTPS	HTTPS → HTTP
`SameSite=Strict`	⛔ Blocked	⛔ Blocked
`SameSite=Lax`	✓ Allowed	✓ Allowed
`SameSite=None;Secure`	✓ Allowed	⛔ Blocked

Loading subresources #

Any changes you make here should only be considered a temporary fix while you work to upgrade to full HTTPS.

Examples of subresources include images, iframes, and network requests made with XHR or Fetch.

Loading a cross-scheme subresource on a page would previously allow SameSite=Strict or SameSite=Lax cookies to be sent or set. Now this is treated the same way as any other third-party or cross-site subresource which means that any SameSite=Strict or SameSite=Lax cookies will be blocked.

Additionally, even if the browser does allow resources from insecure schemes to be loaded on a secure page, all cookies will be blocked on these requests as third-party or cross-site cookies require Secure.

An HTTP page including a cross-scheme subresource via HTTPS.

	HTTP → HTTPS	HTTPS → HTTP
`SameSite=Strict`	⛔ Blocked	⛔ Blocked
`SameSite=Lax`	⛔ Blocked	⛔ Blocked
`SameSite=None;Secure`	✓ Allowed	⛔ Blocked

POSTing a form #

Posting between cross-scheme versions of a website would previously allow cookies set with SameSite=Lax or SameSite=Strict to be sent. Now this is treated as a cross-site POST—only SameSite=None cookies can be sent. You may encounter this scenario on sites that present the insecure version by default, but upgrade users to the secure version on submission of the sign-in or check-out form.

As with subresources, if the request is going from a secure, e.g. HTTPS, to an insecure, e.g. HTTP, context then all cookies will be blocked on these requests as third-party or cross-site cookies require Secure.

Cross-scheme form submission from HTTP to HTTPS.

	HTTP → HTTPS	HTTPS → HTTP
`SameSite=Strict`	⛔ Blocked	⛔ Blocked
`SameSite=Lax`	⛔ Blocked	⛔ Blocked
`SameSite=None;Secure`	✓ Allowed	⛔ Blocked

How can I test my site? #

Developer tooling and messaging are available in Chrome and Firefox.

From Chrome 86, the Issue tab in DevTools will include Schemeful Same-Site issues. You may see the following issues highlighted for your site.

Navigation issues:

"Migrate entirely to HTTPS to continue having cookies sent on same-site requests"—A warning that the cookie will be blocked in a future version of Chrome.
"Migrate entirely to HTTPS to have cookies sent on same-site requests"—A warning that the cookie has been blocked.

Subresource loading issues:

"Migrate entirely to HTTPS to continue having cookies sent to same-site subresources" or "Migrate entirely to HTTPS to continue allowing cookies to be set by same-site subresources"—Warnings that the cookie will be blocked in a future version of Chrome.
"Migrate entirely to HTTPS to have cookies sent to same-site subresources" or "Migrate entirely to HTTPS to allow cookies to be set by same-site subresources"—Warnings that the cookie has been blocked. The latter warning can also appear when POSTing a form.

More detail is available in Testing and Debugging Tips for Schemeful Same-Site.

From Firefox 79, with network.cookie.sameSite.schemeful set to true via about:config the console will display message for Schemeful Same-Site issues. You may see the following on your site:

"Cookie cookie_name will be soon treated as cross-site cookie against http://site.example/ because the scheme does not match."
"Cookie cookie_name has been treated as cross-site against http://site.example/ because the scheme does not match."

FAQ #

My site is already fully available on HTTPS, why am I seeing issues in my browser's DevTools? #

It's possible that some of your links and subresources still point to insecure URLs.

One way to fix this issue is to use HTTP Strict-Transport-Security (HSTS) and the includeSubDomain directive. With HSTS + includeSubDomain even if one of your pages accidentally includes an insecure link the browser will automatically use the secure version instead.

What if I can't upgrade to HTTPS? #

While we strongly recommend that you upgrade your site entirely to HTTPS to protect your users, if you're unable to do so yourself we suggest speaking with your hosting provider to see if they can offer that option. If you self-host, then Let's Encrypt provides a number of tools to install and configure a certificate. You can also investigate moving your site behind a CDN or other proxy that can provide the HTTPS connection.

If that's still not possible then try relaxing the SameSite protection on affected cookies.

In cases where only SameSite=Strict cookies are being blocked you can lower the protection to Lax.
In cases where both Strict and Lax cookies are being blocked and your cookies are being sent to (or set from) a secure URL you can lower the protections to None.
- This workaround will fail if the URL you're sending cookies to (or setting them from) is insecure. This is because SameSite=None requires the Secure attribute on cookies which means those cookies may not be sent or set over an insecure connection. In this case you will be unable to access that cookie until your site is upgraded to HTTPS.
- Remember, this is only temporary as eventually third-party cookies will be phased out entirely.

How does this affect my cookies if I haven't specified a `SameSite` attribute? #

Cookies without a SameSite attribute are treated as if they specified SameSite=Lax and the same cross-scheme behavior applies to these cookies as well. Note that the temporary exception to unsafe methods still applies, see the Lax + POST mitigation in the Chromium SameSite FAQ for more information.

How are WebSockets affected? #

WebSocket connections will still be considered same-site if they're the same secureness as the page.

Same-site:

wss:// connection from https://
ws:// connection from http://

Cross-site:

wss:// connection from http://
ws:// connection from https://

Photo by Julissa Capdevilla on Unsplash

Understanding cookies

2019-10-30T00:00:00Z

A cookie is a small file that websites store on their users’ machine, the information it stores travels back and forth between the browser and the website.

Each cookie is a key-value pair along with a number of attributes that control when and where that cookie is used. These attributes are used to set things like expiration dates or indicating the cookie should only be sent over HTTPS. You can set a cookie in an HTTP header or through JavaScript interface.

Cookies are one of the methods available for adding persistent state to web sites. Over the years their capabilities have grown and evolved, but left the platform with some problematic legacy issues. To address this, browsers (including Chrome, Firefox, and Edge) are changing their behavior to enforce more privacy-preserving defaults.

Cookies in action #

Say you have a blog where you want to display a "What's new" promo to your users. Users can dismiss the promo and then they won't see it again for a while. You can store that preference in a cookie, set it to expire in a month (2,600,000 seconds), and only send it over HTTPS. That header would look like this:

Set-Cookie: promo_shown=1; Max-Age=2600000; Secure

Servers set cookies using the Set-Cookie header.

When your reader views a page that meets those requirements—they're on a secure connection and the cookie is less than a month old—their browser will send this header in its request:

Cookie: promo_shown=1

Your browser sends cookies back in the Cookie header.

You can also add and read the cookies available to that site in JavaScript using document.cookie. Making an assignment to document.cookie will create or override a cookie with that key. For example, you can try the following in your browser's JavaScript console:

→ document.cookie = "promo_shown=1; Max-Age=2600000; Secure"
← "promo_shown=1; Max-Age=2600000; Secure"

Reading document.cookie will output all the cookies accessible in the current context, with each cookie separated by a semicolon:

→ document.cookie;
← "promo_shown=1; color_theme=peachpuff; sidebar_loc=left"

JavaScript can access cookies using document.cookie.

If you try this on a selection of popular sites you will notice that most of them set significantly more than just three cookies. In most cases, those cookies are sent on every single request to that domain, which has a number of implications. Upload bandwidth is often more restricted than download for your users, so that overhead on all outbound requests is adding a delay on your time to first byte. Be conservative in the number and size of cookies you set. Make use of the Max-Age attribute to help ensure that cookies don't hang around longer than needed.

What are first-party and third-party cookies? #

If you go back to that same selection of sites you were looking at before, you probably noticed that there were cookies present for a variety of domains, not just the one you were currently visiting. Cookies that match the domain of the current site, that is, what's displayed in the browser's address bar, are referred to as first-party cookies. Similarly, cookies from domains other than the current site are referred to as third-party cookies. This isn't an absolute label but is relative to the user's context; the same cookie can be either first-party or third-party depending on which site the user is on at the time.

Cookies may come from a variety of different domains on one page.

Continuing the example from above, let's say one of your blog posts has a picture of a particularly amazing cat in it and it's hosted at /blog/img/amazing-cat.png. Because it's such an amazing image, another person uses it directly on their site. If a visitor has been to your blog and has the promo_shown cookie, then when they view amazing-cat.png on the other person's site that cookie will be sent in that request for the image. This isn't particularly useful for anyone since promo_shown isn't used for anything on this other person's site, it's just adding overhead to the request.

If that's an unintended effect, why would you want to do this? It's this mechanism that allows sites to maintain state when they are being used in a third-party context. For example, if you embed a YouTube video on your site then visitors will see a "Watch later" option in the player. If your visitor is already signed in to YouTube, that session is being made available in the embedded player by a third-party cookie—meaning that "Watch later" button will just save the video in one go rather than prompting them to sign in or having to navigate them away from your page and back over to YouTube.

A cookie in a third-party context is sent when visiting different pages.

One of the cultural properties of the web is that it's tended to be open by default. This is part of what has made it possible for so many people to create their own content and apps there. However, this has also brought a number of security and privacy concerns. Cross-site request forgery (CSRF) attacks rely on the fact that cookies are attached to any request to a given origin, no matter who initiates the request. For example, if you visit evil.example then it can trigger requests to your-blog.example, and your browser will happily attach the associated cookies. If your blog isn't careful with how it validates those requests then evil.example could trigger actions like deleting posts or adding their own content.

Users are also becoming more aware of how cookies can be used to track their activity across multiple sites. However until now there hasn't been a way to explicitly state your intent with the cookie. Your promo_shown cookie should only be sent in a first-party context, whereas a session cookie for a widget meant to be embedded on other sites is intentionally there for providing the signed-in state in a third-party context.

You can explicitly state your intent with a cookie by setting the appropriate SameSite attribute.

To identify your first-party cookies and set appropriate attributes, check out First-party cookie recipes.

SameSite cookie recipes

2019-10-30T00:00:00Z

Chrome, Firefox, Edge, and others will be changing their default behavior in line with the IETF proposal, Incrementally Better Cookies so that:

Cookies without a SameSite attribute will be treated as SameSite=Lax, meaning the default behavior will be to restrict cookies to first party contexts only.
Cookies for cross-site usage must specify SameSite=None; Secure to enable inclusion in third party context.

This feature is the default behavior from Chrome 84 stable onward. If you have not already done so, you should update the attributes for your third-party cookies so they will not be blocked in the future.

Cross-browser support #

See the Browser compatibility section of MDN's Set-Cookie page.

Use cases for cross-site or third-party cookies #

There are a number of common use cases and patterns where cookies need to be sent in a third-party context. If you provide or depend on one of these use cases, ensure that either you or the provider are updating their cookies to ensure the service continues to function correctly.

Content within an `<iframe>` #

Content from a different site displayed in an <iframe> is in a third-party context. Standard use cases here are:

Embedded content shared from other sites, such as videos, maps, code samples, and social posts.
Widgets from external services such as payments, calendars, booking, and reservation functionality.
Widgets such as social buttons or anti-fraud services that create less obvious <iframes>.

Cookies may be used here to, among other things, maintain session state, store general preferences, enable statistics, or personalize content for users with existing accounts.

If the embedded content doesn't come from the same site as the top-level browsing context, it's third-party content.

Additionally, as the web is inherently composable, <iframes> are used to embed content that is also viewed in a top-level or first-party context. Any cookies used by that site will be considered as third-party cookies when the site is displayed within the frame. If you're creating sites that you intend to be easily embedded by others while also relying on cookies to function, you will also need to ensure those are marked for cross-site usage or that you can gracefully fallback without them.

"Unsafe" requests across sites #

While "unsafe" may sound slightly concerning here, this refers to any request that may be intended to change state. On the web that's primarily POST requests. Cookies marked as SameSite=Lax will be sent on safe top-level navigations, e.g. clicking a link to go to a different site. However something like a <form> submission via POST to a different site would not include cookies.

If the incoming request uses a "safe" method then the cookies will be sent.

This pattern is used for sites that may redirect the user out to a remote service to perform some operation before returning, for example redirecting to a third-party identity provider. Before the user leaves the site, a cookie is set containing a single use token with the expectation that this token can be checked on the returning request to mitigate Cross Site Request Forgery (CSRF) attacks. If that returning request comes via POST then it will be necessary to mark the cookies as SameSite=None; Secure.

Remote resources #

Any remote resource on a page may be relying on cookies to be sent with a request, from <img> tags, <script> tags, and so on. Common use cases include tracking pixels and personalizing content.

This also applies to requests initiated from your JavaScript by fetch or XMLHttpRequest. If fetch() is called with the credentials: 'include' option this is a good indication that cookies may well be expected on those requests. For XMLHttpRequest you should look for instances of the withCredentials property being set to true. This is a good indication that cookies may well be expected on those requests. Those cookies will need to be appropriately marked to be included in cross-site requests.

Content within a WebView #

A WebView in a platform-specific app is powered by a browser and you will need to test if the same restrictions or issues apply. In Android, if the WebView is powered by Chrome the new defaults will not immediately be applied with Chrome 84. However the intent is to apply them in the future, so you should still test and prepare for this. Additionally, Android allows its platform-specific apps to set cookies directly via the CookieManager API. As with cookies set via headers or JavaScript, consider including SameSite=None; Secure if they are intended for cross-site use.

How to implement `SameSite` today #

For cookies where they are only needed in a first-party context you should ideally mark them as SameSite=Lax or SameSite=Strict depending on your needs. You can also choose to do nothing and just allow the browser to enforce its default, but this comes with the risk of inconsistent behavior across browsers and potential console warnings for each cookie.

Set-Cookie: first_party_var=value; SameSite=Lax

For cookies needed in a third-party context, you will need to ensure they are marked as SameSite=None; Secure. Note that you need both attributes together. If you just specify None without Secure the cookie will be rejected. There are some mutually incompatible differences in browser implementations though, so you may need to use some of the mitigating strategies described in Handling incompatible clients below.

Set-Cookie: third_party_var=value; SameSite=None; Secure

Handling incompatible clients #

As these changes to include None and update default behavior are still relatively new, there are inconsistencies amongst browsers as to how these changes are handled. You can refer to the updates page on chromium.org for the issues currently known, however it's not possible to say if this is exhaustive. While this is not ideal, there are workarounds you can employ during this transitionary phase. The general rule though is to treat incompatible clients as the special case. Do not create an exception for browsers implementing the newer rules.

The first option is to set both the new and old style cookies:

Set-cookie: 3pcookie=value; SameSite=None; Secure
Set-cookie: 3pcookie-legacy=value; Secure

Browsers implementing the newer behavior will set the cookie with the SameSite value, while other browsers may ignore or incorrectly set it. However, those same browsers will set the 3pcookie-legacy cookie. When processing included cookies, the site should first check for the presence of the new style cookie and if it's not found, then fallback to the legacy cookie.

The example below shows how to do this in Node.js, making use of the Express framework and its cookie-parser middleware.

const express = require('express');
const cp = require('cookie-parser');
const app = express();
app.use(cp());

app.get('/set', (req, res) => {
  // Set the new style cookie
  res.cookie('3pcookie', 'value', { sameSite: 'none', secure: true });
  // And set the same value in the legacy cookie
  res.cookie('3pcookie-legacy', 'value', { secure: true });
  res.end();
});

app.get('/', (req, res) => {
  let cookieVal = null;

  if (req.cookies['3pcookie']) {
    // check the new style cookie first
    cookieVal = req.cookies['3pcookie'];
  } else if (req.cookies['3pcookie-legacy']) {
    // otherwise fall back to the legacy cookie
    cookieVal = req.cookies['3pcookie-legacy'];
  }

  res.end();
});

app.listen(process.env.PORT);

The downside is that this involves setting redundant cookies to cover all browsers and requires making changes both at the point of setting and reading the cookie. However, this approach should cover all browsers regardless of their behavior and ensure third-party cookies continue to function as before.

Alternatively at the point of sending the Set-Cookie header, you can choose to detect the client via the user agent string. Refer to the list of incompatible clients and then make use of an appropriate library for your platform, for example ua-parser-js library on Node.js. It's advisable to find a library to handle user agent detection as you most probably don't want to write those regular expressions yourself.

The benefit of this approach is that it only requires making one change at the point of setting the cookie. However, the necessary warning here is that user agent sniffing is inherently fragile and may not catch all of the affected users.

Support for `SameSite=None` in languages, libraries, and frameworks #

The majority of languages and libraries support the SameSite attribute for cookies, however the addition of SameSite=None is still relatively new which means that you may need to work around some of the standard behavior for now. These are documented in the SameSite examples repo on GitHub.

Getting help #

Cookies are all over the place and it's rare for any site to have completely audited where they're set and used, especially once you throw cross-site use cases in the mix. When you encounter an issue, it may well be the first time anyone has encountered it - so don't hesitate to reach out:

Raise an issue on the SameSite examples repo on GitHub.
blog a question on the "samesite" tag on StackOverflow.
For issues with Chromium's behavior, raise a bug via the [SameSite cookies] issue template.
Follow Chrome's progress on the SameSite updates page.

SameSite cookies explained

2019-05-07T00:00:00Z

Each cookie contains a key-value pair along with a number of attributes that control when and where that cookie is used.

The introduction of the SameSite attribute (defined in RFC6265bis) allows you to declare if your cookie should be restricted to a first-party or same-site context. It's helpful to understand exactly what 'site' means here. The site is the combination of the domain suffix and the part of the domain just before it. For example, the www.web.dev domain is part of the web.dev site.

The public suffix list defines this, so it's not just top-level domains like .com but also includes services like github.io. That enables your-project.github.io and my-project.github.io to count as separate sites.

Explicitly state cookie usage with the `SameSite` attribute #

Introducing the SameSite attribute on a cookie provides three different ways to control this behaviour. You can choose to not specify the attribute, or you can use Strict or Lax to limit the cookie to same-site requests.

If you set SameSite to Strict, your cookie will only be sent in a first-party context. In user terms, the cookie will only be sent if the site for the cookie matches the site currently shown in the browser's URL bar. So, if the promo_shown cookie is set as follows:

Set-Cookie: promo_shown=1; SameSite=Strict

When the user is on your site, then the cookie will be sent with the request as expected. However when following a link into your site, say from another site or via an email from a friend, on that initial request the cookie will not be sent. This is good when you have cookies relating to functionality that will always be behind an initial navigation, such as changing a password or making a purchase, but is too restrictive for promo_shown. If your reader follows the link into the site, they want the cookie sent so their preference can be applied.

That's where SameSite=Lax comes in by allowing the cookie to be sent with these top-level navigations. Let's revisit the cat article example from above where another site is referencing your content. They make use of your photo of the cat directly and provide a link through to your original article.

<p>Look at this amazing cat!</p>
<img src="https://blog.example/blog/img/amazing-cat.png" />
<p>Read the <a href="https://blog.example/blog/cat.html">article</a>.</p>

And the cookie has been set as so:

Set-Cookie: promo_shown=1; SameSite=Lax

When the reader is on the other person's blog the cookie will not be sent when the browser requests amazing-cat.png. However when the reader follows the link through to cat.html on your blog, that request will include the cookie. This makes Lax a good choice for cookies affecting the display of the site with Strict being useful for cookies related to actions your user is taking.

Finally there is the option of not specifying the value which has previously been the way of implicitly stating that you want the cookie to be sent in all contexts. In the latest draft of RFC6265bis this is being made explicit by introducing a new value of SameSite=None. This means you can use None to clearly communicate that you intentionally want the cookie sent in a third-party context.

Explicitly mark the context of a cookie as None, Lax, or Strict.

Changes to the default behavior without SameSite #

While the SameSite attribute is widely supported, it has unfortunately not been widely adopted by developers. The open default of sending cookies everywhere means all use cases work but leaves the user vulnerable to CSRF and unintentional information leakage. To encourage developers to state their intent and provide users with a safer experience, the IETF proposal, Incrementally Better Cookies lays out two key changes:

Cookies without a SameSite attribute will be treated as SameSite=Lax.
Cookies with SameSite=None must also specify Secure, meaning they require a secure context.

Chrome implements this default behavior as of version 84. Firefox has them available to test as of Firefox 69 and will make them default behaviors in the future. To test these behaviors in Firefox, open about:config and set network.cookie.sameSite.laxByDefault. Edge also plans to change its default behaviors.

`SameSite=Lax` by default #

No attribute set

Set-Cookie: promo_shown=1

If you send a cookie without any SameSite attribute specified…

Default behavior applied

Set-Cookie: promo_shown=1; SameSite=Lax

The browser will treat that cookie as if SameSite=Lax was specified.

While this is intended to apply a more secure default, you should ideally set an explicit SameSite attribute rather than relying on the browser to apply that for you. This makes your intent for the cookie explicit and improves the chances of a consistent experience across browsers.

`SameSite=None` must be secure #

Rejected

Set-Cookie: widget_session=abc123; SameSite=None

Setting a cookie without Secure will be rejected.

Accepted

Set-Cookie: widget_session=abc123; SameSite=None; Secure

You must ensure that you pair SameSite=None with the Secure attribute.

You can test this behavior as of Chrome 76 by enabling about://flags/#cookies-without-same-site-must-be-secure and from Firefox 69 in about:config by setting network.cookie.sameSite.noneRequiresSecure.

You will want to apply this when setting new cookies and actively refresh existing cookies even if they are not approaching their expiry date.

Both of these changes are backwards-compatible with browsers that have correctly implemented the previous version of the SameSite attribute, or just do not support it at all. By applying these changes to your cookies, you are making their intended use explicit rather than relying on the default behavior of the browser. Likewise, any clients that do not recognize SameSite=None as of yet should ignore it and carry on as if the attribute was not set.

`SameSite` cookie recipes #

For further detail on exactly how to update your cookies to successfully handle these changes to SameSite=None and the difference in browser behavior, head to the follow up article, SameSite cookie recipes.

Kind thanks for contributions and feedback from Lily Chen, Malte Ubl, Mike West, Rob Dodson, Tom Steiner, and Vivek Sekhar

Cookie hero image by Pille-Riin Priske on Unsplash

Rowan Merewood on web.dev

Migrate to User-Agent Client Hints

Audit collection and use of user-agent data #

Are you only using basic user-agent data? #

Strategy: On-demand client-side JavaScript API #

Strategy: Static server-side header #

Strategy: Delegating hints to cross-origin requests #

Strategy: Delegating hints to iframes #

Strategy: Dynamic server-side hints #

Strategy: Server-side hints required on first request #

Strategy: Legacy support #

Further support #

Schemeful Same-Site

Common cross-scheme scenarios #

Navigation #

Loading subresources #

POSTing a form #

How can I test my site? #

FAQ #

My site is already fully available on HTTPS, why am I seeing issues in my browser's DevTools? #

What if I can't upgrade to HTTPS? #

How does this affect my cookies if I haven't specified a SameSite attribute? #

How are WebSockets affected? #

Understanding cookies

Cookies in action #

What are first-party and third-party cookies? #

SameSite cookie recipes

Cross-browser support #

Use cases for cross-site or third-party cookies #

Content within an <iframe> #

"Unsafe" requests across sites #

Remote resources #

Content within a WebView #

How to implement SameSite today #

Handling incompatible clients #

Support for SameSite=None in languages, libraries, and frameworks #

Getting help #

SameSite cookies explained

Explicitly state cookie usage with the SameSite attribute #

Changes to the default behavior without SameSite #

SameSite=Lax by default #

SameSite=None must be secure #

SameSite cookie recipes #

How does this affect my cookies if I haven't specified a `SameSite` attribute? #

Content within an `<iframe>` #

How to implement `SameSite` today #

Support for `SameSite=None` in languages, libraries, and frameworks #

Explicitly state cookie usage with the `SameSite` attribute #

`SameSite=Lax` by default #

`SameSite=None` must be secure #

`SameSite` cookie recipes #