<identity> Element

Controls the application identity of the Web application. This element can be declared at any level (machine, site, application, subdirectory, or page).

<configuration>
   <system.web>
      <identity>

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

Required Attributes

Attribute Option Description
impersonate     Specifies whether client impersonation is used on each request.
    true Specifies that client impersonation is used.
    false Specifies that client impersonation is not used.

Optional Attributes

Attribute Description
userName Specifies the user name to use if impersonate is set to true.

userName and password are stored in clear text in the configuration file. Although IIS will not transmit .config files in response to a user agent request, configuration files can be read by other means, for instance by an authenticated user with proper credentials on the domain that contains the server. For security reasons, the identity section supports storage of encrypted userName and password attributes in the registry. The credentials must be in REG_BINARY format encrypted by the Windows 2000 and Windows XP Data Protection API (DPAPI) encryption functions. For more information, see the Remarks and Example sections below.

   password Specifies the password to use if impersonate is set to true. See userName for information about storing encrypted worker process credentials in the registry.

Remarks

Storing a User Name and Password in the Registry

To encrypt the user name and password and store them in the registry, set the userName and password 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 will read 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 the current account creation failure code path will be followed.

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 the ASP.NET Set Registry console application (Aspnet_setreg.exe), which uses CryptProtectData to accomplish the encryption. To download Aspnet_setreg.exe, along with the Visual C++ source code and documentation, visit the Web site www.asp.net and search for "aspnet_setreg".

You should configure access to the key 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 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:

  • The ACL permissions require the identity accessing the data to be an Administrator.
  • An attacker must run code on the server (CryptUnprotectData) to recover the credentials for the account.

Example

The following example sets client identity impersonation to true.

<configuration>
   <system.web>
      <identity impersonate="true"/>
   </system.web>
</configuration>

The following example specifies that the encrypted username and password are stored in the registry under the user-defined key AspNetIdentity.

<configuration>
   <system.web>
      <identity> 
         userName="registry:HKLM\Software\AspNetIdentity,Name"
         password="registry:HKLM\Software\AspNetIdentity,Pwd"
      </identity>
   </system.web>
</configuration>

Requirements

Contained Within: <system.web>

Web Platform: IIS 5.0, IIS 5.1, IIS 6.0

Configuration File: Machine.config, Web.config

Configuration Section Handler: System.Web.Configuration.IdentityConfigHandler

See Also

ASP.NET Configuration | ASP.NET Settings Schema