📄 SameSite Support Service Documentation
🗂 Table of Contents
- Overview & Purpose
- Key Functional Areas
- Dependencies & Technologies
- Class Diagram (UML)
- Public API: Methods & Signatures
- Error Handling & Return Types
- Usage Examples & Code Snippets
- Third‑Party References & Integration
- Conclusion
🔍 Overview & Purpose
The SameSite Support service provides a way to detect whether a given browser (based on its User-Agent string) supports or breaks cookies with SameSite=None. This is crucial in ASP.NET/ASP.NET Core applications that need to set cross-site cookies correctly, ensuring compatibility across a wide range of browsers and devices.
Why this matters:
Recent browser privacy changes enforce stricter handling of the SameSite attribute, which can lead to unintended logouts or authentication failures in older or non‑standard browser implementations. This helper class helps you:
- Detect incompatible clients (e.g., iOS 12 Safari, old Chrome, UnrealEngine browsers).
- Conditionally apply the
SameSite=None; Secureattribute only when safe.
🔑 Key Functional Areas
| Area | Description |
|---|---|
| Browser Detection Logic | Inspects the User-Agent to determine compatibility with SameSite=None. |
| Compatibility Flags | Offers two flags: |
DisallowsSameSiteNone (true if broken) |
|
AllowsSameSiteNone (inverse). |
|
| Cross‑Platform Considerations | Covers iOS Safari, Mac Safari, Chrome 50–69, UnrealEngine embedded browsers, and more. |
🛠 Dependencies & Technologies
- .NET Standard / .NET Core
- C# 8.0+
- No external NuGet dependencies
- Based on guidance from:
- ASP.NET Core team blog
- Chromium “Incompatible Clients” documentation
📐 Class Diagram (UML)
+-------------------------------------+
| BrowserDetection |«static»
+-------------------------------------+
| + DisallowsSameSiteNone(userAgent) | : bool
| + AllowsSameSiteNone(userAgent) | : bool
+-------------------------------------+
📑 Public API: Methods & Signatures
1. DisallowsSameSiteNone(string userAgent) : bool
Determines if the browser breaks SameSite=None cookies.
/// <summary>
/// Returns true if the user agent is known to *disallow* SameSite=None.
/// </summary>
/// <param name="userAgent">The browser's User-Agent string.</param>
/// <returns>
/// true if the browser is incompatible; false otherwise.
/// </returns>
public static bool DisallowsSameSiteNone(string userAgent)
Logic Highlights
- Null or empty UA → true (safe default).
- iOS 12 browsers (Safari, WKWebView, Chrome) → true.
- MacOS 10.14 Safari → true.
- Chrome 50–69 → true.
- UnrealEngine (pre‑4.23) → true.
2. AllowsSameSiteNone(string userAgent) : bool
The inverse of DisallowsSameSiteNone. Returns true if the browser supports SameSite=None.
/// <summary>
/// Returns true if the user agent supports SameSite=None.
/// </summary>
/// <param name="userAgent">The browser's User-Agent string.</param>
/// <returns>
/// true if the browser is compatible; false otherwise.
/// </returns>
public static bool AllowsSameSiteNone(string userAgent) =>
!DisallowsSameSiteNone(userAgent);
⚙️ Error Handling & Return Types
- Null or Empty UA: Treated as incompatible (returns
truefromDisallowsSameSiteNone), ensuring the application errs on the side of caution. - Return Values:
true→ Browser does not supportSameSite=None.false→ Browser may supportSameSite=None.
There are no exceptions thrown by these methods.
🚀 Usage Examples & Code Snippets
Example 1: Setting Cookie Options in ASP.NET Core
public void Configure(IApplicationBuilder app)
{
app.Use(async (context, next) =>
{
var userAgent = context.Request.Headers["User-Agent"].ToString();
var cookieOptions = new CookieOptions
{
HttpOnly = true,
Secure = true,
// Conditionally apply SameSite=None
SameSite = BrowserDetection.AllowsSameSiteNone(userAgent)
? SameSiteMode.None
: SameSiteMode.Lax
};
context.Response.Cookies.Append("MyAuthCookie", "encrypted-token", cookieOptions);
await next.Invoke();
});
// ... other middleware
}
Example 2: Middleware Extension
public static class CookiePolicyExtensions
{
public static IApplicationBuilder UseSameSiteCookiePolicy(this IApplicationBuilder app)
{
app.Use(async (context, next) =>
{
var ua = context.Request.Headers["User-Agent"].ToString();
context.Response.OnStarting(() =>
{
if (context.Response.Cookies != null)
{
// Adjust each cookie in Response.Cookies as needed...
}
return Task.CompletedTask;
});
await next();
});
return app;
}
}
🔗 Third-Party References & Integration
- 💡 ASP.NET Core Blog: Upcoming SameSite cookie changes
- 📖 Chromium Docs: Incompatible Clients
- 📜 Apache 2.0 License (included in header)
🏁 Conclusion
The SameSiteSupport service—via the BrowserDetection class—provides a simple, zero‑dependency solution to ensure that your cross‑site cookies remain functional across legacy, mobile, and embedded browsers. By integrating these checks into your middleware or cookie‑setting logic, you can gracefully handle browser quirks without sacrificing security or privacy.
Get started by plugging the static helper into your cookie policy pipeline and enjoy consistent behavior across all user agents! 🚀
Document generated for IrbyImaging/Services/SameSiteSupport.cs