faysilalshareef/cors-configuration

CORS Configuration

Core Principles

• Least privilege: only allow the origins, methods, and headers your clients actually need
• Explicit origins: list specific origins instead of wildcards — AllowAnyOrigin() disables the browser's same-origin protection
• Never wildcard with credentials: the CORS spec forbids Access-Control-Allow-Origin: * when Access-Control-Allow-Credentials: true — browsers will block the response
• Defense in depth: CORS is a browser-enforced mechanism, not a server-side security boundary — always validate and authorize on the server regardless
• Middleware order matters: UseCors() must appear after UseRouting() and before UseAuthentication() / UseAuthorization()

When to Use

• Your API is consumed by a browser-based SPA hosted on a different origin
• You expose public endpoints that third-party front-ends call
• Your development server runs on a different port than the API (e.g., Vite on :5173, API on :5000)
• You need to allow cross-origin file uploads or custom headers

When NOT to Use

• Server-to-server communication (CORS is browser-only; it adds no value)
• Your SPA and API share the same origin (same scheme + host + port)
• You use a reverse proxy / API gateway that already handles CORS headers before traffic reaches .NET
• Mobile apps or desktop clients (they do not enforce CORS)

Patterns

Basic Setup

// Program.cs
builder.Services.AddCors(options =>
{
    options.AddDefaultPolicy(policy =>
    {
        policy
            .WithOrigins("https://app.example.com")
            .WithMethods("GET", "POST", "PUT", "DELETE")
            .WithHeaders("Content-Type", "Authorization");
    });
});

var app = builder.Build();

app.UseRouting();
app.UseCors();          // after UseRouting, before UseAuth
app.UseAuthentication();
app.UseAuthorization();

Named Policies

Use named policies when different endpoint groups need different CORS rules.

builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowSPA", policy =>
        policy
            .WithOrigins(
                "https://app.example.com",
                "https://staging.example.com")
            .WithMethods("GET", "POST", "PUT", "DELETE")
            .WithHeaders(
                "Content-Type",
                "Authorization",
                "X-Request-Id"));

    options.AddPolicy("AllowReporting", policy =>
        policy
            .WithOrigins("https://reports.example.com")
            .WithMethods("GET")
            .WithHeaders("Authorization"));

    options.AddPolicy("AllowPublic", policy =>
        policy
            .AllowAnyOrigin()
            .WithMethods("GET")
            .WithHeaders("Content-Type"));
});

Credentials

When your SPA sends cookies or Authorization headers with credentials: "include", you must explicitly allow credentials. This is incompatible with AllowAnyOrigin().

options.AddPolicy("AllowSPAWithCredentials", policy =>
    policy
        .WithOrigins("https://app.example.com")
        .WithMethods("GET", "POST", "PUT", "DELETE")
        .WithHeaders("Content-Type", "Authorization")
        .AllowCredentials());

If you need to support multiple subdomains dynamically while still using credentials, use SetIsOriginAllowed:

options.AddPolicy("AllowSubdomains", policy =>
    policy
        .SetIsOriginAllowed(origin =>
        {
            var host = new Uri(origin).Host;
            return host == "example.com"
                || host.EndsWith(".example.com",
                    StringComparison.OrdinalIgnoreCase);
        })
        .AllowCredentials()
        .WithMethods("GET", "POST", "PUT", "DELETE")
        .WithHeaders("Content-Type", "Authorization"));

Per-Endpoint CORS

Apply named policies to specific endpoint groups instead of globally.

// Minimal API — RequireCors on a group
var api = app.MapGroup("/api")
    .RequireCors("AllowSPA");

api.MapGet("/orders", GetOrders);
api.MapPost("/orders", CreateOrder);

// Public health check — different policy
app.MapGet("/health", () => Results.Ok("Healthy"))
    .RequireCors("AllowPublic");

With controllers, use the [EnableCors] attribute:

[ApiController]
[Route("api/[controller]")]
[EnableCors("AllowSPA")]
public class OrdersController : ControllerBase
{
    // All actions inherit "AllowSPA"

    [DisableCors]
    [HttpGet("internal-status")]
    public IActionResult InternalStatus() => Ok();
}

Preflight Caching

Browsers send an OPTIONS preflight request before non-simple cross-origin requests. Cache the preflight response to avoid redundant round-trips.

options.AddPolicy("AllowSPA", policy =>
    policy
        .WithOrigins("https://app.example.com")
        .WithMethods("GET", "POST", "PUT", "DELETE")
        .WithHeaders("Content-Type", "Authorization")
        .SetPreflightMaxAge(TimeSpan.FromHours(1)));

• Default browser preflight cache: 5 seconds
• Recommended: 1-2 hours for stable APIs
• Maximum respected by most browsers: ~2 hours (Chrome caps at 7200s)

Development vs Production

Use environment-specific CORS configuration so development is convenient while production stays locked down.

if (builder.Environment.IsDevelopment())
{
    builder.Services.AddCors(options =>
    {
        options.AddDefaultPolicy(policy =>
            policy
                .WithOrigins(
                    "https://localhost:5173",
                    "http://localhost:5173",
                    "https://localhost:3000")
                .AllowAnyMethod()
                .AllowAnyHeader()
                .AllowCredentials());
    });
}
else
{
    var allowedOrigins = builder.Configuration
        .GetSection("Cors:AllowedOrigins")
        .Get<string[]>() ?? [];

    builder.Services.AddCors(options =>
    {
        options.AddDefaultPolicy(policy =>
            policy
                .WithOrigins(allowedOrigins)
                .WithMethods("GET", "POST", "PUT", "DELETE")
                .WithHeaders(
                    "Content-Type",
                    "Authorization",
                    "X-Request-Id")
                .AllowCredentials()
                .SetPreflightMaxAge(
                    TimeSpan.FromHours(1)));
    });
}

