CORS

An origin is the combination of scheme, host and port: https://hr.example is one origin, and http://hr.example, https://hr.example:8080 and https://other.example are three different ones. A difference in any of the three parts makes it a separate origin.

Browsers enforce a rule called the same-origin policy. Script running on one origin cannot read the response from a request to a different origin unless that other origin says it may. This is what stops a page you happened to open from reading your data out of an API you are signed in to on another tab.

Cross-Origin Resource Sharing, universally shortened to CORS, is the mechanism by which a server grants that permission. It is a set of response headers saying which origins are allowed, which methods and headers they may use, and whether credentials may be included.

Configuring it is therefore an act of naming who you trust. That framing is more useful than treating CORS as an error to make go away.

const string HrPortalPolicy = "hr-portal";

builder.Services.AddCors(options =>
{
    options.AddPolicy(HrPortalPolicy, policy =>
        policy
            // Exact origins. No trailing slash — the value must match
            // scheme, host and port exactly.
            .WithOrigins(
                "https://hr.example",
                "https://hr-staging.example")
            .WithMethods("GET", "POST", "PUT", "DELETE")
            .WithHeaders("Content-Type", "Authorization")
            // Without this, script cannot read the header at all.
            .WithExposedHeaders("X-Correlation-Id")
            .AllowCredentials()
            // Cache the preflight answer, so OPTIONS is not sent every time.
            .SetPreflightMaxAge(TimeSpan.FromMinutes(10)));
});

WebApplication app = builder.Build();

app.UseRouting();
app.UseCors(HrPortalPolicy);   // before authorization
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

• Everything is named explicitly: which origins, which methods, which request headers, which response headers. Each line is a decision you can defend in a review.
• Origins must match exactly and must not end with a slash. A trailing slash is the single most common reason a correctly configured policy appears not to work.
• WithExposedHeaders is easy to forget. By default script can read only a small set of response headers, so your correlation id is invisible to the client until you list it here.
• SetPreflightMaxAge lets the browser cache the preflight result. It removes an OPTIONS round trip per request, at the cost of a delay before a policy change takes effect for clients that already cached it.
• UseCors goes after UseRouting and before UseAuthorization. Register it too late and a rejected cross-origin request can fail before the headers that explain the rejection are ever added.

OPTIONS /api/employees HTTP/1.1
Host: api.internal.example
Origin: https://hr.example
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type,authorization

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://hr.example
Access-Control-Allow-Methods: GET,POST,PUT,DELETE
Access-Control-Allow-Headers: content-type,authorization
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 600
Vary: Origin

• The browser sends this by itself. There is no body, no controller involved, and no authentication — which is why a preflight must be allowed through even on endpoints that require a token.
• Access-Control-Allow-Origin echoes one specific origin rather than a wildcard, because the policy named exact origins.
• Access-Control-Allow-Credentials: true is what permits cookies and the Authorization header on the real request. It only appears because the policy called AllowCredentials.
• Vary: Origin tells caches that the response depends on the Origin header. Without it, a shared cache can serve one origin's allow-headers to a different origin.
• If any of these headers were missing or did not cover what was asked, the browser would stop here and the real POST would never be sent.