Windows Authentication

Overview

The element defines configuration settings for the Internet Information Services (IIS) 7 Windows authentication module. You can use Windows authentication when your IIS 7 server runs on a corporate network that is using Microsoft Active Directory service domain identities or other Windows accounts to identify users. Because of this, you can use Windows authentication whether or not your server is a member of an Active Directory domain.

Windows authentication (formerly named NTLM, and also referred to as Windows NT Challenge/Response authentication) is a secure form of authentication because the user name and password are hashed before being sent across the network. When you enable Windows authentication, the client browser sends a strongly hashed version of the password in a cryptographic exchange with your Web server.

Windows authentication supports two authentication protocols, Kerberos and NTLM, which are defined in the

element. When you install and enable Windows authentication on IIS 7, the default protocol is Kerberos. The element can also contain a useKernelMode attribute that configures whether to use the kernel mode authentication feature that is new to Windows Server 2008.

Windows authentication is best suited for an intranet environment for the following reasons:

• Client computers and Web servers are in the same domain.
• Administrators can make sure that every client browser is Internet Explorer 2.0 or later.
• HTTP proxy connections, which are not supported by NTLM, are not required.
• Kerberos version 5 requires a connection to Active Directory, which is not feasible in an Internet environment.

New in IIS 7.5

The element was introduced in IIS 7.5, which allows you to configure the settings for the new extended protection features that have been integrated into Windows authentication.

Compatibility

Version	Notes
IIS 10.0	The element was not modified in IIS 10.0.
IIS 8.5	The element was not modified in IIS 8.5.
IIS 8.0	The element was not modified in IIS 8.0.
IIS 7.5	The element was added in IIS 7.5.
IIS 7.0	The element was introduced in IIS 7.0.
IIS 6.0	The element replaces portions of the IIS 6.0 AuthType and AuthFlags metabase properties.

Setup

The default installation of IIS 7 and later does not include the Windows authentication role service. To use Windows authentication on IIS, you must install the role service, disable Anonymous authentication for your Web site or application, and then enable Windows authentication for the site or application.

After you install the role service, IIS 7 commits the following configuration settings to the ApplicationHost.config file.

Windows Server 2012 or Windows Server 2012 R2

1. On the taskbar, click Server Manager.
2. In Server Manager, click the Manage menu, and then click Add Roles and Features.
3. In the Add Roles and Features wizard, click Next. Select the installation type and click Next. Select the destination server and click Next.
4. On the Server Roles page, expand Web Server (IIS), expand Web Server, expand Security, and then select Windows Authentication. Click Next.
   .
5. On the Select features page, click Next.
6. On the Confirm installation selections page, click Install.
7. On the Results page, click Close.

Windows 8 or Windows 8.1

1. On the Start screen, move the pointer all the way to the lower left corner, right-click the Start button, and then click Control Panel.
2. In Control Panel, click Programs and Features, and then click Turn Windows features on or off.
3. Expand Internet Information Services, expand World Wide Web Services, expand Security, and then select Windows Authentication.
   
4. Click OK.
5. Click Close.

Windows Server 2008 or Windows Server 2008 R2

1. On the taskbar, click Start, point to Administrative Tools, and then click Server Manager.
2. In the Server Manager hierarchy pane, expand Roles, and then click Web Server (IIS).
3. In the Web Server (IIS) pane, scroll to the Role Services section, and then click Add Role Services.
4. On the Select Role Services page of the Add Role Services Wizard, select Windows Authentication, and then click Next.
   
5. On the Confirm Installation Selections page, click Install.
6. On the Results page, click Close.

Windows Vista or Windows 7

1. On the taskbar, click Start, and then click Control Panel.
2. In Control Panel, click Programs and Features, and then click Turn Windows Features on or off.
3. Expand Internet Information Services, then World Wide Web Services, then Security.
4. Select Windows Authentication, and then click OK.
   

How To

How to enable Windows authentication for a Web site, Web application, or Web service

Open Internet Information Services (IIS) Manager:

If you are using Windows Server 2012 or Windows Server 2012 R2:

• On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.

If you are using Windows 8 or Windows 8.1:

• Hold down the Windows key, press the letter X, and then click Control Panel.
• Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

If you are using Windows Server 2008 or Windows Server 2008 R2:

