How to Set Security Headers in IIS: CSP, HSTS and web.config

How IIS adds custom response headers

Windows IIS adds extra response headers through the customHeaders collection in the system.webServer/httpProtocol section of the configuration. You can set it in three places, and they stack from the top down:

• Server level, in applicationHost.config, applies to every site on the machine.
• Site level, in the web.config file in the site's root folder, applies to that site.
• Folder or application level, in a web.config inside a subfolder, applies below that folder.

Lower levels inherit from higher ones unless they clear the collection. When you add a header in IIS Manager under HTTP Response Headers, IIS Manager simply writes the same customHeaders entry into the config file for the level you selected. So whether you edit web.config by hand or click through the interface, the result is the same XML.

Custom headers are added to responses for static files and for applications IIS hosts, including ASP.NET and ASP.NET Core sites behind the ASP.NET Core Module. That makes web.config a good single place to own your security headers on a Windows server, as long as the application does not also set them.

Adding security headers in web.config

Open the web.config in the site root and add a httpProtocol block inside system.webServer. If the file already has a system.webServer element, add the block inside it rather than creating a second one.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <httpProtocol>
      <customHeaders>
        <remove name="X-Powered-By" />
        <add name="X-Content-Type-Options" value="nosniff" />
        <add name="X-Frame-Options" value="SAMEORIGIN" />
        <add name="Referrer-Policy" value="strict-origin-when-cross-origin" />
        <add name="Permissions-Policy" value="camera=(), microphone=(), geolocation=()" />
        <add name="Content-Security-Policy-Report-Only" value="default-src 'self'; img-src 'self' data:; frame-ancestors 'self'" />
      </customHeaders>
    </httpProtocol>
    <security>
      <requestFiltering removeServerHeader="true" />
    </security>
  </system.webServer>
</configuration>

The remove line drops the X-Powered-By: ASP.NET header that IIS adds by default, and removeServerHeader drops the Server header on IIS 10 version 1709 and later (Windows Server 2019 onwards). Neither is a security fix in itself, but scanners often flag them as information disclosure.

The same thing in IIS Manager

1. Open IIS Manager, expand Sites and select your site.
2. Double-click HTTP Response Headers.
3. Click Add in the Actions pane, enter the header name and value, and click OK.
4. Repeat for each header. To remove X-Powered-By, select it and click Remove.

Changes apply straight away; you do not need to restart the site. For a full list of headers and valid values, see the missing security headers guide.

How to set Content-Security-Policy in web.config

A Content Security Policy goes in customHeaders like any other header, but the XML format adds three rules:

• Keep it on one line. The value is an XML attribute, so write the whole policy in one string, with directives separated by semicolons.
• Use single quotes inside the value. CSP keywords such as 'self' and 'none' need single quotes, which sit safely inside the double-quoted XML attribute.
• Escape special XML characters. An ampersand or a less-than sign in a URL inside the policy must be written as an XML entity, or IIS will reject the file.

<add name="Content-Security-Policy"
     value="default-src 'self'; script-src 'self' https://cdn.example.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; frame-ancestors 'self'; base-uri 'self'; form-action 'self'" />

Start with the header name Content-Security-Policy-Report-Only. The browser then reports what the policy would block without blocking it, so you can watch the DevTools console and your reports for a week or two, add the sources your site really uses, and switch the name to Content-Security-Policy when nothing legitimate is being reported. The CSP report-only guide covers reading the reports.

ASP.NET sites often rely on inline scripts, for example WebForms postback scripts, which a strict policy blocks. If you cannot remove them, you may need 'unsafe-inline' for scripts at first, then work towards nonces. Framework-specific advice is in the CSP and frameworks guide.

Three ways to add HSTS on IIS

Strict-Transport-Security should only be sent on HTTPS responses. Browsers ignore it over plain HTTP, and some scanners flag it there as invalid. That is why the simple customHeaders method is not ideal for HSTS: it adds the header to every response, HTTP included. There are better options.

Native HSTS

On a recent IIS, select the site in IIS Manager and look for HSTS in the Actions pane, or set it from an elevated command prompt:

%windir%\system32\inetsrv\appcmd.exe set config -section:system.applicationHost/sites "/[name='Example Site'].hsts.enabled:True" "/[name='Example Site'].hsts.max-age:31536000" "/[name='Example Site'].hsts.includeSubDomains:True" "/[name='Example Site'].hsts.redirectHttpToHttps:True" /commit:apphost

This writes to applicationHost.config, not web.config, so you will not see it in the site folder.

URL Rewrite outbound rule

<rewrite>
  <outboundRules>
    <rule name="Add HSTS on HTTPS">
      <match serverVariable="RESPONSE_Strict_Transport_Security" pattern=".*" />
      <conditions>
        <add input="{HTTPS}" pattern="on" ignoreCase="true" />
      </conditions>
      <action type="Rewrite" value="max-age=31536000; includeSubDomains" />
    </rule>
  </outboundRules>
</rewrite>

This goes inside system.webServer. Start with a short max-age, such as 300, until you are sure every subdomain works over HTTPS; the disabling HSTS guide explains why a long one is hard to undo.

Why HSTS is not showing in IIS

If you have set HSTS and a scanner or curl still says it is missing, one of these is usually the reason:

A certificate or binding problem can also stop HTTPS working at all, so no HTTPS response, and no HSTS, ever reaches the visitor. The IIS SSL bindings guide covers that case.

How to check the headers IIS sends

Windows 10 and later, and Windows Server 2019 and later, include curl.exe. Use it from Command Prompt or PowerShell, typing curl.exe rather than curl, because in Windows PowerShell 5.1 curl is an alias for a different command:

curl.exe -sI https://www.example.com/
curl.exe -sI http://www.example.com/

Or use PowerShell directly:

(Invoke-WebRequest -Uri https://www.example.com/ -Method Head -UseBasicParsing).Headers

To see what the configuration says, rather than what the response says, list the section for the site:

%windir%\system32\inetsrv\appcmd.exe list config "Example Site" -section:system.webServer/httpProtocol

If the config lists a header that the response lacks, something after IIS, such as a proxy, is removing it, or the application is overwriting it. If the response has a header twice, both IIS and the application are adding it; remove one. You can also run the site through our security audit to see every header on several pages at once.

The fix, step by step

Edge cases worth knowing

• Application headers win or duplicate. If ASP.NET code also sets X-Frame-Options or a CSP, the response can carry two values. Pick one place and remove the other.
• Error pages. Detailed IIS error pages and some 401 responses may not carry custom headers; check a 404 with curl.
• Web Deploy and publish overwrites. Publishing an ASP.NET Core app regenerates web.config. Add your headers to the project's own web.config so they survive.
• Azure App Service. Windows plans read web.config the same way, but Front Door or Application Gateway in front may need the headers too.
• Shared hosting. If the host locks the httpProtocol section, you get a 500.19 lock error; ask them to unlock it or set the headers.

Keeping the headers in place

Keep the security header block in source control with the site, so every deployment carries it. After each Windows update, IIS change or publish, run curl.exe -sI on the home page, a deep page and a 404, and compare against your list. Rescan monthly, and keep the reports for clients or auditors. If the site sits behind a proxy, check the public address, not the server's own name, because that is what visitors and scanners see. Redirect rules affect HSTS too; see the HTTPS redirects guide.