Explained: Windows Authentication in ASP.NET 2.0

 

Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

patterns & practices Developer Center

patterns & practices Developer Center

J.D. Meier, Alex Mackman, Blaine Wastell, Prashant Bansode, Chaitanya Bijwe

Microsoft Corporation

November 2005

Applies To

  • ASP.NET version 2.0
  • Windows Server 2003
  • Internet Information Services (IIS) 6.0

Summary

This module explains how IIS Integrated Windows authentication and ASP.NET Windows authentication works in ASP.NET version 2.0. It explains how NTLM and Kerberos authentication work. Additionally, this module explains how the WindowsAuthenticationModule class constructs WindowsPrincipal and WindowsIdentity objects, and then attaches the objects to the current ASP.NET Web request to represent the authenticated user.

Contents

Objectives Overview IIS Authentication NTLM Authentication Kerberos Authentication ASP.NET Authentication Security Context Impersonation Delegation Additional Resources

Objectives

  • Learn how Windows authentication works in ASP.NET version 2.0.
  • Learn how Kerberos authentication works.
  • Learn how NTLM authentication works.
  • Learn how the WindowsAuthenticationModule class creates WindowsPrincipal and WindowsIdentity objects.
  • Learn how impersonation affects the WindowsPrincipal and WindowsIdentity objects.

Overview

Authentication is the process of validating client identity, usually by means of a designated third-party authority. The client might be an end user, computer, application, or service. The client's identity is called a security principal. To authenticate with a server application, the client provides some form of credentials to allow the server to verify the client's identity. After the client's identity is confirmed, the application can authorize the principal to perform operations and access resources.

If your application uses an Active Directory user store, you should use Integrated Windows authentication. When you use Integrated Windows authentication with an ASP.NET application, the best approach is to use an Internet Information Services (IIS) authentication method coupled with the Windows authentication provider for ASP.NET. With this approach, a WindowsPrincipal object (encapsulating a WindowsIdentity object) is automatically created to represent the authenticated user. You do not need to write any authentication-specific code.

ASP.NET also supports custom solutions for using Windows authentication, which bypasses IIS authentication. For example, you can write a custom ISAPI filter that checks the user's credentials against Active Directory. With this approach you must manually create a WindowsPrincipal object.

This document explains how Windows authentication works in ASP.NET version 2.0 with IIS 6.0.

IIS Authentication

When ASP.NET is configured for Windows authentication, it relies on IIS to authenticate its clients using the configured authentication mode. IIS determines the authentication mode for a particular application by examining its metabase settings. After successfully authenticating a user, IIS passes the Windows token representing the authenticated user to the ASP.NET worker process (w3wp.exe) in which the ASP.NET application is hosted. If your application uses a virtual directory that is configured in IIS to support anonymous access, the token represents the anonymous Internet user account; otherwise, the token represents the authenticated user.

IIS supports the following modes of authentication:

  • Anonymous. If you do not need to authenticate your clients (or you use a custom authentication mechanism, such as forms authentication), you can configure IIS to allow anonymous access. In this event, IIS creates a Windows token to represent all anonymous users with the same anonymous (or guest) account. The default anonymous account is IUSR_MACHINENAME, where MACHINENAME is the NetBIOS name of the computer that was specified during installation.
  • Basic. Basic authentication requires the user to supply credentials in the form of a user name and password to prove their identity. Basic authentication is based on the Internet standard RFC 2617, and is supported by all popular browsers. The user's credentials are transmitted from the browser to the Web server in an unencrypted Base64-encoded format. To help protect the credentials, you should only use basic authentication with Secure Sockets Layer (SSL). Because the Web server obtains the user's credentials unencrypted, ASP.NET applications can impersonate the caller and use their credentials to access network resources.
  • Integrated Windows. Integrated Windows authentication (formerly called NTLM, and also known as Windows NT Challenge/Response authentication) uses either Kerberos v5 authentication or NTLM authentication, depending upon the client and server configuration. The server negotiates with the client to determine the protocol to use. Kerberos authentication is used if the following conditions are met:
    • Your ASP.NET Web application is running under the NetworkService account or a custom domain account. If your application runs under a local account, such as the ASPNET account on Windows 2000 Server, then NTLM authentication will be used.
    • A service principal name (SPN) exists in Active Directory for the domain account used to run the service with which the client is authenticating.
    • Client and server computers are running at least Windows 2000 Server and are in the same, or trusting, Windows domain.

