Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

The OPTIONS preflight to an IIS site comes back 403 or 401

ErrorOPTIONS https://api.example.com/orders 403 (Forbidden)

Short answer

A browser sends the OPTIONS preflight without credentials, so an IIS site that needs authentication refuses it before your code runs. Install and enable the IIS CORS module: it answers preflights ahead of other modules. A 403 can also be the module itself, when failUnlistedOrigins is on and the origin is not in your list.

  • Applies to IIS 10, Windows Server 2022, IIS CORS module
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Send the preflight by hand with the origin your page uses and read the status line and any Access-Control headers in the reply.

    curl -i -X OPTIONS https://api.example.com/orders \
      -H "Origin: https://app.example.com" \
      -H "Access-Control-Request-Method: POST"
  2. 2Match what you see, then jump to its fix

    1. 1OPTIONS gets 401 or 403 with no Access-Control-Allow-Origin header, while the same URL works with credentials.Authentication refuses the preflight before any CORS code runsFix
    2. 2The 403 appears only for some origins, and the module is already enabled.The module rejects an origin that is not on the listFix

What does the error look like?

  • OPTIONS https://api.example.com/orders 403 (Forbidden)
  • 403 on the OPTIONS request in the browser Network tab, with no Access-Control-Allow-Origin header

Cause 1 of 2

Authentication refuses the preflight before any CORS code runs

1Check

The preflight is an OPTIONS request, and these requests are always anonymous. If anonymous authentication is switched off for the site, IIS rejects them. The IIS CORS module is built to handle preflights before other modules do, so it can answer correctly even then.

findstr /s /i "cors" C:\inetpub\wwwroot\web.config

2Fix

Install the IIS CORS module, then enable it for the site with the origin your page uses.

<system.webServer>
  <cors enabled="true">
    <add origin="https://app.example.com" allowCredentials="true" maxAge="120">
      <allowMethods>
        <add method="POST" />
      </allowMethods>
      <allowHeaders allowAllRequestedHeaders="true" />
    </add>
  </cors>
</system.webServer>

3Verify

Run the OPTIONS curl again: the status should be a success and Access-Control-Allow-Origin should name your origin.

curl -i -X OPTIONS https://api.example.com/orders \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST"

Confirmed by learn.microsoft.com

Did this fix it?

Cause 2 of 2

The module rejects an origin that is not on the list

1Check

With failUnlistedOrigins set to true, the module sets status 403 when the requested origin does not match the configured list, or when the origin is configured as not allowed. A typo, a missing port, http instead of https, or a different subdomain all count as another origin.

findstr /s /i "cors" C:\inetpub\wwwroot\web.config

2Fix

Add the exact origin to the list, or fix the existing entry. A wildcard such as https://*.example.com covers subdomains.

<cors enabled="true" failUnlistedOrigins="true">
  <add origin="https://app.example.com" />
  <add origin="https://*.example.com" />
</cors>

3Verify

Repeat the preflight with the origin that was refused.

curl -i -X OPTIONS https://api.example.com/orders \
  -H "Origin: https://staging.example.com" \
  -H "Access-Control-Request-Method: POST"

Confirmed by learn.microsoft.com

Did this fix it?

How do I stop it coming back?

  • Keep the origin list in web.config under source control so every environment has the same entries.
  • Use a specific origin, not *, when allowCredentials is true; the module expects this for protocol compliance.
  • Test the preflight with curl after every change to authentication settings.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.