ASP.NET Core CORS configuration

pmentPolicy", policy => { policy.SetIsOriginAllowed(origin => { var uri = new Uri(origin); return uri.Host == "localhost" || uri.Host == "127.0.0.1"; }) .AllowAnyMethod() .AllowAnyHeader() .AllowCredentials(); }); });

builder.Services.AddControllers(); builder.Services.AddAuthorization();

var app = builder.Build();

// Pipeline ordering is critical app.UseRouting();

// Apply CORS before authorization var environment = app.Environment.EnvironmentName; var activePolicy = environment == "Development" ? "DevelopmentPolicy" : "ProductionPolicy"; app.UseCors(activePolicy);

app.UseAuthorization(); app.MapControllers();

app.Run();

### Architecture Decisions and Rationale

- **Named Policies over Global Wildcards**: Named policies enable granular control, testing, and auditability. They prevent accidental credential exposure and allow per-service overrides in microservice architectures.
- **Configuration-Driven Origins**: Hardcoded origins break during environment promotion and increase deployment risk. Binding to `IConfiguration` enables secret management integration and CI/CD validation.
- **Middleware Pipeline Placement**: CORS evaluation must occur after routing but before authorization. If placed before routing, the framework cannot match endpoints correctly. If placed after authorization, protected resources may leak headers to unauthorized cross-origin clients.
- **Preflight Caching**: `SetPreflightMaxAge` reduces `OPTIONS` request volume. A 24-hour cache is safe for stable APIs and reduces latency by 40-60% for repeated cross-origin calls.
- **Credential Compatibility**: `AllowCredentials()` requires explicit origin matching. The CORS specification prohibits wildcards with credentials. ASP.NET Core enforces this at runtime, throwing exceptions if misconfigured.

## Pitfall Guide

### 1. Using `AllowAnyOrigin()` with `AllowCredentials()`
The browser blocks this combination entirely. ASP.NET Core will throw an `InvalidOperationException` at runtime. Developers often attempt to bypass this by adding custom headers or disabling browser security, which destroys the protection model. Always pair credentials with explicit origin lists.

### 2. Misplacing `UseCors()` in the Pipeline
Placing `UseCors()` before `UseRouting()` causes the framework to evaluate CORS against unmatched routes, resulting in 404 responses or missing headers. Placing it after `UseAuthorization()` allows unauthorized clients to receive CORS headers, enabling credential theft. The correct position is immediately after routing.

### 3. Ignoring Preflight Request Handling
Browsers send `OPTIONS` requests for requests with custom headers, non-simple methods, or credentials. If the policy does not allow the requested method or header, the preflight fails and the actual request is blocked. ASP.NET Core handles preflight automatically when policies are correctly defined, but custom middleware or minimal APIs often bypass this logic.

### 4. Hardcoding Origins in Source Control
Hardcoded origins prevent environment promotion and expose internal development URLs in production. They also complicate compliance audits. Always externalize origins to configuration providers (JSON, Azure Key Vault, AWS Secrets Manager).

### 5. Confusing CORS with Authentication/Authorization
CORS does not authenticate or authorize requests. It only controls whether the browser allows the JavaScript runtime to read the response. A cross-origin request can succeed at the network level while the server returns 401/403. Developers often mistake CORS failures for authentication failures, leading to incorrect debugging paths.

### 6. Overusing `SetIsOriginAllowed()` with Regex
`SetIsOriginAllowed()` accepts a delegate for dynamic validation, but using regex or string matching without strict parsing introduces open redirect vulnerabilities. Always validate against a whitelist or use `Uri` parsing with explicit scheme/host checks.

### 7. Not Testing with Real Browser DevTools
Server-side logs cannot reveal browser-enforced CORS blocks. Always test with Chrome/Firefox DevTools Network tab, inspect `Access-Control-*` response headers, and verify preflight behavior. Mock clients (Postman, curl) bypass CORS entirely, creating false confidence.

