How To: Use 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, Andy Wigley, Kishore Gopalan

Microsoft Corporation

August 2005

Applies To

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

Summary

This How To shows you how to configure and use Windows authentication in an ASP.NET Web application. Windows authentication is the preferred approach whenever users are a part of your Windows domain. This approach enables you to use an existing identity store such as your corporate Active Directory, and does not transmit passwords over the network. This How To also shows various impersonation options available with Windows authentication and how to configure and use them with ASP.NET applications. It also explains how to use the various authorization mechanisms including file authorization, URL authorization, and role-based authorization, with Windows authentication.

Contents

Objectives
Overview
Configuring Windows Authentication
Using Impersonation with Windows Authentication
Authorizing Windows Users
Kerberos Authentication
Additional Resources

Objectives

  • Learn how to configure your Web application for using Windows authentication.
  • Use impersonation with Windows authentication in ASP.NET applications.
  • Authorize users authenticated with Windows authentication.

Overview

ASP.NET supports various authentication modes, including Windows authentication, forms authentication, Passport authentication, and custom authentication. You should choose Windows authentication if your user accounts are maintained by a Microsoft® Windows NT… domain controller or within Microsoft Windows… Active Directory™ and there are no firewall issues.

The main benefit of using Windows authentication is that it can be coupled with IIS authentication so that you don't have to write any custom code. Compared to other authentication mechanisms, Windows authentication does not pass the user credentials over the wire. Windows authentication also provides a seamless user experience. Therefore Windows authentication should be used wherever possible.

When you configure ASP.NET for Windows authentication, it can be coupled with IIS authentication where IIS authenticates your application's users by using Basic authentication, Integrated Windows authentication, Digest authentication, or Client Certificate authentication. Both Integrated Windows authentication and Client Certificate authentication provide strong authentication, but Integrated Windows authentication is recommended unless you have a PKI infrastructure and your clients have certificates.

IIS authenticates the user and passes a Windows token for the authenticated user to ASP.NET along with each Web request.

Impersonation Options

You can use Windows authentication with ASP.NET in a number of ways:

  • Windows authentication without impersonation. This is the default setting. ASP.NET performs operations and accesses resources by using your application's process identity, which by default is the Network Service account on Windows Server 2003.
  • Windows authentication with impersonation. With this approach, you impersonate the authenticated user and use that identity to perform operations and access resources.
  • Windows authentication with fixed-identity impersonation. With this approach, you impersonate a fixed Windows account to access resources using a specific identity. On Windows Server 2003, you should avoid this impersonation approach; instead, use a custom application pool with a custom service identity.

Authorization Options

Regardless of impersonation, you can authorize users and control access to resources and business operations by using the following mechanisms:

  • URL authorization. You use URL authorization to control access to requested files and folders based on the request URL. You configure URL authorization by using an <authorization> element in the Web.config file to control which users and groups of users should have access to requested resources. Authorization is based on the IPrincipal object stored in HttpContext.User. With Windows authentication, this object is of type WindowsPrincipal and it contains a WindowsIdentity object that holds the Windows token for the authenticated user.

    Note ASP.NET version 2.0 on Windows Server 2003 protects all files in a particular directory, even those not mapped to ASP.NET such as .html, .gif, and .jpg files.

  • File authorization. For file types mapped by IIS to the ASP.NET ISAPI extension (Aspnet_isapi.dll), automatic access checks are performed using the authenticated user's Windows access token against the access control list (ACL) attached to the requested ASP.NET file. The FileAuthorizationModule class only performs access checks against the requested file. For example, if you request Default.aspx and it contains an embedded user control (Usercontrol.ascx), which in turn includes an image tag (pointing to Image.gif), the FileAuthorizationModule performs an access check for Default.aspx and Usercontrol.ascx, because these file types are mapped by IIS to the ASP.NET ISAPI extension. The FileAuthorizationModule does not perform a check for Image.gif, because this is a static file handled internally by IIS. However, because access checks for static files are performed by IIS, the authenticated user must still be granted read permission to the file with an appropriately configured ACL.

    Note Impersonation is not required for file authorization.

  • Role checks. You can check the authenticated user's role membership by using methods such as User.IsInRole and Roles.IsUserInRole. This allows you to perform fine-grained authorization logic. To use the Roles API, you need to enable role manager for your application. You can also use principal permission demands and use class-level and method-level declarative security to control which users should be allowed to call classes and methods.