Note    Integrated Windows authentication is enabled by default for Windows Server 2003 operating systems. However, Integrated Windows authentication is disabled by default if you install Windows Server 2003 Service Pack 1 (SP1) as part of a slipstream installation of a Windows Server 2003 operating system. If you upgrade Windows Server 2003 with SP1, the setting for Integrated Windows authentication is unchanged from its Windows Server 2003 setting.

You should use Integrated Windows authentication instead of basic authentication because it avoids transmitting user credentials over the network. Because Kerberos v5 authentication supports mutual authentication, users can also authenticate the server to which they are connecting.

Integrated Windows authentication is best suited for an intranet environment, where both the client and Web server computers are part of the same, or trusting, domains.

NTLM Authentication

NTLM is the authentication protocol used in Windows NT and in Windows 2000 Server work-group environments. It is also employed in mixed Windows 2000 Active Directory domain environments that must authenticate Windows NT systems. When Windows 2000 Server is converted to native mode where no down-level Windows NT domain controllers exist, NTLM is disabled. Kerberos v5 then becomes the default authentication protocol for the enterprise.

NTLM Authentication Mechanism

Figure 1 shows the NTLM protocol.

Ff647076.ntlmauthentication(en-us,PandP.10).gif

Figure 1. The NTLM challenge/response mechanism

The challenge/response mechanism is outlined below:

  1. User requests access. The user tries to log on to the client by providing user credentials. Before logon, the client computer caches the password hash and discards the password. The client sends a request to the server, which includes the user name along with the request in plain text.
  2. Server sends challenge message. The server generates a 16-byte random number called challenge, or nonce, and sends it to the client.
  3. Client sends response message. The client uses a password hash generated from the user's password to encrypt the challenge sent by the server. It sends this encrypted challenge in the form of a response back to the server.
  4. Server sends challenge and response to domain controller. The server sends the user name, the original challenge, and the response from the client computer to the domain controller.
  5. Domain controller compares challenge and response to authenticate user. The domain controller obtains the password hash for the user, and then uses this hash to encrypt the original challenge. Next, the domain controller compares the encrypted challenge with the response from the client computer. If they match, the domain controller sends the server confirmation that the user is authenticated.
  6. Server sends response to the client. Assuming valid credentials, the server grants the client access to the requested service or resource.

Kerberos Authentication

Kerberos authentication offers the following advantages over NTLM authentication:

  • Mutual authentication. When a client uses the Kerberos v5 protocol for authentication with a particular service on a particular server, Kerberos provides the client with an assurance that the service is not being impersonated by malicious code on the network.
  • Delegation support. Servers that use Kerberos authentication to authenticate clients can impersonate those clients and use the client's security context to access network resources.
  • Performance. Kerberos authentication offers improved performance over NTLM authentication.
  • Simplified trust management. Networks with multiple domains no longer require a complex set of explicit, point-to-point trust relationships.
  • Interoperability. Microsoft's implementation of the Kerberos protocol is based on standards-track specifications recommended to the Internet Engineering Task Force (IETF). As a result, the implementation of the protocol in Windows 2000 lays a foundation for interoperability with other networks where Kerberos version 5 is used for authentication.

Kerberos Authentication Mechanism

A simplified view of the Kerberos authentication protocol is shown in Figure 2.

Ff647076.kerberosauthentication(en-us,PandP.10).gif

Figure 2. Kerberos authentication

