📄 SameSite Support Service Documentation


🗂 Table of Contents

  1. Overview & Purpose
  2. Key Functional Areas
  3. Dependencies & Technologies
  4. Class Diagram (UML)
  5. Public API: Methods & Signatures
  6. Error Handling & Return Types
  7. Usage Examples & Code Snippets
  8. Third‑Party References & Integration
  9. 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; Secure attribute 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 true from DisallowsSameSiteNone), ensuring the application errs on the side of caution.
  • Return Values:
    • true → Browser does not support SameSite=None.
    • false → Browser may support SameSite=None.

There are no exceptions thrown by these methods.


🚀 Usage Examples & Code Snippets

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


🏁 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