Configuring Windows Authentication

To configure your application to use Integrated Windows authentication, you must use IIS Manager to configure your application's virtual directory security settings and you must configure the <authentication> element in the Web.config file.

To configure Windows authentication

  1. Start Internet Information Services (IIS).
  2. Right-click your application's virtual directory, and then click Properties.
  3. Click the Directory Security tab.
  4. Under Anonymous access and authentication control, click Edit.
  5. Make sure the Anonymous access check box is not selected and that Integrated Windows authentication is the only selected check box.

In your application's Web.config file or in the machine-level Web.config file, ensure that the authentication mode is set to Windows as shown here.

...
 <system.web>
  ...
  <authentication mode="Windows"/>
  ...
 </system.web>
 ...
  

Using Impersonation with Windows Authentication

By using impersonation, ASP.NET applications can execute code or access resources with the identity of the authenticated user or a fixed Windows identity. Standard impersonate-level impersonation tokens that are usually created when you enable impersonation allow you to access local resources only. To be able to access remote network resources, you require a delegate-level token. To generate a delegate-level token when you impersonate, you need to use Kerberos authentication and your process account needs to be marked as trusted for delegation in Active Directory.

By default, ASP.NET applications are not configured for impersonation. You can confirm this by reviewing the identity settings in the Machine.config.comments file located in the following folder: %windir%\Microsoft.Net\Framework\{Version}\CONFIG.

The <identity> element is configured as follows. Note that impersonation is disabled.

<identity impersonate="false" userName="" password="" />
  

Impersonating the Original Caller with Windows Authentication

When you configure your application for impersonation, an impersonation token for the authenticated user is attached to the Web request thread. As a result, all local resource access is performed using the caller's identity.

To configure ASP.NET to use Windows authentication with impersonation, use the following configuration.

...
 <system.web>
    ...
    <authentication mode="Windows"/>
    <identity impersonate="true"/>
    ...
 </system.web>
 ...
  

The resulting impersonation token and associated logon session does not have network credentials. If you access this Web site from a browser while logged onto a different machine in the same domain and the Web site attempts to access network resources, you end up with a null session on the remote server and the resource access will fail. To access remote resources, you need delegation. For more information about how to use delegation, see How To: Use Protocol Transition and Constrained Delegation in ASP.NET 2.0.

Impersonating a Fixed Identity with Windows Authentication

You can configure ASP.NET to impersonate a fixed identity. You specify the credentials of the impersonated identity on the <identity> element in the Web.config file as shown here.

...
 <system.web>
  ...
  <authentication mode="Windows"/>
    <identity impersonate="true" userName="<domain>\<UserName>" password="<password>"/>
    ...
 </system.web>
 ...
  

If you specify credentials on the <identity> element, make sure they are stored in encrypted format by using the Aspnet_regiis.exe tool. For more information, see How To: Encrypt Configuration Sections in ASP.NET Using DPAPI and How To: Encrypt Configuration Sections in ASP.NET Using RSA.

Note Specifying credentials on the <identity> element should be avoided where possible. If you need a specific identity to access resources, and your application runs on Windows Server 2003, use a custom application pool with a custom service account identity instead. This approach avoids impersonation.

Impersonating the Original Caller Programmatically

If you only require an impersonated identity to access specific resources or perform specific operations and can use your process identity the rest of the time, you can use programmatic impersonation to temporarily enable impersonation.

To temporarily impersonate the authenticated user

