Microsoft KB Archive/315736

= How To Secure an ASP.NET Application by Using Windows Security =

Article ID: 315736

Article Last Modified on 12/3/2007

-

APPLIES TO


 * Microsoft ASP.NET 1.0
 * Microsoft Internet Information Services 5.0
 * Microsoft ASP.NET 1.1
 * Microsoft Internet Information Services 6.0

-



This article was previously published under Q315736



This article refers to the following Microsoft .NET Framework Class Library namespaces:
 * System.Security

IN THIS TASK

 * SUMMARY
 * Requirements
 * How to Develop the Web Site
 * How to Disable Anonymous Access
 * Authorization
 * How to Enable Impersonation
 * How to Assign a Custom Principal
 * Troubleshooting
 * REFERENCES



SUMMARY
ASP.NET can be used together with Microsoft Internet Information Services (IIS) to authenticate Web users based on their Microsoft Windows 2000 or Windows Server 2003 user account credentials. The ASP.NET execution engine can also be configured to impersonate Web users, or to use its own Windows identity when it accesses resources such as databases or files.

Back to the top

Requirements
You need the following hardware, software, and network infrastructure to perform the procedures in this article:
 * Windows 2000 Server Service Pack 2
 * IIS 5.0
 * Windows Server 2003 with IIS 6.0
 * Microsoft Internet Explorer 6.0
 * Microsoft Visual Studio .NET

You also need experience with the following:
 * ASP.NET development with Visual Basic .NET
 * IIS administration
 * Windows 2000 user account administration

Back to the top

How to Develop the Web Site
In this procedure, you will create a simple ASP.NET Web application, which will be secured by using Windows authentication.  Start Visual Studio .NET, and then create a new Visual Basic ASP.NET Web application named &quot;WindowsSite.&quot; Drag a label control from the toolbox onto the WebForm1.aspx Web form, and then set its ID property to authUserPrincipalLabel . Drag a second label control from the toolbox onto the WebForm1.aspx Web form, and then set its ID property to aspPrincipalLabel .  Double-click WebForm1.aspx to view the code window, and then add the following Imports statement above the class declaration: Imports System.Security Add the following code to the Page_Load event procedure: Dim authUserName As String Dim aspUserName As String authUserName = User.Identity.Name aspUserName = Principal.WindowsIdentity.GetCurrent.Name authUserPrincipalLabel.Text = &quot;You are: &quot; & authUserName aspPrincipalLabel.Text = &quot;This page runs as: &quot; & aspUserName  View the project's Web.config file, and then locate the  element. Verify that the mode attribute has a value of Windows. Build and save the project. Run the project, and then confirm that the page is displayed with the following message: <ul> In Windows 2000

You are:

This page runs as: \ASPNET

</li> In Windows Server 2003

You are:

This page runs as: \NETWORK SERVICE

</li></ul>

Note Your user name is not displayed because you have not been authenticated by IIS; anonymous access is still enabled.</li> Quit Internet Explorer to stop the project.</li></ol>

Back to the top

How to Disable Anonymous Access
In this procedure, you will configure IIS to require Windows-integrated authentication for the WindowsSite site. <ol> Minimize Visual Studio, and then start Internet Services Manager from the Administrative Tools program group.</li> Expand your server and its default Web site, right-click the WindowsSite site, and then click Properties.</li> On the Directory Security tab in the WindowsSite Properties dialog box, click the Edit button in the &quot;Anonymous access and authentication control&quot; section.</li> Click to clear the Anonymous access check box, verify that the Integrated Windows authentication check box is selected, and then click OK.</li> Click OK to close the WindowsSite Properties dialog box.</li> Switch back to Visual Studio, and then run the project. Confirm that the page is displayed with the following message: <ul> In Windows 2000

You are:

This page runs as: \ASPNET

</li> In Windows Server 2003

You are:

This page runs as: \NETWORK SERVICE

</li></ul>

Note You have been authenticated through your Windows account. If you had not been logged on to Windows, you would have been prompted for a Windows user name and password.</li> Quit Internet Explorer to stop the project.</li></ol>

