identity Element (ASP.NET Settings Schema)

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

Note

The example syntax in this topic includes a password to demonstrate how the syntax works. In your applications, we recommend that you use a strategy to secure passwords.

<configuration> Element
  system.web Element (ASP.NET Settings Schema)
    identity Element (ASP.NET Settings Schema)

<identity impersonate="true|false" 
          userName="domain\username"
          password="<secure 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. ValueDescription 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	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