This procedure shows you how to temporarily impersonate the original caller by using the Windows token that is passed by IIS to your Web application and is available through the HttpContext object.

  1. Check that your ASP.NET application is not configured for impersonation by ensuring that impersonate is set to false on the <identity> element in the Web.config file.

    ...
     <system.web>
      ...
      <authentication mode="Windows"/>
      <identity impersonate="false"/>
      ...
     </system.web>
     ...
    
    
  2. Obtain the authenticated user's Windows token.

    IIdentity WinId= HttpContext.Current.User.Identity;
    WindowsIdentity wi = (WindowsIdentity)WinId;
    
    
  3. Use the authenticated user's Windows token to temporarily impersonate the original user and remove the impersonation token from the current thread when you are finished impersonating.

    // Temporarily impersonate the original user.
    WindowsImpersonationContext wic = wi.Impersonate();
    try
    {
      // Access resources while impersonating.
    }
    catch
    {
      // Prevent exceptions propagating.
    }
    finally
    {
      // Revert impersonation.
      wic.Undo();
    }
    
    

Authorizing Windows Users

When you use Windows authentication to authenticate users, you can use the following authorization options:

  • File authorization provided by the FileAuthorizationModule.
  • URL authorization provided by the UrlAuthorizationModule.
  • Role-based authorization.

Note File authorization requires Windows authentication. The other authorization options are available with other authentication mechanisms.

Configuring Windows ACLs for File Authorization

Requests for file types mapped to the ASP.NET ISAPI extension are checked by the FileAuthorizationModule. When you use Windows authentication, the authenticated user's Windows token is compared against the ACL attached to the requested file. For static files types that are not mapped to the ASP.NET ISAPI extension, IIS performs access checks again by using the authenticated user's access token and the ACL attached to the file. You need to configure appropriate ACLs on the file types directly requested by the user and on the files and other Windows resources accessed by your application, as described here:

  • Forresources directly requested by the user. For resources such as Web pages (.aspx files) and Web services (.asmx files) directly requested by the user, the authenticated user's Windows access token is compared against the Windows ACL attached to the file. Make sure that the authenticated user is allowed to access the appropriate Web pages and Web services.
  • For resources that the application accesses. If impersonation is enabled, resources such as files, databases, registry keys, and Active Directory objects are accessed by using the impersonated identity. Otherwise, your application's process identity, such as the Network Service account, is used for resource access. For the resource access attempt to succeed, the ACL attached to these resources must be suitably configured to allow the process account or impersonated identity the access it requests, such as read access, or write access.

Configuring URL Authorization

When you use Windows authentication, the UrlAuthorizationModule checks the access to requested files and folders based on the authenticated caller's identity. This is true regardless of whether your application is configured for impersonation.

To configure URL authorization, add an <authorization> element to the Web.config file, and specify the domain name and user or group name when configuring <deny> and <allow> elements, as shown here.

<authorization>
 <deny users="DomainName\UserName" />
 <allow roles="DomainName\WindowsGroup" />
</authorization>
  

When you use Windows authentication, user names take the form domainName\userName. Windows groups are used as roles and they take the form domainName\windowsGroupName. Well known local groups such as Administrators and Users are referenced by using the "BUILTIN" prefix as shown here.

<authorization>
  <allow users="DomainName\Bob, DomainName\Mary" />
  <allow roles="BUILTIN\Administrators, DomainName\Manager" />
  <deny users="*" />
</authorization>
  

Checking Role Membership in Code

With Windows authentication, the user's Windows group membership can be used to determine the role membership and Window groups become the roles. You can perform role-based authorization in code either by performing explicit role checks (User.IsInRole or Roles.IsUserInRole), or by using PrincipalPermission demands. You can do the latter either imperatively in the body of a method or declaratively by adding attributes to your classes and methods.