When a client authenticates against a network service, the Kerberos v5 protocol follows these steps:

  1. Client requests TGT from KDC. The user tries to log on to the client by providing user credentials. The Kerberos service on the client computer sends a Kerberos authentication service request to the Key Distribution Center (KDC). The request contains the user name, the service information for which the ticket-granting ticket (TGT) is requested, and a time stamp that is encrypted using the user's long-term key, or password.

    Note    On Windows 2000 Server or Windows Server 2003 operating systems, a domain controller acts as a KDC, and Active Directory hosts the security account database.

  2. Authentication service sends encrypted TGT and session key. The KDC gets the long-term key, or password, for the user from Active Directory, and then decrypts the time stamp that was passed along with the request. If the time stamp is valid, the user is genuine. The KDC authentication service creates a logon session key and encrypts the copy with the user's long-term key. The authentication service then creates a TGT, which includes user information and a logon session key. Finally, the authentication service encrypts the TGT with its own key and passes both the encrypted session key and the encrypted TGT to client.

  3. Client requests server access from TGT. The client decrypts the logon session key using its long-term key, or password, and caches it locally. Additionally, the client stores the encrypted TGT in its cache. When accessing a network service, the client sends a request to the KDC ticket-granting service (TGS) with information, including the user's name, an authenticator message encrypted using the user's logon session key, the TGT, and the name of the service (and server) that the user wants to access.

  4. TGS sends encrypted session key and ticket. The TGS on the KDC decrypts the TGT using its own key and extracts the logon session key. Using the logon session key, it decrypts the authenticator message (which is usually a time stamp). If the authenticator message is successfully decrypted, the TGS extracts user information from the TGT, and using the user information creates a service session key for accessing the service. It encrypts one copy of the service session key with the user's logon session key, creates a service ticket with the service session key and user information, and then encrypts the service ticket with the server's long term key (password). The TGS then sends the encrypted service session key and service ticket to the client.

  5. Client sends service ticket. When a client accesses the service, it sends a request to the server. The request contains the authenticator message (time stamp), which is encrypted using the service session-key and the service ticket.

  6. Server sends encrypted time stamp for client validation. The server decrypts the service ticket and extracts the service session-key. Using the service session-key, the server decrypts the authenticator message (time stamp) and evaluates it. If the authenticator passes the test, the server encrypts the authenticator (time stamp) using the service session-key and then passes the authenticator back to the client. The client decrypts the time stamp, and if it is the same as the original, the service is genuine and the client proceeds with the connection.

Service Principal Names

The Kerberos v5 authentication protocol uses service principal names (SPNs) for the following reasons:

  • To support mutual authentication.
  • To enable a client to request tickets, which in turn, enables the client to communicate with a particular service.

For example, if a client needs to obtain a ticket and authenticate with a particular service (MyService), which is running on a computer (MyServer) that is listening on port 4766, then the client requests a ticket from the KDC by using a name constructed from that information, as shown here:

MyService/MyServer:4766

An SPN that is registered in Active Directory maintains a mapping between this name and the domain account under which the requested service is running. By using this mechanism, it becomes difficult for a malicious user to impersonate a service on the network. The malicious user must disable the actual service and remove the actual server from the network. Then the malicious user must add a new computer to the network with the same name and expose the duplicated service. Because the client uses the Kerberos v5 protocol with mutual authentication, the client will not be able to use the duplicated service unless it can provide the password for the domain account under which the actual service is configured to run.

ASP.NET Authentication

IIS passes to ASP.NET the token that represents the authenticated user or anonymous user account. This token is maintained inside an IIdentity object that is contained inside an IPrincipal object, which, in turn, is attached to the current Web request thread. The IPrincipal and IIdentity objects can be accessed through the HttpContext.User property. These objects and this property are set by authentication modules, which are implemented as HTTP modules and invoked as a standard part of the ASP.NET pipeline, which is shown in Figure 3.

Ff647076.refaspnetpipelineprocessing(en-us,PandP.10).gif

Figure 3. ASP.NET pipeline

The ASP.NET pipeline model consists of an HttpApplication object, various HTTP module objects, and an HTTP handler object, along with their associated factory objects. An HttpRuntime object is used at the start of the processing sequence. Throughout the request life cycle, an HttpContext object is used to convey details about the request and response.

For more information about the ASP.NET request life cycle, see "ASP.NET Life Cycle" at https://msdn.microsoft.com/en-us/library/ms227435(VS.80).aspx.

