* 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.
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.
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.
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. TheFileAuthorizationModule 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. TheFileAuthorizationModule 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
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.
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:
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
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
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
<identity impersonate="true" userName="<domain>\<UserName>"
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.
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
// Temporarily impersonate the original user.
WindowsImpersonationContext wic = wi.Impersonate();
// Access resources while impersonating.
// Prevent exceptions propagating.
// Revert impersonation.
Authorizing Windows Users
When you use Windows authentication to authenticate users, you can use the following
* 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
* For resources 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
* 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
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.
<deny users="DomainName\UserName" />
<allow roles="DomainName\WindowsGroup" />
When you use Windows authentication, user names take the form
domainName\userName. Windows groups are used as roles and they take the
formdomainName\windowsGroupName. Well known local groups such as
Administrators and Users are referenced by using the "BUILTIN" prefix as shown here.
<allow users="DomainName\Bob, DomainName\Mary" />
<allow roles="BUILTIN\Administrators, DomainName\Manager" />
<deny users="*" />
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 usingPrincipalPermission 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 formatdomainName\groupName for the group name.
// Perform restricted operation
// 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.
// Perform restricted operation
// Return unauthorized access error.
To use the role manager API, you must enable role manager. With Windows
authentication, you can use the built-inAspNetWindowsTokenRoleProvider, which uses
Windows groups as roles. To enable role manager and select this provider, add the
following configuration to your Web.config file.
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
* For fine grained authorization, call PrincipalPermission.Demand within code, as
// Imperative checks
PrincipalPermission permCheckUser = new PrincipalPermission(@"Domain\Bob",
* Alternatively, you can decorate your classes or methods with the
PrincipalPermissionAttribute, as shown here.
The advantage of this approach is that the security requirements of your methods are
visible to tools such as Permview.exe.
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 theEnable Integrated Windows Authentication check box
in the Security section of the Advanced tab of the Internet Options menu, and then restart
* 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
setspn -A HTTP/webservername domain\customAccountName
setspn -A HTTP/webservername.fullyqualifieddomainname
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.