• On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

If you are using Windows Vista or Windows 7:

• On the taskbar, click Start, and then click Control Panel.
• Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

In the Connections pane, expand the server name, expand Sites, and then the site, application, or Web service for which you want to enable Windows authentication.

Scroll to the Security section in the Home pane, and then double-click Authentication.

In the Authentication pane, select Windows Authentication, and then click Enable in the Actions pane.

How to enable Extended Protection for Windows authentication

Open Internet Information Services (IIS) Manager:

If you are using Windows Server 2012 or Windows Server 2012 R2:

• On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.

If you are using Windows 8 or Windows 8.1:

• Hold down the Windows key, press the letter X, and then click Control Panel.
• Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

If you are using Windows Server 2008 or Windows Server 2008 R2:

• On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

If you are using Windows Vista or Windows 7:

• On the taskbar, click Start, and then click Control Panel.
• Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

In the Connections pane, expand the server name, expand Sites, and then the site, application, or Web service for which you want to enable Extended Protection for Windows authentication.

Scroll to the Security section in the Home pane, and then double-click Authentication.

In the Authentication pane, select Windows Authentication.

Click Enable in the Actions pane.

Click Advanced Settings in the Actions pane.

When the Advanced Settings dialog box appears, select one of the following options in the Extended Protection drop-down menu:

• Select Accept if you want to enable extended protection while providing down-level support for clients that do not support extended protection.
• Select Required if you want to enable extended protection without providing down-level support.
  

Click OK to close the Advanced Settings dialog box.

Configuration

The element is configurable at the site, application, or virtual directory level in the ApplicationHost.config file.

Attributes

Attribute	Description
authPersistNonNTLM	Optional Boolean attribute.

Specifies whether IIS automatically reauthenticates every non-NTLM (for example, Kerberos) request, even those on the same connection. False enables multiple authentications for the same connections.

Note: A setting of true means that the client will be authenticated only once on the same connection. IIS will cache a token or ticket on the server for a TCP session that stays established.

The default is false . authPersistSingleRequest Optional Boolean attribute.

Setting this flag to true specifies that authentication persists only for a single request on a connection. IIS resets the authentication at the end of each request, and forces reauthentication on the next request of the session.

The default value is false . enabled Required Boolean attribute.

Specifies whether Windows authentication is enabled.

The default value is false . useKernelMode Optional Boolean attribute.

Specifies whether Windows authentication is done in kernel mode. True specifies that Windows authentication uses kernel mode.

Kernel-mode authentication may improve authentication performance and prevent authentication problems with application pools that are configured to use a custom identity.

As a best practice, do not disable this setting if you use Kerberos authentication and have a custom identity on the application pool.

The default is true .

Child Elements

Element	Description
extendedProtection	Optional element.

Specifies extended protection options for Windows authentication.

Note: This element was added in IIS 7.5. providers Optional element.

Specifies security support providers used for Windows authentication.

Configuration Sample

The following default element is configured at the root ApplicationHost.config file in IIS 7.0, and disables Windows authentication by default. It also defines the two Windows authentication providers for IIS 7.0.

The following example enables Windows authentication and disables Anonymous authentication for a Web site named Contoso.

Sample Code

The following examples disable Anonymous authentication for a site named Contoso, then enable Windows authentication for the site.

Configure Windows Authentication in ASP.NET Core

Windows Authentication (also known as Negotiate, Kerberos, or NTLM authentication) can be configured for ASP.NET Core apps hosted with IIS, Kestrel, or HTTP.sys.

Windows Authentication (also known as Negotiate, Kerberos, or NTLM authentication) can be configured for ASP.NET Core apps hosted with IIS or HTTP.sys.

Windows Authentication relies on the operating system to authenticate users of ASP.NET Core apps. You can use Windows Authentication when your server runs on a corporate network using Active Directory domain identities or Windows accounts to identify users. Windows Authentication is best suited to intranet environments where users, client apps, and web servers belong to the same Windows domain.

Windows Authentication isn’t supported with HTTP/2. Authentication challenges can be sent on HTTP/2 responses, but the client must downgrade to HTTP/1.1 before authenticating.

Proxy and load balancer scenarios