**Production Best Practices:**
- Log rejected CORS requests with origin, path, and policy name for audit trails.
- Automate policy validation in CI/CD using integration tests that simulate cross-origin requests.
- Separate CORS policies by service boundary in microservice architectures.
- Rotate allowed origins during domain migrations using configuration versioning.
- Document CORS requirements in API contracts (OpenAPI/Swagger) to align frontend/backend teams.

## Production Bundle

### Action Checklist
- [ ] Register CORS services before routing middleware
- [ ] Define named policies with explicit origins, methods, and headers
- [ ] Externalize allowed origins to environment configuration
- [ ] Place UseCors() after UseRouting() and before UseAuthorization()
- [ ] Validate credential compatibility with origin whitelists
- [ ] Set preflight max age to reduce OPTIONS request volume
- [ ] Test cross-origin behavior with browser DevTools, not curl/Postman
- [ ] Log CORS rejections for security auditing and debugging

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Single-page app communicating with monolithic API | Policy-based with specific origins | Balances security and performance; easy to audit | Low implementation cost, high long-term savings |
| Microservice architecture with 10+ frontend clients | Named policies per service + shared origin config | Prevents policy sprawl; enables independent deployment | Medium setup cost, reduces cross-team coordination overhead |
| Internal tooling with dynamic subdomains | SetIsOriginAllowed() with strict Uri validation | Handles wildcard-like behavior safely | Higher maintenance, prevents security gaps |
| Legacy migration with mixed HTTP/HTTPS origins | Environment-split policies + redirect enforcement | Avoids mixed-content blocking; aligns with modern browsers | Short-term migration cost, eliminates compliance risk |
| High-throughput public API | Reverse-proxy CORS + strict origin allowlist | Offloads header management; reduces app server load | Infrastructure cost increase, improves scalability |

### Configuration Template

```json
// appsettings.json
{
  "CorsPolicy": {
    "AllowedOrigins": [
      "https://app.example.com",
      "https://admin.example.com",
      "https://partner.example.io"
    ],
    "AllowedMethods": [ "GET", "POST", "PUT", "DELETE" ],
    "AllowedHeaders": [ "Content-Type", "Authorization", "X-Request-Id" ],
    "AllowCredentials": true,
    "PreflightMaxAgeSeconds": 86400
  }
}

// Policy registration with configuration binding
builder.Services.AddCors(options =>
{
    var corsConfig = builder.Configuration.GetSection("CorsPolicy");
    var origins = corsConfig.GetSection("AllowedOrigins").Get<string[]>() ?? Array.Empty<string>();
    var methods = corsConfig.GetSection("AllowedMethods").Get<string[]>() ?? new[] { "GET", "POST" };
    var headers = corsConfig.GetSection("AllowedHeaders").Get<string[]>() ?? new[] { "Content-Type" };
    var allowCredentials = corsConfig.GetValue<bool>("AllowCredentials");
    var preflightMaxAge = TimeSpan.FromSeconds(corsConfig.GetValue<int>("PreflightMaxAgeSeconds"));

    options.AddPolicy("DefaultPolicy", policy =>
    {
        policy.WithOrigins(origins)
              .WithMethods(methods)
              .WithHeaders(headers)
              .SetPreflightMaxAge(preflightMaxAge);

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

Quick Start Guide

1. Add CORS services: Call builder.Services.AddCors() in Program.cs before building the app.
2. Define a policy: Use options.AddPolicy("MyPolicy", policy => policy.WithOrigins("https://frontend.domain").AllowAnyMethod().AllowAnyHeader()).
3. Insert middleware: Add app.UseCors("MyPolicy") immediately after app.UseRouting().
4. Apply to endpoints: Use [EnableCors("MyPolicy")] on controllers or rely on global application.
5. Verify in browser: Open DevTools Network tab, send a cross-origin request, and confirm Access-Control-Allow-Origin matches your policy. Preflight OPTIONS should return 204 with correct headers.

CORS is not a connectivity feature; it is a security contract between the browser and the server. Treating it as such eliminates 90% of cross-origin failures, reduces incident response time, and aligns ASP.NET Core applications with modern zero-trust architecture principles.