Back to the top

Authorization
In ASP.NET, it is possible to allow authorization to the application when you make additional settings available within the Web.config file. You can allow certain users or certain groups access to these additional settings. The following examples describe this capability. To allow access to all users found in the Windows NT Group that is called &quot;Managers,&quot; use the following code: <system.web> <allow roles=&quot;domainname\Managers&quot; /> <deny users=&quot;*&quot; /> </system.web> To allow access to only certain users, use the following code: <system.web> <allow users=&quot;domainname\user1,domainname\user2,domainname\user3&quot; /> <deny users=&quot;*&quot; /> </system.web> Note You can reference multiple roles or users when you use a comma-separated list.

Back to the top

How to Enable Impersonation
In this procedure, you will configure the WindowsSite application to impersonate the Windows user who is accessing it. <ol> In Visual Studio, view the Web.config file for the WindowsSite project.</li>  Add the following element after the  element: <identity impersonate = &quot;true&quot; /> </li> Save Web.config.</li> <li>Run the project. Confirm that the page is displayed with the following message (note that the ASP.NET execution engine will use your Windows credentials to access resources on your behalf):

You are:

This page runs as:

</li> <li>Quit Internet Explorer to stop the project.</li></ol>

Back to the top

How to Assign a Custom Principal
In this procedure, you will configure the WindowsSite application to use a custom security principal: <ol> <li>Start the Computer Management feature from the Administrative Tools program group. Create a new Windows 2000 user account named &quot;WindowsSite,&quot; with a password of &quot;password&quot; (note whether your server is a domain controller, and then use the Active Directory Users and Computers tool).</li> <li>Click to clear the User must change password at next logon check box.Note The custom principal that you select must have the permissions that are outlined in the following Knowledge Base article:

317012 INFO: Process and Request Identity in ASP.NET

</li> <li>When the WindowsSite account has been created, close the administrative tool that you used to create it.</li> <li>In Visual Studio, view the Web.config file for the WindowsSite project.</li> <li>Edit the  element to read as follows:

<pre class="fixed_text">identity impersonate = &quot;true&quot; userName = &quot;DomainOrServerName\WindowsSite&quot;

password = &quot;password&quot;/>

where  is either the name of your Windows 2000 or Windows Server 2003 domain (in a domain environment) or of your computer (in a workgroup environment).</li> <li>Save Web.config.</li> <li>Run the project. Confirm that the page is displayed with the following message:

You are:

This page runs as: \WindowsSite

Note Aspnet_wp.exe will use the Windows credentials that you specified to access resources on your behalf.</li> <li>Quit Internet Explorer to stop the project.</li></ol>

Note The identity of the process that impersonates a specific user on a thread must have the Act as part of the operating system privilege.
 * On Windows 2000, by default, the Aspnet_wp.exe process runs under a computer account that is named ASPNET.
 * On Windows Server 2003, by default, the Aspnet_wp.exe process runs under a computer account that is named NetworkService. However, this account does not have the correct privileges to impersonate a specific user. You receive an error message if you try to impersonate a specific user.

To work around this problem, use one of the following methods:
 * Grant the Act as part of the operating system privilege to the ASPNET account (the least privileged account).

Note Although you can use this method to work around the problem, Microsoft does not recommend this method.
 * Change the account that the Aspnet_wp.exe process runs under to the System account in the <processModel> configuration section of the Machine.config file.

For more information about the ASPNET process, visit the following Microsoft Developer Network (MSDN) Web site:

http://msdn2.microsoft.com/en-us/library/aa291339(VS.71).aspx

Back to the top

Troubleshooting
Windows security in an ASP.NET Web site can be further enhanced (and complicated) by using NTFS file permissions. If your Windows account does not have permissions to read an ASP.NET Web page, IIS will prompt you for alternative Windows credentials. Similarly, if an ASP.NET page attempts to access a file that the security principal used by the ASP.NET execution engine does not have access to, you will be prompted for alternative credentials. NTFS permissions are an effective way to control access to subsections of a Web site.

Back to the top

<div class="references_section">