ASP.NET Core CORS Policy Demo

Named, Default & Endpoint-Level CORS configuration for ASP.NET Core Web API — with security best practices, preflight handling, and anti-pattern examples.

---

🚀 Support the Channel — Join on Patreon

If this sample saved you time, consider joining our Patreon community. You'll get exclusive .NET tutorials, premium code samples, and early access to new content — all for the price of a coffee.

👉 Join CodingDroplets on Patreon

Prefer a one-time tip? Buy us a coffee ☕

---

🎯 What You'll Learn

• How to define named CORS policies (AddCors + options.AddPolicy) in ASP.NET Core
• How to apply a global default policy via app.UseCors("PolicyName")
• How to override per-controller or per-action with [EnableCors("PolicyName")]
• How to opt out of CORS entirely with [DisableCors] (and when you'd ever want to)
• The difference between AllowAnyOrigin() and WithOrigins(...) — and why it matters with credentials
• How preflight OPTIONS requests are handled automatically by the middleware
• Security best practices: principle of least privilege for API origins, headers, and methods
• Common CORS anti-patterns and how to avoid them

---

🗺️ Architecture Overview

Browser Request
      │
      ▼
┌─────────────────────────────────────────┐
│            CORS Middleware              │
│  ┌──────────────────────────────────┐   │
│  │  Evaluate against active policy  │   │
│  │  (global default or [EnableCors])│   │
│  └──────────────────────────────────┘   │
│  • Preflight (OPTIONS) handled here     │
│  • Access-Control-* headers added       │
└─────────────────────────────────────────┘
      │
      ▼
  HTTP Router
      │
      ▼
  Controller Action
      │   [EnableCors("PublicApiPolicy")]   → PublicApiPolicy
      │   (no attribute — inherits default) → FrontendPolicy
      │   [EnableCors("AdminPolicy")]       → AdminPolicy
      │   [DisableCors]                     → No CORS headers
      │
      ▼
   Response
      │
      ▼
Browser (respects Access-Control-Allow-Origin header)

---

📋 Policy Summary

Policy	Origins	Credentials	Headers	Methods	Use Case
PublicApiPolicy	Any (*)	❌ Not allowed	Any	Any	Public read-only endpoints
FrontendPolicy (default)	app.example.com, localhost:3000	✅ Allowed	Any	Any	Authenticated SPA clients
AdminPolicy	admin.example.com	❌ Not set	Content-Type, Authorization	GET, POST, PUT, DELETE	Admin back-office (strict)

Key rule: AllowAnyOrigin() and AllowCredentials() are mutually exclusive. ASP.NET Core will throw at startup if you combine them — by design, since a wildcard origin with credentials is a security vulnerability.

---

📁 Project Structure

aspnet-core-cors-policy-demo/
├── aspnet-core-cors-policy-demo.sln
└── CorsDemo/
    ├── CorsDemo.csproj                 # Project file — Scalar.AspNetCore package
    ├── Program.cs                      # CORS policy definitions + middleware pipeline
    ├── appsettings.json                # App configuration
    ├── Controllers/
    │   ├── PublicController.cs         # [EnableCors("PublicApiPolicy")] override
    │   ├── ProductsController.cs       # Uses global FrontendPolicy (no attribute)
    │   └── AdminController.cs          # [EnableCors("AdminPolicy")] + [DisableCors] demo
    └── Properties/
        └── launchSettings.json         # Scalar UI auto-launch on F5

---

🛠️ Prerequisites

Requirement	Version
.NET SDK	10.0+
IDE	Visual Studio 2022 v17.x / VS Code / Rider

---

⚡ Quick Start

# Clone the repository
git clone https://github.com/codingdroplets/aspnet-core-cors-policy-demo.git
cd aspnet-core-cors-policy-demo

# Restore and build
dotnet build -c Release

# Run the API
cd CorsDemo
dotnet run

Open your browser to http://localhost:5289/scalar/v1 — the Scalar API explorer opens automatically.

---

🔧 How It Works

1. Define named CORS policies (Program.cs)

builder.Services.AddCors(options =>
{
    // Policy 1: Public endpoints — any origin, no credentials
    options.AddPolicy("PublicApiPolicy", policy =>
        policy
            .AllowAnyOrigin()
            .AllowAnyHeader()
            .AllowAnyMethod());

    // Policy 2: Authenticated SPA — explicit origins + credentials
    options.AddPolicy("FrontendPolicy", policy =>
        policy
            .WithOrigins("https://app.example.com", "http://localhost:3000")
            .AllowAnyHeader()
            .AllowAnyMethod()
            .AllowCredentials());

    // Policy 3: Admin back-office — maximum restriction
    options.AddPolicy("AdminPolicy", policy =>
        policy
            .WithOrigins("https://admin.example.com")
            .WithHeaders("Content-Type", "Authorization")
            .WithMethods("GET", "POST", "PUT", "DELETE"));
});

2. Apply a global default policy

// Must come before UseAuthorization() and MapControllers()
app.UseCors("FrontendPolicy");

3. Override at controller level with [EnableCors]

[ApiController]
[Route("api/public")]
[EnableCors("PublicApiPolicy")] // overrides FrontendPolicy for this entire controller
public class PublicController : ControllerBase { ... }

4. Override at action level with [EnableCors] or [DisableCors]

[ApiController]
[Route("api/admin")]
[EnableCors("AdminPolicy")] // controller-wide override
public class AdminController : ControllerBase
{
    [HttpGet("health")]
    [DisableCors] // no CORS headers on this action — cross-origin blocked intentionally
    public IActionResult GetHealth() { ... }
}

5. Preflight handling

ASP.NET Core CORS middleware handles OPTIONS preflight requests automatically. No controller action is needed — the middleware intercepts and responds with the appropriate Access-Control-* headers before the request reaches your controller.

---

📡 API Endpoints

Method	Endpoint	CORS Policy	Description
GET	/api/public	PublicApiPolicy (any origin)	Public announcements — no auth required
GET	/api/products	FrontendPolicy (default)	List all products
GET	/api/products/{id}	FrontendPolicy (default)	Get product by ID
POST	/api/products	FrontendPolicy (default)	Create a new product
GET	/api/admin	AdminPolicy (admin.example.com only)	List admin users
DELETE	/api/admin/{id}	AdminPolicy (admin.example.com only)	Delete an admin user
GET	/api/admin/health	None [DisableCors]	Health check — cross-origin blocked
GET	/scalar/v1	N/A	Scalar API explorer (development only)
GET	/openapi/v1.json	N/A	OpenAPI JSON document

---

🧪 Running Tests

This project is focused on demonstrating CORS middleware configuration. You can test all CORS behaviours directly via the Scalar UI or with curl:

# Test PublicApiPolicy — any origin works
curl -H "Origin: https://random.example.com" \
     -H "Access-Control-Request-Method: GET" \
     -X OPTIONS http://localhost:5289/api/public -v

# Test FrontendPolicy — allowed origin
curl -H "Origin: http://localhost:3000" \
     -H "Access-Control-Request-Method: GET" \
     -X OPTIONS http://localhost:5289/api/products -v

# Test AdminPolicy — disallowed origin (expect no CORS headers in response)
curl -H "Origin: https://attacker.com" \
     -H "Access-Control-Request-Method: GET" \
     -X OPTIONS http://localhost:5289/api/admin -v

# Test [DisableCors] — no CORS headers regardless of origin
curl -H "Origin: https://admin.example.com" \
     -H "Access-Control-Request-Method: GET" \
     -X OPTIONS http://localhost:5289/api/admin/health -v

---

🤔 Key Concepts

Named vs Default vs Endpoint-Level CORS

Approach	How to Apply	Scope	Best For
Default policy	app.UseCors("Name")	Entire app	Single-policy APIs
Named policy	[EnableCors("Name")]	Controller or action	Mixed-policy APIs
Disable CORS	[DisableCors]	Specific action	Internal diagnostic routes

AllowAnyOrigin vs WithOrigins

// ✅ Safe for public, unauthenticated data
policy.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader()

// ✅ Required when credentials (cookies/auth headers) are involved
policy.WithOrigins("https://app.example.com").AllowCredentials()

// ❌ INVALID — throws InvalidOperationException at runtime
policy.AllowAnyOrigin().AllowCredentials()

Why UseCors() placement matters

app.UseRouting();
app.UseCors("MyPolicy");   // ← must be AFTER UseRouting, BEFORE UseAuthorization
app.UseAuthorization();
app.MapControllers();

CORS is browser-enforced, not server-enforced

CORS headers tell the browser whether to allow the response. A malicious server-to-server call can always ignore CORS. Use authentication and authorisation to secure your API — CORS alone is not a security boundary.

---

🏷️ Technologies Used

• ASP.NET Core 10 — Web API framework
• Microsoft.AspNetCore.Cors — Built-in CORS middleware (no extra package needed)
• Scalar.AspNetCore — Beautiful OpenAPI/Scalar UI replacing Swagger UI
• System.Text.Json — Built-in JSON serialisation with ReferenceHandler.IgnoreCycles
• .NET 10 SDK — Target framework

---

📚 References

• Enable Cross-Origin Requests (CORS) in ASP.NET Core — Microsoft Docs
• Cross-Origin Resource Sharing (CORS) — MDN Web Docs
• Fetch Standard — CORS Protocol (WHATWG)
• 📖 Deep Dive: ASP.NET Core CORS Policy Enterprise Decision Guide

---

📄 License

This project is licensed under the MIT License.

---

🔗 Connect with CodingDroplets

Platform	Link
🌐 Website	https://codingdroplets.com/
📺 YouTube	https://www.youtube.com/@CodingDroplets
🎁 Patreon	https://www.patreon.com/CodingDroplets
☕ Buy Me a Coffee	https://buymeacoffee.com/codingdroplets
💻 GitHub	http://github.com/codingdroplets/

Want more samples like this? Support us on Patreon or buy us a coffee ☕ — every bit helps keep the content coming!