Authentication Modules

ASP.NET 2.0 defines a set of HTTP modules in the machine-level Web.config file. These include a number of authentication modules as shown here:

<httpModules>

  <add name="WindowsAuthentication"
    type="System.Web.Security.WindowsAuthenticationModule" />
  <add name="FormsAuthentication" 
    type="System.Web.Security.FormsAuthenticationModule" />
  <add name="PassportAuthentication" 
    type="System.Web.Security.PassportAuthenticationModule" />

</httpModules>

Only one authentication module is loaded, and this is dependent on which authentication mode has been specified in the authentication element of the configuration file. The authentication module creates an IPrincipal object and stores it in the HttpContext.User property. This is vital because other authorization modules use this IPrincipal object to make authorization decisions.

When anonymous access is enabled in IIS and the mode attribute of the authentication element is set to none, there is a special module that puts a default anonymous principal into the HttpContext.User property. As a result, HttpContext.User is never a null reference (Nothing in Visual Basic) after authentication.

WindowsAuthenticationModule

The WindowsAuthenticationModule class is activated when the following element is in the Web.config file.

<authentication mode="Windows" />

The WindowsAuthenticationModule class is responsible for creating WindowsPrincipal and WindowsIdentity objects to represent the authenticated user, and for attaching these objects to the current Web request.

For Windows authentication, the following sequence occurs:

  1. The WindowsAuthenticationModule class creates a WindowsPrincipal object using the Windows access token that is passed from IIS to ASP.NET. This token is wrapped in the WorkerRequest property of the HttpContext class. When the AuthenticateRequest event is raised, the WindowsAuthenticationModule retrieves the token from the HttpContext class and creates the WindowsPrincipal object. The HttpContext.User property is set with this WindowsPrincipal object and represents the security context of the authenticated user for all authorization modules and ASP.NET pages.
  2. The WindowsAuthenticationModule class uses P/Invoke to call Win32 functions and obtain the list of Windows groups to which the user belongs. These groups are used to populate the WindowsPrincipal role list.
  3. The WindowsAuthenticationModule class stores the WindowsPrincipal object in the HttpContext.User property. This is subsequently used by authorization modules to authorize the authenticated user.

Note: The DefaultAuthenticationModule class, which is also part of the ASP.NET pipeline, sets the Thread.CurrentPrincipal property to the same value as the HttpContext.User property. It does so after the AuthenticateRequest event is handled.

Authorization Modules

After the WindowsAuthenticationModule class has finished its processing, the authorization modules are called if the request has not been rejected. The authorization modules are also defined in the httpModules element in the machine-level Web.config file as shown here:

<httpModules>
  <add name="UrlAuthorization" 
    type="System.Web.Security.UrlAuthorizationModule" />
  <add name="FileAuthorization" 
    type="System.Web.Security.FileAuthorizationModule" />
  <add name="AnonymousIdentification" 
    type="System.Web.Security.AnonymousIdentificationModule" />
</httpModules>

UrlAuthorizationModule

When the UrlAuthorizationModule class is called, it checks for an authorization element in either the machine-level or application-specific Web.config file. If present, the UrlAuthorizationModule class retrieves the IPrincipal object from the HttpContext.User property, and then determines whether the user is authorized to access the requested resource by using the specified verb (GET, POST, and so on).

FileAuthorizationModule

Next, the FileAuthorizationModule class is called. It checks whether the IIdentity object in the HttpContext.User.Identity property is an instance of the WindowsIdentity class. If the IIdentity object is not an instance of the WindowsIdentity class, then the FileAuthorizationModule class stops processing.

If an instance of the WindowsIdentity class is present, the FileAuthorizationModule class calls the AccessCheck Win32 function (through P/Invoke) to determine whether the authenticated client is authorized to access the requested file. If the file's security descriptor contains at least a Read Access Control Entry (ACE) in its Discretionary Access Control List (DACL), the request is allowed to proceed. Otherwise, the FileAuthorizationModule class calls the HttpApplication.CompleteRequest method and returns a 401 status code to the client.

Security Context