Windows Authentication is a stateful scenario primarily used in an intranet, where a proxy or load balancer doesn’t usually handle traffic between clients and servers. If a proxy or load balancer is used, Windows Authentication only works if the proxy or load balancer:

• Handles the authentication.
• Passes the user authentication information to the app (for example, in a request header), which acts on the authentication information.

An alternative to Windows Authentication in environments where proxies and load balancers are used is Active Directory Federated Services (ADFS) with OpenID Connect (OIDC).

IIS/IIS Express

Add authentication services by invoking AddAuthentication (Microsoft.AspNetCore.Server.IISIntegration namespace) in Startup.ConfigureServices :

Launch settings (debugger)

Configuration for launch settings only affects the Properties/launchSettings.json file for IIS Express and doesn’t configure IIS for Windows Authentication. Server configuration is explained in the IIS section.

The Web Application template available via Visual Studio or the .NET Core CLI can be configured to support Windows Authentication, which updates the Properties/launchSettings.json file automatically.

New project

1. Create a new project.
2. Select ASP.NET Core Web Application. Select Next.
3. Provide a name in the Project name field. Confirm the Location entry is correct or provide a location for the project. Select Create.
4. Select Change under Authentication.
5. In the Change Authentication window, select Windows Authentication. Select OK.
6. Select Web Application.
7. Select Create.

Run the app. The username appears in the rendered app’s user interface.

Existing project

The project’s properties enable Windows Authentication and disable Anonymous Authentication:

1. Right-click the project in Solution Explorer and select Properties.
2. Select the Debug tab.
3. Clear the check box for Enable Anonymous Authentication.
4. Select the check box for Enable Windows Authentication.
5. Save and close the property page.

Alternatively, the properties can be configured in the iisSettings node of the launchSettings.json file:

New project

Execute the dotnet new command with the webapp argument (ASP.NET Core Web App) and —auth Windows switch:

Existing project

Update the iisSettings node of the launchSettings.json file:

When modifying an existing project, confirm that the project file includes a package reference for the Microsoft.AspNetCore.App metapackage or the Microsoft.AspNetCore.Authentication NuGet package.

IIS uses the ASP.NET Core Module to host ASP.NET Core apps. Windows Authentication is configured for IIS via the web.config file. The following sections show how to:

• Provide a local web.config file that activates Windows Authentication on the server when the app is deployed.
• Use the IIS Manager to configure the web.config file of an ASP.NET Core app that has already been deployed to the server.

If you haven’t already done so, enable IIS to host ASP.NET Core apps. For more information, see Host ASP.NET Core on Windows with IIS.

Enable the IIS Role Service for Windows Authentication. For more information, see Enable Windows Authentication in IIS Role Services (see Step 2).

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.

Use either of the following approaches:

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.

After publishing and deploying the project, perform server-side configuration with the IIS Manager:

1. In IIS Manager, select the IIS site under the Sites node of the Connections sidebar.
2. Double-click Authentication in the IIS area.
3. Select Anonymous Authentication. Select Disable in the Actions sidebar.
4. Select Windows Authentication. Select Enable in the Actions sidebar.

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.

Kestrel

The Microsoft.AspNetCore.Authentication.Negotiate NuGet package can be used with Kestrel to support Windows Authentication using Negotiate and Kerberos on Windows, Linux, and macOS.

Credentials can be persisted across requests on a connection. Negotiate authentication must not be used with proxies unless the proxy maintains a 1:1 connection affinity (a persistent connection) with Kestrel.

The Negotiate handler detects if the underlying server supports Windows Authentication natively and if it is enabled. If the server supports Windows Authentication but it is disabled, an error is thrown asking you to enable the server implementation. When Windows Authentication is enabled in the server, the Negotiate handler transparently forwards authentication requests to it.

Add authentication services by invoking AddAuthentication and AddNegotiate in Startup.ConfigureServices :

Add Authentication Middleware by calling UseAuthentication in Startup.Configure :

For more information on middleware, see ASP.NET Core Middleware.

Kerberos authentication and role-based access control (RBAC)

Kerberos authentication on Linux or macOS doesn’t provide any role information for an authenticated user. To add role and group information to a Kerberos user, the authentication handler must be configured to retrieve the roles from an LDAP domain. The most basic configuration only specifies an LDAP domain to query against and will use the authenticated user’s context to query the LDAP domain:

Some configurations may require specific credentials to query the LDAP domain. The credentials can be specified in the following highlighted options:

By default, the negotiate authentication handler resolves nested domains. In a large or complicated LDAP environment, resolving nested domains may result in a slow lookup or a lot of memory being used for each user. Nested domain resolution can be disabled using the IgnoreNestedGroups option.

Anonymous requests are allowed. Use ASP.NET Core Authorization to challenge anonymous requests for authentication.

Windows environment configuration

The Microsoft.AspNetCore.Authentication.Negotiate component performs User Mode authentication. Service Principal Names (SPNs) must be added to the user account running the service, not the machine account. Execute setspn -S HTTP/myservername.mydomain.com myuser in an administrative command shell.

Linux and macOS environment configuration

Instructions for joining a Linux or macOS machine to a Windows domain are available in the Connect Azure Data Studio to your SQL Server using Windows authentication — Kerberos article. The instructions create a machine account for the Linux machine on the domain. SPNs must be added to that machine account.

When following the guidance in the Connect Azure Data Studio to your SQL Server using Windows authentication — Kerberos article, replace python-software-properties with python3-software-properties if needed.

Once the Linux or macOS machine is joined to the domain, additional steps are required to provide a keytab file with the SPNs:

• On the domain controller, add new web service SPNs to the machine account:
  • setspn -S HTTP/mywebservice.mydomain.com mymachine
  • setspn -S HTTP/mywebservice@MYDOMAIN.COM mymachine
• Use ktpass to generate a keytab file:
  • ktpass -princ HTTP/mywebservice.mydomain.com@MYDOMAIN.COM -pass myKeyTabFilePassword -mapuser MYDOMAIN\mymachine$ -pType KRB5_NT_PRINCIPAL -out c:\temp\mymachine.HTTP.keytab -crypto AES256-SHA1
  • Some fields must be specified in uppercase as indicated.
• Copy the keytab file to the Linux or macOS machine.
• Select the keytab file via an environment variable: export KRB5_KTNAME=/tmp/mymachine.HTTP.keytab
• Invoke klist to show the SPNs currently available for use.

A keytab file contains domain access credentials and must be protected accordingly.

HTTP.sys

HTTP.sys supports Kernel Mode Windows Authentication using Negotiate, NTLM, or Basic authentication.

Add authentication services by invoking AddAuthentication (Microsoft.AspNetCore.Server.HttpSys namespace) in Startup.ConfigureServices :

Configure the app’s web host to use HTTP.sys with Windows Authentication (Program.cs). UseHttpSys is in the Microsoft.AspNetCore.Server.HttpSys namespace.

HTTP.sys delegates to Kernel Mode authentication with the Kerberos authentication protocol. User Mode authentication isn’t supported with Kerberos and HTTP.sys. The machine account must be used to decrypt the Kerberos token/ticket that’s obtained from Active Directory and forwarded by the client to the server to authenticate the user. Register the Service Principal Name (SPN) for the host, not the user of the app.

HTTP.sys isn’t supported on Nano Server version 1709 or later. To use Windows Authentication and HTTP.sys with Nano Server, use a Server Core (microsoft/windowsservercore) container. For more information on Server Core, see What is the Server Core installation option in Windows Server?.

Authorize users

The configuration state of anonymous access determines the way in which the [Authorize] and [AllowAnonymous] attributes are used in the app. The following two sections explain how to handle the disallowed and allowed configuration states of anonymous access.

Disallow anonymous access

When Windows Authentication is enabled and anonymous access is disabled, the [Authorize] and [AllowAnonymous] attributes have no effect. If an IIS site is configured to disallow anonymous access, the request never reaches the app. For this reason, the [AllowAnonymous] attribute isn’t applicable.

Allow anonymous access

When both Windows Authentication and anonymous access are enabled, use the [Authorize] and [AllowAnonymous] attributes. The [Authorize] attribute allows you to secure endpoints of the app which require authentication. The [AllowAnonymous] attribute overrides the [Authorize] attribute in apps that allow anonymous access. For attribute usage details, see Simple authorization in ASP.NET Core.

By default, users who lack authorization to access a page are presented with an empty HTTP 403 response. The StatusCodePages Middleware can be configured to provide users with a better «Access Denied» experience.