// appsettings.Production.json
{
  "Cors": {
    "AllowedOrigins": [
      "https://app.example.com",
      "https://admin.example.com"
    ]
  }
}

CORS Options Class

For complex projects, bind CORS configuration to a strongly-typed options class.

public sealed class CorsOptions
{
    public const string SectionName = "Cors";

    public string[] AllowedOrigins { get; init; } = [];
    public string[] AllowedMethods { get; init; } =
        ["GET", "POST", "PUT", "DELETE"];
    public string[] AllowedHeaders { get; init; } =
        ["Content-Type", "Authorization"];
    public bool AllowCredentials { get; init; } = true;
    public int PreflightMaxAgeSeconds { get; init; } = 3600;
}

// Registration
var corsConfig = builder.Configuration
    .GetSection(CorsOptions.SectionName)
    .Get<CorsOptions>() ?? new CorsOptions();

builder.Services.AddCors(options =>
{
    options.AddDefaultPolicy(policy =>
    {
        policy
            .WithOrigins(corsConfig.AllowedOrigins)
            .WithMethods(corsConfig.AllowedMethods)
            .WithHeaders(corsConfig.AllowedHeaders)
            .SetPreflightMaxAge(
                TimeSpan.FromSeconds(
                    corsConfig.PreflightMaxAgeSeconds));

        if (corsConfig.AllowCredentials)
            policy.AllowCredentials();
    });
});

Common Mistakes

| Mistake | Problem | Fix | |---------|---------|-----| | AllowAnyOrigin() + AllowCredentials() | CORS spec violation — browsers block the response | Use WithOrigins(...) with explicit origins when credentials are needed | | UseCors() after UseAuthorization() | CORS middleware never runs for unauthorized preflight requests, returning 401 | Place UseCors() before UseAuthentication() and UseAuthorization() | | Origins with trailing slash | https://app.example.com/ does not match https://app.example.com | Remove trailing slashes from all origin strings | | Hardcoded localhost origins in production | Opens your API to any local dev machine | Use environment-conditional configuration (see Development vs Production) | | Missing OPTIONS method in WithMethods() | Not needed — the CORS middleware handles preflight OPTIONS automatically | Do not add OPTIONS to WithMethods(); it is implicit | | AllowAnyOrigin() on authenticated endpoints | Any website can make authenticated requests on behalf of your users | Restrict to known origins | | Wildcard headers with AllowAnyHeader() | Exposes your API to unexpected custom headers | List only the headers your clients actually send | | Not exposing response headers | Client JavaScript cannot read custom response headers unless exposed | Use WithExposedHeaders("X-Pagination", "X-Request-Id") | | Duplicating CORS headers in both middleware and reverse proxy | Browsers reject responses with duplicate Access-Control-Allow-Origin | Configure CORS in exactly one layer |

Decision Guide

| Scenario | Policy Configuration | |----------|---------------------| | Single SPA, same domain, different port (dev) | Default policy, WithOrigins("https://localhost:PORT"), AllowCredentials() | | Single SPA, different domain (prod) | Default policy, WithOrigins("https://app.example.com"), AllowCredentials() | | Multiple SPAs, different domains | Named policies per SPA group, RequireCors("PolicyName") per endpoint group | | Public read-only API | AllowAnyOrigin(), WithMethods("GET"), no credentials | | Subdomain wildcard | SetIsOriginAllowed() with domain suffix check, AllowCredentials() | | Server-to-server only | No CORS configuration needed | | API gateway handles CORS | No CORS in .NET — configure at the gateway layer only | | Mixed public + authenticated endpoints | Named policies: one restrictive with credentials, one permissive without |

Anti-Patterns

| Anti-Pattern | Why It Is Harmful | Better Approach | |-------------|-------------------|-----------------| | AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader() | Effectively disables CORS protection entirely | Specify exact origins, methods, and headers | | SetIsOriginAllowed(_ => true) | Equivalent to AllowAnyOrigin() but bypasses the wildcard-credentials check — worst of both worlds | Validate the origin against an allowlist or domain pattern | | Copying CORS config from Stack Overflow without reviewing | Most SO answers use AllowAny* for simplicity — not production-safe | Follow least-privilege principle for each policy | | One global permissive policy for all endpoints | Public endpoints and authenticated endpoints have different threat models | Use named policies and apply per-group | | Relying on CORS as an authentication mechanism | CORS is browser-enforced only — curl, Postman, and servers ignore it | Always enforce server-side authentication and authorization | | Adding CORS headers manually via middleware | Bypasses the built-in CORS negotiation logic and is error-prone | Use AddCors() and UseCors() exclusively |

Detect Existing Patterns

1. Search for AddCors in Program.cs or Startup.cs
2. Look for UseCors in the middleware pipeline
3. Check for [EnableCors] or [DisableCors] attributes on controllers
4. Search for RequireCors on minimal API endpoint groups
5. Look for manual Access-Control-Allow-Origin header manipulation
6. Check reverse proxy config (nginx, YARP, Azure Front Door) for existing CORS headers

Adding to Existing Project

1. Audit current origins: identify every front-end domain that calls the API
2. Add AddCors() with named policies matching your endpoint groups
3. Place UseCors() in the correct middleware position (after routing, before auth)
4. Apply per-endpoint policies using RequireCors() or [EnableCors()]
5. Set preflight cache with SetPreflightMaxAge to reduce OPTIONS traffic
6. Move allowed origins to configuration so they differ between environments
7. Verify with browser DevTools: check the Access-Control-* response headers on preflight and actual requests

References

• https://learn.microsoft.com/en-us/aspnet/core/security/cors
• https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
• https://fetch.spec.whatwg.org/#http-cors-protocol