The .NET Framework encapsulates Windows tokens and logon sessions with the following two interfaces:

  • System.Security.Principal.IPrincipal
  • System.Security.Principal.IIdentity (This is exposed as a property in the IPrincipal interface.)

HttpContext.User

In ASP.NET, the security context of a user that is authenticated with Windows authentication is represented by the WindowsPrincipal and WindowsIdentity classes. ASP.NET applications that use Windows authentication can access the WindowsPrincipal class through the HttpContext.User property.

To retrieve the security context of the Windows authenticated user that initiated the current request, use the following code:

using System.Security.Principal;
...
// Obtain the authenticated user's Identity
WindowsPrincipal winPrincipal = (WindowsPrincipal)HttpContext.Current.User;

WindowsIdentity.GetCurrent

The WindowsIdentity.GetCurrent method can be used to obtain the identity of the security context of the Win32 thread that is currently running. Without impersonation, the thread inherits the security context of the process on IIS 6.0, which is the NetworkService account by default.

This security context is used when accessing local resources. You can override this security context with impersonation by using either the original authenticated user's security context or by using a fixed identity.

To retrieve the security context under which the application is running, use the following code:

using System.Security.Principal;
...
// Obtain the authenticated user's identity.
WindowsIdentity winId = WindowsIdentity.GetCurrent();
WindowsPrincipal winPrincipal = new WindowsPrincipal(winId);

Thread.CurrentPrincipal

Each thread in an ASP.NET application exposes a CurrentPrincipal object, which holds the original authenticated user's security context. This security context can be used for role-based authorization.

To retrieve the thread's current principal, use following code:

using System.Security.Principal;
...
// Obtain the authenticated user's identity
WindowsPrincipal winPrincipal = (WindowsPrincipal) Thread.CurrentPrincipal();

Table 1 shows the resulting identities that are obtained from the various identity properties available to ASP.NET application code when your application uses Windows authentication and IIS is configured to use Integrated Windows authentication.

Table 1: Thread Exposed CurrentPrincipal Object

Web.config settings Variable location Resultant identity
<identity impersonate="true"/>
<authentication mode="Windows" />
HttpContext
WindowsIdentity
Thread
Domain\UserName
Domain\UserName
Domain\UserName
<identity impersonate="false"/>
<authentication mode="Windows" />
HttpContext
WindowsIdentity
Thread
Domain\UserName
NT AUTHORITY\NETWORK SERVICE
Domain\UserName
<identity impersonate="true"/>
<authentication mode="Forms" />
HttpContext
WindowsIdentity
Thread
Name provided by user
Domain\UserName
Name provided by user
<identity impersonate="false"/>
<authentication mode="Forms" />
HttpContext
WindowsIdentity
Thread
Name provided by user
NT AUTHORITY\NETWORK SERVICE
Name provided by user

Impersonation

An ASP.NET application can use impersonation to perform operations and access resources with the security context of the authenticated client or of a specific Windows account.

Original User Impersonation

To impersonate the original (authenticated) user, use the following configuration in the Web.config file:

<authentication mode="Windows" />
<identity impersonate="true" />

With this configuration, ASP.NET always impersonates the authenticated user, and all resource access is performed using the authenticated user's security context. If anonymous access is enabled on your application's virtual directory, the IUSR_MACHINENAME account is impersonated.

To temporarily impersonate the authenticated caller, set the impersonate attribute of the identity element to false, and then use the following code:

using System.Security.Principal;
...
// Obtain the authenticated user's identity.
WindowsIdentity winId = (WindowsIdentity)HttpContext.Current.User.Identity;
WindowsImpersonationContext ctx = null;
try
{
    // Start impersonating.
    ctx = winId.Impersonate();
    // Now impersonating.
    // Access resources using the identity of the authenticated user.
}
// Prevent exceptions from propagating.
catch
{
}
finally
{
    // Revert impersonation.
    if (ctx != null)
        ctx.Undo();
}
// Back to running under the default ASP.NET process identity.

This code impersonates the original authenticated user. The original user's identity and Windows token are maintained in the HttpContext.Current.User.Identity object.

Fixed Identity Impersonation

