CORS, Correctly

The orders front end is served from one host and calls the API on another. That is two origins, and browsers treat the boundary between them as significant. Getting the configuration right takes ten minutes; understanding what it is for takes a little longer and is the part worth having.

The same-origin policy is a browser rule. A page from one origin may cause a request to another origin — that has always been allowed, and it is how every image, script and form post to a third party works. What the policy stops is the page reading the response. Script on a page cannot read what came back from an origin that did not agree to it.

That rule is why a page you have open cannot quietly read your inbox from another tab's session. Without it, any page could call any API your browser has cookies for and read the results.

CORS — cross-origin resource sharing — is the mechanism by which a server relaxes that rule on purpose. Your API says, in response headers, which other origins may read its responses. The rest of this lesson is about configuring that narrowly, and about the thing people consistently get wrong: who enforces it.

var builder = WebApplication.CreateBuilder(args);

// Origins differ per environment, so they are configuration rather than code.
// The development localhost origin must not be allowed in production.
var allowedOrigins = builder.Configuration
    .GetSection("Cors:AllowedOrigins").Get<string[]>() ?? [];

builder.Services.AddCors(options =>
{
    options.AddPolicy("OrdersWebApp", policy => policy
        .WithOrigins(allowedOrigins)                                // exact scheme, host and port
        .WithMethods("GET", "POST", "PUT", "DELETE")
        .WithHeaders("Authorization", "Content-Type", "X-CSRF-TOKEN")
        .WithExposedHeaders("X-Correlation-Id")
        .AllowCredentials()
        .SetPreflightMaxAge(TimeSpan.FromMinutes(10)));
});

var app = builder.Build();

app.UseCors("OrdersWebApp");   // before authentication and before the endpoints
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers().RequireAuthorization();

// FLAWED SHAPE, for recognition only.
//
//   policy.AllowAnyOrigin().AllowCredentials()
//
// ASP.NET Core throws at runtime for that combination, because the CORS
// protocol forbids it. The workaround people reach for next is worse, since
// it removes the guard instead of the cause:
//
//   policy.SetIsOriginAllowed(_ => true).AllowCredentials()
//
// That reflects whatever origin asked back as the allowed origin, and tells
// the browser to send this user's cookies to it. Neither line belongs in a
// deployed application.

app.Run();

• WithOrigins compares the full origin, exactly. A trailing slash makes it fail to match, http and https are different entries, and a port must be written when it is not the default. Most of the time a policy that seems ignored is a policy that did not match.
• Origins come from configuration because they are environment-specific. A localhost entry compiled into the policy is an allowed origin in production, and it is the kind of thing that survives for years because nothing visibly breaks.
• Naming methods and headers rather than allowing any is the same closed-by-default idea as the fallback policy in the first lesson. AllowAnyHeader is common and is usually a shortcut past working out which header was missing.
• WithExposedHeaders is needed for your own response headers to be readable by the page. Without it a browser exposes only a small standard set, which is the usual explanation for a correlation id that the front end cannot find.
• AllowCredentials permits cookies and the Authorization header on cross-origin requests. It is required for a cookie-based front end on another origin, and it is the setting that makes a loose origin list serious rather than untidy.
• The framework throwing for AllowAnyOrigin with AllowCredentials is a guard, not a bug to route around. Reflecting the origin back with SetIsOriginAllowed produces exactly what the protocol forbids, with the error message removed. If you find that line in a codebase, the question to ask is which origins genuinely need access.
• UseCors runs before the endpoints, and before anything that short-circuits the pipeline. Put it after, and a preflight gets answered without the headers, which surfaces as a CORS failure in the browser with a perfectly healthy server log.
• RequireAuthorization on the endpoints is the point of the callout above. The CORS policy governs which pages may read responses; the authorisation requirement is what actually decides who may call.
• SetPreflightMaxAge lets the browser cache the preflight answer, saving a round trip per request shape. The trade-off is that a policy change takes up to that long to reach a browser holding a cached answer, so keep it modest while you are still adjusting things.

OPTIONS /orders/4821 HTTP/1.1
Host: api.example-company.com
Origin: https://orders.example-company.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: authorization,content-type

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://orders.example-company.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 600
Vary: Origin

• The browser sends this by itself. Your front-end code makes one call; the network tab shows two. Nothing in your application code triggers the OPTIONS request and nothing needs to handle it when the CORS middleware is registered.
• The request states what the real call intends to do. If the method or any header is not permitted, the browser stops there and the real request is never sent — which is why a missing header in the policy looks like a request that never reached the server, because it did not.
• The response names one origin, not a list. Where several origins are allowed, the server echoes back the one that asked, after checking it against the policy.
• Vary: Origin tells caches that the response depends on the request's Origin header. Without it, a shared cache can store the headers generated for one origin and serve them to another, which quietly hands a response to a page that was never allowed to read it. This is the CORS detail most often missed once a CDN is in front of an API.
• Access-Control-Allow-Credentials: true is only valid alongside a specific origin. A browser refuses the combination of credentials and a wildcard, and that refusal is the protocol working as intended.
• Max-Age caches this answer for ten minutes, so subsequent PUTs to that origin skip the preflight.
• Worth repeating in this context: a client that is not a browser sends none of this and reads none of it. It issues the PUT directly. The preflight is a conversation between the browser and your server about what the browser will allow its own page to do.