identity Element (ASP.NET Settings Schema) 

  • Article

Configures the identity of the Web application. This element can be declared at any level in the configuration file hierarchy.

<identity impersonate="true|false" 
          userName="domain\username"
          password="password"/>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute Description

impersonate

Required attribute.

Specifies whether client impersonation is used on each request.

This attribute can be one of the following possible values.

Value Description

false

Specifies that client impersonation is not used.

true

Specifies that client impersonation is used.

password

Optional attribute.

Specifies the password to use, if the impersonate attribute is true.

For information about storing encrypted worker process credentials in the registry, see the userName attribute.

userName

Optional attribute.

Specifies the user name to use, if the impersonate attribute is true.

This attribute and the password attribute are stored in clear text in the configuration file. Although Microsoft Internet Information Services (IIS) will not transmit .config files in response to a user agent request, .config files can be read by other means. For example, by an authenticated user with the proper credentials on the domain that contains the server. For security reasons, the identity attribute supports storing encrypted userName and password attributes in the registry. The credentials must be in REG_BINARY format and encrypted by the Microsoft Windows 2000 and Windows XP Data Protection API (DPAPI) encryption functions.

For more information, see "Remarks" and "Example," later in this topic.

Child Elements

None.

Parent Elements

Element Description

configuration

Specifies the root element in every configuration file that is used by the common language runtime and the .NET Framework applications.

system.web

Specifies the root element for the ASP.NET configuration section.

Remarks

To encrypt the user name and password and store the user name and password in the registry, set the userName and password attributes as follows.

userName="registry:HKLM\Software\AspNetProcess,Name"password="registry:HKLM\Software\AspNetProcess,Pwd"

The portion of the string after the keyword registry and before the comma indicates the name of the registry key that ASP.NET opens. The portion after the comma contains a single string value name from which ASP.NET reads the credentials. The comma is required and the credentials must be stored in the HKLM hive. If the configuration format is incorrect, ASP.NET will not launch the worker process and will follow the current account creation failure code path.

The credentials must be in REG_BINARY format, containing the output of a call to the Windows API function CryptProtectData. You can create the encrypted credentials and store them in the registry with Aspnet_setreg.exe, which uses CryptProtectData to accomplish the encryption. To download Aspnet_setreg.exe, along with the Microsoft Visual C++ source code and documentation, go to the ASP.NET Web site and search for aspnet_setreg.

You should configure access to the key that is storing the encrypted credentials so that access is provided only to Administrators and SYSTEM. Because the key will be read by the ASP.NET process that is running as SYSTEM, you should set the following permissions:

  • Administrators:F

  • SYSTEM:F

  • CREATOR OWNER:F

  • ProcessAccount:R

This provides two lines of defense to help protect the data, as follows:

  • The ACL permissions require the identity that is accessing the data to be Administrator.

  • An attacker must run code on the server (the CryptUnprotectData API) to recover the credentials for the account.

Default Configuration

The following default identity element is not explicitly configured in the Machine.config file or in the root Web.config file. However, it is the default configuration that is returned by application.

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

Element Information

Configuration section handler

System.Web.Configuration.IdentitySection

Configuration member

System.Web.Configuration.SystemWebSectionGroup.Identity

Configurable locations

Machine.config

Root-level Web.config

Application-level Web.config

Virtual or physical directory–level Web.config

Requirements

Microsoft Internet Information Services (IIS) 5.0, 5.1, or 6.0

The .NET Framework version 1.0, 1.1, or 2.0

Microsoft Visual Studio 2003 or Visual Studio 2005

See Also

Tasks

How to: Lock ASP.NET Configuration Settings

Reference

system.web Element (ASP.NET Settings Schema)
<configuration> Element
System.Configuration
System.Web.Configuration

Concepts

ASP.NET Configuration Overview
ASP.NET Web Server Controls and Browser Capabilities
Securing ASP.NET Configuration
ASP.NET Configuration Scenarios

Other Resources

ASP.NET Configuration Files
ASP.NET Configuration Settings
General Configuration Settings (ASP.NET)
ASP.NET Configuration API