If you need to impersonate the same identity throughout the lifetime of your application, you can specify credentials on the identity element in your Web.config file. The following example shows how to impersonate a Windows account named "TestUser".

<identity impersonate="true" username="TestUser" password="P@ssw0rd" />

If you use this approach, you should encrypt the credentials. With ASP.NET 2.0, you can use the ASP.NET IIS Registration Tool (Aspnet_regiis.exe). With ASP.NET version 1.1, you can use the Aspnet_setreg.exe utility. For more information about this utility, see https://msdn.microsoft.com/en-us/library/k6h9cz8h(VS.71).aspx.

To use a fixed identity for resource access in ASP.NET applications, you can configure credentials by using the identity element on Windows 2000 Server or Windows Server 2003. If you are running Windows Server 2003 with IIS 6.0 configured to run in worker process isolation mode (the default), you can avoid impersonation by configuring your ASP.NET application to run in a custom application pool that runs under a specific domain identity. Then you can use the specified domain identity to access resources without using impersonation.

Delegation

Impersonation gives access to local resources only. Delegation is an extended impersonation capability that enables you to use an impersonation token to access network resources.

If your application uses Kerberos v5 authentication to authenticate its users, you can use Kerberos delegation to pass the user's identity through the layers of your application and to access network resources. If your application does not use Kerberos v5 authentication, you can use protocol transition to switch to Kerberos, and then use delegation to pass on the identity.

Constrained delegation in Windows Server 2003 requires Kerberos authentication. If your application cannot use Kerberos authentication to authenticate its callers, you can use protocol transition to switch from an alternate, non-Windows authentication mode (such as forms or certificate authentication) to Kerberos authentication. You can then use Kerberos with constrained delegation to access downstream network resources.

Constrained and Unconstrained Delegation

Kerberos delegation on Windows 2000 Server is unconstrained. Servers that are configured for delegation in Active Directory can access any network resources or any computer on the network while using the impersonated user's security context. This represents a potential security threat, particularly if the Web server is compromised by a malicious user.

To address this security issue, Windows Server 2003 introduces constraineddelegation. This enables administrators to specify exactly which services another server or domain account can access when using an impersonated user's security context.

Configuring Delegation

To use Kerberos delegation, appropriate Active Directory configuration is required.

To grant the Web server the right to delegate client credentials, configure Active Directory as follows:

  • If you run your application under the NetworkService account, the Web server computer account must be marked in Active Directory as trusted for delegation.
  • If you run your application under a custom domain account, this user account must be marked in Active Directory as trusted for delegation.
  • If your application impersonates a user account, make sure that the user account your application impersonates is not marked as "Sensitive and cannot be delegated" in Active Directory.

For more information about protocol transition and constrained delegation, see How To: Use Protocol Transition and Constrained Delegation in ASP.NET 2.0.

Additional Resources

Feedback

Provide feedback by using either a Wiki or e-mail:

We are particularly interested in feedback regarding the following:

  • Technical issues specific to recommendations
  • Usefulness and usability issues

Technical Support

Technical support for the Microsoft products and technologies referenced in this guidance is provided by Microsoft Support Services. For product support information, please visit the Microsoft Support Web site at https://support.microsoft.com.

Community and Newsgroups

Community support is provided in the forums and newsgroups:

To get the most benefit, find the newsgroup that corresponds to your technology or problem. For example, if you have a problem with ASP.NET security features, you would use the ASP.NET Security forum.

Contributors and Reviewers

  • External Contributors and Reviewers: Jason Taylor, Security Innovation; Rudolph Araujo, Foundstone Professional Services
  • Microsoft PSS Contributors and Reviewers: Tom Christian, Wade Mascia
  • Microsoft Product Group: Stefan Schackow
  • Test team: Larry Brader, Microsoft Corporation; Nadupalli Venkata Surya Sateesh, Sivanthapatham Shanmugasundaram, Infosys Technologies Ltd.
  • Edit team: Lara Ballinger, Nelly Delgado, Microsoft Corporation
  • Release Management: Sanjeev Garg, Microsoft Corporation

patterns & practices Developer Center

Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.