To use explicit role checks:

  • Use the IPrincipal interface of the User object attached to the current HTTP request. This approach works with ASP.NET versions 1.0, 1.1. and 2.0. When using Windows authentication, make sure to use the domainName\userName format for the user name and the format domainName\groupName for the group name.

    if(User.IsInRole(@"DomainName\Manager"))
      // Perform restricted operation
    else
      // Return unauthorized access error.
    
    
  • Alternatively, use role manager APIs introduced in ASP.NET version 2.0, which supports a similar Roles.IsUserInRole method, as shown here.

    if(Roles.IsUserInRole(@"DomainName\Manager"))
      // Perform restricted operation
    else
      // Return unauthorized access error.
    
    

    To use the role manager API, you must enable role manager. With Windows authentication, you can use the built-in AspNetWindowsTokenRoleProvider, which uses Windows groups as roles. To enable role manager and select this provider, add the following configuration to your Web.config file.

    <roleManager enabled="true"
                 defaultProvider="AspNetWindowsTokenRoleProvider"/>
    
    

    When you use Windows authentication, you can use alternate role providers, such as the AuthorizationStoreRoleProvider and SqlRoleProvider, if you need to store roles in alternate role stores such as Authorization Manager policy stores or SQL Server databases. For more information, see How To: Use Role Manager in ASP.NET 2.0.

To use PrincipalPermission demands

  • Construct a PrincipalPermission object, and then call its Demand method to perform authorization.

  • For fine grained authorization, call PrincipalPermission.Demand within code, as shown here.

    using System.Security.Permissions;
    ...
    // Imperative checks 
    PrincipalPermission permCheckUser = new PrincipalPermission(@"Domain\Bob", null);
    permCheckUser.Demand();
    
    
  • Alternatively, you can decorate your classes or methods with the PrincipalPermissionAttribute, as shown here.

    using System.Security.Permissions;
    ...
     [PrincipalPermission(SecurityAction.Demand,Role=@"Builtin\Administrators")]
    
    

    The advantage of this approach is that the security requirements of your methods are visible to tools such as Permview.exe.

Kerberos Authentication

When you configure IIS for Integrated Windows authentication, it uses either NTLM or Kerberos authentication, depending on the configuration of client and servers. Kerberos authentication offers a performance benefit and also supports additional features such as the ability to use delegation and mutual authentication.

To use Kerberos authentication

  • All servers must be running Windows 2000 Server or later.
  • Client computers must be running Internet Explorer 5.5 or later.
  • All computers must be in a Windows 2000 Server or later domain.
  • Internet Explorer security settings must be configured to enable Integrated Windows authentication. By default, Integrated Windows authentication is not enabled in Internet Explorer 6. To enable the browser to respond to a negotiate challenge and perform Kerberos authentication, select the Enable Integrated Windows Authentication check box in the Security section of the Advanced tab of the Internet Options menu, and then restart the browser.
  • If you use a custom service account to run your ASP.NET application, you a Service Principal Name (SPN) must be registered for the account in Active Directory.

To register an SPN, use the Setspn.exe utility by running the following commands from a command prompt:

setspn -A HTTP/webservername domain\customAccountName

setspn -A HTTP/webservername.fullyqualifieddomainname domain\customAccountName

Note that you cannot have multiple Web applications with the same host name if you want them to have multiple identities and to use Kerberos authentication. This is an HTTP limitation, not a Kerberos limitation. The workaround is to have multiple Domain Name System (DNS) names for the same host, and then start the URLs for each Web application with a different DNS name. For example, you would use http://app1 and http://app2 instead of http://site/app1 and http://site/app2.

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: Eric Marvets, Dunn Training and Consulting; Jason Taylor, Security Innovation; Rudolph Araujo, Foundstone Professional Services
  • Microsoft Consulting Services and PSS Contributors and Reviewers: Adam Semel, Tom Christian, Wade Mascia
  • Microsoft Product Group Contributors and Reviewers: Stefan Schackow
  • Test team: Larry Brader, Microsoft Corporation; Nadupalli Venkata Surya Sateesh, Infosys Technologies Ltd; Sivanthapatham Shanmugasundaram, Infosys Technologies Ltd
  • Edit team: Nelly Delgado, Microsoft Corporation; Tina Burden McGrayne, TinaTech Inc.
  • 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.