dotnet / dotnet/AspNetCore.Docs
Changing IIS WindowsAuth and AnonAuth require Feature Delegation in IIS
- Dominant language
- C#
- Stars
- 13.1k
- Forks
- 24.6k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 97
Description
Under the IIS section of this doc, there are two approaches for enabling Windows Authentication.
The first approach is this:
> Before publishing and deploying the project, add the following web.config file to the project root:
>
```
```
> When the project is published by the .NET Core SDK (without the property set to true in the project file), the published web.config file includes the section. For more information on the property, see Host ASP.NET Core on Windows with IIS.
The problem with this is it does not consider IIS Feature Delegation, which by default **does not allow a web.config file to modify the anonymousAuthentication and windowsAuthentication sections** (they are locked as read-only).
Doing this as-is, without unlocking those sections, results in a 500.19 error from IIS due to modifying locked sections.
Both sections must be unlocked before they can be modified. Here is how to do this for both sections:
```
C:\Windows\System32\inetsrv>appcmd unlock config -section:WindowsAuthentication
Unlocked section "system.webServer/security/authentication/windowsAuthentication" at configuration path "MACHINE/WEBROOT/APPHOST".
C:\Windows\System32\inetsrv>appcmd unlock config -section:anonymousAuthentication
Unlocked section "system.webServer/security/authentication/anonymousAuthentication" at configuration path "MACHINE/WEBROOT/APPHOST".
```
It can also be performed in the IIS Manager interface:
IIS Manager -> root/server node -> Feature Delegation
**Authentication - Anonymous** => change to Read/Write (default=Read Only)
**Authentication - Windows** => change to Read/Write (default=Read Only)
CSS just had a support case for this, and the customer confirmed this is the doc they used.
The 2nd approach on the doc site says this (**_note my emphasis_**):
> After publishing and deploying the project, perform server-side configuration with the IIS Manager:
>
> In IIS Manager, select the IIS site under the Sites node of the Connections sidebar.
> Double-click Authentication in the IIS area.
> Select Anonymous Authentication. Select Disable in the Actions sidebar.
> Select Windows Authentication. Select Enable in the Actions sidebar.
> **_When these actions are taken, IIS Manager modifies the app's web.config file._** A node is added with updated settings for anonymousAuthentication and windowsAuthentication:
```
```
> The section added to the web.config file by IIS Manager is outside of the app's section added by the .NET Core SDK when the app is published. Because the section is added outside of the node, the settings are inherited by any sub-apps to the current app. To prevent inheritance, move the added section inside of the section that the .NET Core SDK provided.
>
> When IIS Manager is used to add the IIS configuration, it only affects the app's web.config file on the server. A subsequent deployment of the app may overwrite the settings on the server if the server's copy of web.config is replaced by the project's web.config file. Use either of the following approaches to manage the settings:
>
> Use IIS Manager to reset the settings in the web.config file after the file is overwritten on deployment.
> Add a web.config file to the app locally with the settings.
"**_When these actions are taken, IIS Manager modifies the app's web.config file._**"
This is incorrect **if IIS Feature Delegation has not been configured as noted above, and the Windows Auth and Anonymous Auth configurations are still locked as read-only.**
When modifying a configuration in IIS Manager at a level where that configuration is locked, IIS will make the configuration at a higher level and wrap it inside a `````` tag indicating where at the lower level the configuration should be applied.
Thus, when making changes to Windows Auth and Anon Auth, the change will be placed into the applicationhost.config.
**For the wording as-is to be accurate, both features must be unlocked as described earlier.**
I suggest there be wording above the approaches showing how to unlock the IIS configuration, then the approaches will work as described:
> The ASP.NET Core Module is configured to forward the Windows Authentication token to the app by default. For more information, see ASP.NET Core Module configuration reference: Attributes of the aspNetCore element.
>
> ``` insert configuration unlocking section here```
>
> Use either of the following approaches:
---
#### Document Details
⚠ *Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.*
* ID: 401ad9a0-9e51-80a2-5846-82e9790d7257
* Version Independent ID: fbc36c26-9992-1f4c-66d3-02f898ee7ec4
* Content: [Configure Windows Authentication in ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/windowsauth?view=aspnetcore-2.1&tabs=visual-studio#iis)
* Content Source: [aspnetcore/security/authentication/windowsauth.md](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/security/authentication/windowsauth.md)
* Product: **aspnet-core**
* Technology: **aspnetcore-security**
* GitHub Login: @Rick-Anderson
* Microsoft Alias: **riande**
Contributor guide
Assessment
This issue has not been assessed yet.