The thread that physically handles the request impersonates an identity according to the current IIS authentication setting, whether it is Basic, Windows, or Anonymous. If the site is configured for anonymous access, the identity impersonated by the thread is the one you set through the dialog box shown in Figure 19-1. By default, it is named IUSR_xxx, where xxx stands for the machine name.

Figure 19-1. Enabling anonymous access.

Basic authentication is an HTTP standard supported by virtually any browser (and disabled by default in IIS 7). With this type of authentication, a request bounces back with a particular HTTP status code (HTTP 401) that the browser understands as a demand to display a standard dialog box to request the user’s credentials. The information gathered is sent to IIS, which attempts to match it with any of the Web server’s accounts. Because credentials are sent out as Base64-encoded text, essentially in clear text, Basic authentication is recommended only for use over HTTPS secure channels.

Note that the default installation of IIS 7 doesn’t include Digest authentication. Digest authentication differs from Basic authentication mostly because it hashes credentials before sending. Digest authentication is an HTTP 1.1 feature and, as such, is not supported by some old browsers. Both Basic and Digest authentication work well through firewalls and proxy servers. To use Digest authentication on IIS 7, you must install the appropriate Digest role service and disable anonymous authentication.

Integrated Windows authentication sets up a conversation between the browser and the Web server. The browser passes the credentials of the currently logged-on user, who is not required to type anything. The user needs to have a valid account on the Web server or in a trusted domain to be successfully authenticated. The authentication can take place through the NTLM challenge/response method or by using Kerberos. The technique has limited browser support and is impractical in the presence of firewalls. It is designed for intranet use.

In IIS 7, you can also leverage ASP.NET Forms authentication at the IIS level as well as ASP.NET impersonation. ASP.NET Forms authentication essentially redirects to an application-specific login page. If you enable impersonation, instead, your ASP.NET application will run under the security context of the user authenticated by IIS 7 or under the specific account you indicate by editing the impersonation settings in the IIS manager.

After authentication, the thread dispatches the request to the appropriate module. For an ASP.NET application, the request is queued to the application pool and picked up by the copy of the w3wp.exe IIS worker process that serves that application pool. What is the identity of the worker process?

As you saw in Chapter 2, the worker process typically runs under the identity of the NETWORK SERVICE account or under a virtual account associated with the application pool. You can change it through the Advanced Settings dialog box of the application pool as shown in Figure 19-2.

Figure 19-2. Changing the identity for the worker process.

Inside the worker process, a pooled thread picks up the request to serve it. What’s the identity of this thread? If impersonation is disabled in the ASP.NET application, this thread will inherit the identity of the worker process. This is what happens by default. If impersonation is enabled, the worker thread will inherit the security token passed by IIS.

When impersonation is active, the worker process account doesn’t change. The worker process still compiles pages and reads configuration files using the original account. Impersonation is used only with the code executed within the page, not for all the preliminary steps that happen before the request is handed to the page handler. For example, this means that any access to local files or databases occur using the impersonated account, not the worker process’s account.

The third security context indicates the identity of the user making the request. The point here is authenticating the user and authorizing access to the page and its embedded resources. Obviously, if the requested page is freely available, no further step is performed; the page output is generated and served to the user.

To protect pages against unauthorized access, an ASP.NET application needs to define an authentication policy—typically Forms authentication. Authentication modules hook up requests for protected pages and manage to obtain the user’s credentials. The user is directed to the page only if the credentials are deemed valid and authorize access to the requested resource.

Using the dialog box shown in Figure 19-2 is the only way to change the real identity of the ASP.NET process. If you change the process identity, all threads in the process will use this as the base identity and no extra work is needed on thread switches. More importantly, you should make sure the new account has at least full permissions on the Temporary ASP.NET Files folder. (Review carefully the list of permissions granted to the standard ASP.NET accounts, which you can find in the Privileges of the ASP.NET Default Account section.)

Alternatively, you can require the worker process to impersonate a fixed identity through the <identity> section of the web.config file. Note that when fixed impersonation is used, every worker thread processing a request needs to impersonate the specified account. Impersonation will then be performed for each thread switch because a thread switch event takes the thread identity back to the process identity.

To impersonate a fixed identity, you first define the user account and then add a setting to the web.config file. The following snippet shows an example:

<identity impersonate="true"
    userName="MyAspNetAccnt" password="ILoveA$pnet*SinceVer1.0" />

As mentioned earlier, impersonation doesn’t really change the physical identity of the process running ASP.NET. More simply, all threads serving in the context of the ASP.NET worker process always impersonate a given user for the duration of the application.

Impersonating a fixed identity is different from classic, per-request impersonation such as impersonating the identity of the Windows user making the request. Per-request impersonation refers to the situation in which you enable impersonation without specifying a fixed identity. In this case, the security token with identity information is created by IIS and inherited by the worker process. When a fixed identity is involved, the security token must be generated by the ASP.NET worker process. When running under a poorly privileged account, though, the ASP.NET worker process sometimes lacks the permission to do that.

A third possibility to change the identity of the ASP.NET worker process is by impersonating through the anonymous account. The idea is that the ASP.NET application grants access to anonymous users, and the anonymous account is configured to be the desired account for the application.

In this case, the application uses per-request impersonation and the ASP.NET code executes as the impersonated account. The process account remains set to NETWORK SERVICE or the virtual account, which means you don’t have to worry about replicating into the new account the minimum set of permissions on folders that allow ASP.NET to work.

Of all the possible user rights assignments, ASPNET and NETWORK SERVICE are granted only the following five:

In addition, the accounts are given some NTFS permissions to oper ate on certain folders and create temporary files and assemblies. The folders involved are these:

An ASP.NET application running under an account that lacks some of these permissions might fail. Granting at least all these permissions is highly recommended for all accounts used for fixed-account impersonation.

By default, ASP.NET applications run unrestricted and are allowed to do whatever their account is allowed to do. The actual security restrictions that sometimes apply to ASP.NET applications (for example, the inability to write files) are not a sign of partial trust, but more simply the effect of the underprivileged account under which ASP.NET applications normally run.

By tweaking the <trust> section in the root web.config file, you can configure code access security permissions for a Web application and decide whether it has to run fully or partially trusted:

<trust level="Medium" originUrl="" />

Table 19-2 describes the levels of trust available.

Admittedly, restricting the set of things an application can do might be painful at first. However, in the long run (read, if you don’t just give up and deliver the application), it produces better and safer code.

Let’s review in more detail the permission granted to ASP.NET applications when the various trust levels are applied. Key ASP.NET permissions for each trust level are outlined in Table 19-3.

More detailed information about the permissions actually granted to the default trust levels are available in the security configuration files for each level. The name of the file for each level is stored in the <trustLevel> section.

In the end, full-trust applications run unrestricted. High-trust applications have read/write permission for all the files in their application space. However, the physical access to files is still ruled by the NTFS access control list on the resource. High-trust applications have unrestricted access to Microsoft SQL Server but not, for example, to OLE DB classes. (The OleDbPermission and other managed provider permissions are denied to all but fully trusted applications.) Reflection calls are denied, with the exception of those directed at classes in the System.Reflection.Emit namespace.

Medium applications have unrestricted access to SQL Server, but only as long as they don’t use blank passwords for accounts. The WebPermission is granted to both medium-trust and low-trust applications, but it requires that the URL be configured in the <trust> section through the originUrl attribute. Low-trust applications have read-only permission for files in their application directories. Isolated storage is still permitted but limited to a 1-MB quota.

A rule of thumb is that Medium trust should be fine for most ASP.NET applications and applying it shouldn’t cause significant headaches, provided that you don’t need to access legacy Component Object Model (COM) objects or databases exposed via OLE DB providers. However, there are a few common situations in which adapting an application to Medium trust requires some configuration work. A popular example is setting NHibernate to work in a Medium-trust environment. (See http://blog.yeticode.co.uk/2010/03/running-nhibernate-in-medium-trust for details.)

What if one of the tasks to perform requires privileges that the trust level doesn’t grant? There are two basic approaches. The simplest approach is to customize the policy file for the trust level and add any permissions you need. The solution is easy to implement and doesn’t require code changes. It does require administrator rights to edit the security policy files. From a pure security perspective, it is not a great solution because you’re just adding to the whole application the permissions you need for a particular method of a particular page or assembly.

The second approach requires a bit of refactoring but leads to better and safer code. The idea is to sandbox the server-side code and make it delegate to external components (for example, serviced components or command-line programs) the execution of any tasks that exceed the application’s permission set. Obviously, the external component will be configured to have all required permissions.

When using Windows authentication, ASP.NET works in conjunction with IIS. The real authentication is performed by IIS, which uses one of its authentication methods: Basic or Integrated Windows. When IIS has authenticated the user, it passes the security token on to ASP.NET. When in Windows authentication mode, ASP.NET does not perform any further authentication steps and limits its use of the IIS token to authorizing access to the resources.

Typically, you use the Windows authentication method in intranet scenarios when the users of your application have Windows accounts that can be authenticated only by the Web server. Let’s assume that you configured the Web server to work with the Integrated Windows authentication mode and that you disabled anonymous access. The ASP.NET application works in Windows authentication mode. What happens when a user connects to the application? First, IIS authenticates the user (popping up a dialog box if the account of the local user doesn’t match any accounts on the Web server or in the trusted domain) and then hands the security token over to ASP.NET.

In most cases, Windows authentication is used in conjunction with file authorization—via the FileAuthorizationModule HTTP module. User-specific pages in the Web application can be protected from unauthorized access by using access control lists (ACLs) on the file. When ASP.NET is about to access a resource, the FileAuthorizationModule HTTP module is called into action. File authorization performs an ACL check on ASP.NET files using the caller’s identity. For example, it will be sure that the user Joe will never be able to access an .aspx page whose ACL doesn’t include an entry for him.

Note, though, that file authorization does not require impersonation at the ASP.NET level and, more importantly, it works regardless of whether the impersonation flag is turned on. Once you’ve set an appropriately configured ACL on an ASP.NET resource, you’re pretty much done. Nobody will be able to access the resource without permission.

The .NET Framework (starting with 3.0) contains a new technology that can be used with ASP.NET Web sites to authenticate users: Windows CardSpace. Any page that includes the Identity Selector object, uses the identity cards of the connected user to send credentials to the server. Each user can manage her own cards by using the Windows CardSpace applet in Control Panel of any client machines equipped with the .NET Framework 3.0 or later.

The Identity Selector is an <object> tag of type application/x-informationcard. By requesting the value property of this object, you force an enabled browser to bring up the CardSpace applet. The user then picks up the right card to send. The server-side login page will then access the content of the card and make any necessary checks to authorize the request. If it becomes widely accepted, Windows CardSpace could be the perfect tool for authentication over the Internet. For more information, you can start reading the following MSDN article: http://msdn.microsoft.com/en-us/magazine/cc163434.aspx.

The layout of a login page is nearly the same—a couple of text boxes for the user name and password, a button to confirm, and perhaps a label to display error messages. However, you can make it as complex as needed and add as many graphics as appropriate. The user enters the credentials, typically in a case-sensitive way, and then clicks the button to log on. When the login page posts back, the following code runs:

void LogonUser(object sender, EventArgs e)
{
    string user = userName.Text;
    string pswd = passWord.Text;

    // Custom authentication
    bool bAuthenticated = AuthenticateUser(user, pswd);
    if (bAuthenticated)
        FormsAuthentication.RedirectFromLoginPage(user, false);
    else
        errorMsg.Text = "Sorry, yours seems not to be a valid account.";
}

The event handler retrieves the strings typed in the user name and password fields and calls into a local function named AuthenticateUser. The function verifies the supplied credentials and returns a Boolean value. If the user has been successfully authenticated, the code invokes the RedirectFromLoginPage static method on the FormsAuthentication class to inform the browser that it’s time to issue a new request to the original page.

The RedirectFromLoginPage method redirects an authenticated user back to the originally requested URL. It has two overloads with the following prototypes:

public static void RedirectFromLoginPage(string, bool);
public static void RedirectFromLoginPage(string, bool, string);

The first argument is the name of the user to store in the authentication ticket. The second argument is a Boolean value that denotes the duration of the cookie, if any, being created for the authentication ticket. If this argument is true, the cookie is given a duration that equals the number of minutes set by the timeout attribute (which is 30 minutes by default). In this way, you get a cookie that persists across browser sessions. Otherwise, your authentication cookie will last for the current session only. Finally, the third argument optionally specifies the cookie path.

The authenticating algorithm—that is, the code inside the AuthenticateUser method seen earlier—is entirely up to you. For example, you might want to check the credentials against a database or any other user-defined storage device. The following listing shows a (rather naïve) function that compares the user name and password against the firstname and lastname columns of the Northwind Employees table in SQL Server:

private bool AuthenticateUser(string username, string pswd)
{
   // Performs authentication here
   string connString = "...";
   string cmdText = "SELECT COUNT(*) FROM employees " +
                    "WHERE firstname=@user AND lastname=@pswd";

   int found = 0;
   using(SqlConnection conn = new SqlConnection(connString))
   {
      SqlCommand cmd = new SqlCommand(cmdText, conn);
      cmd.Parameters.Add("@user",
           SqlDbType.NVarChar, 10).Value = username;
      cmd.Parameters.Add("@pswd",
           SqlDbType.NVarChar, 20).Value = pswd;
      conn.Open();
      found = (int)cmd.ExecuteScalar();
      conn.Close();
   }
   return (found > 0);
}

The query is configured to return an integer that represents the number of rows in the table that match the specified user name and password. Notice the use of typed and sized parameters in the SQL command as a line of defense against possible injection of malicious code. Notice also that the SQL code just shown does not support strong passwords because the SQL = operator in the WHERE clause doesn’t perform case-sensitive comparisons. To make provisions for that, you should rewrite the command as follows:

SELECT COUNT(*) FROM employees WHERE
    CAST(RTRIM(firstname) AS VarBinary)=CAST(RTRIM(@user) AS VarBinary)
    AND
    CAST(RTRIM(lastname) AS VarBinary)=CAST(RTRIM(@pswd) AS VarBinary)

The CAST operator converts the value into its binary representation, while the RTRIM operator removes trailing blanks. To capture the name of the currently logged-in user, a page should just use the following code block:

 Welcome, <%= User.Identity.Name %>.

While an explicit sign-in is always required by Web sites that need authentication, an explicit sign-out is less common but legitimate nonetheless. The Forms authentication module provides an explicit method to sign out. The SignOut method on the FormsAuthentication class takes no argument and resets the authentication ticket. In particular, when cookies are used, the SignOut method removes the current ticket from the Cookies collection of the current HttpResponse object and replaces it with an empty and expired cookie.

After you call SignOut, you might want to redirect the application to another page. The FormsAuthentication class has a method—RedirectToLoginPage—that provides the described functionality and transfers the user to a given page using Response.Redirect.

Let’s now take a look at the methods of the FormsAuthentication class and the configurable parameters you find in the web.config file. After this, I’ll move on to introduce the membership API and role management.

Table 19-4 lists the properties of the FormsAuthentication class. As you can see, many of them deal with cookie naming and usage and expose the content of configuration attributes in the <forms> section. We’ll look at the underpinnings of the <forms> XML configuration element in the next section. All the properties of the FormsAuthentication class shown in the table are static.

Most of the properties are initialized with the values read from the <forms> configuration section of the web.config file when the application starts up.

Table 19-5 details the methods supported by the FormsAuthentication class. All the methods listed in the table are static.

The Initialize method is called only once in the application’s lifetime and initializes the properties in Table 19-4 by reading the configuration file. The method also gets the cookie values and encryption keys to be used for the application.

Forms authentication is driven by the contents of the <forms> section child of the <authentication> section. The overall syntax is shown here:

<forms name="cookie"
    loginUrl="url"
    protection="All|None|Encryption|Validation"
    timeout="30"
    requireSSL="true|false"
    slidingExpiration="true|false"
    path="/"
    enableCrossAppsRedirects="true|false"
    cookieless="UseCookies|UseUri|AutoDetect|UseDeviceProfile"
    defaultUrl="url"
    domain="string">
</forms>

The various attributes are described in Table 19-6.

The defaultUrl attribute lets you set the default name of the page to return after a request has been successfully authenticated. This URL is configurable. But isn’t the URL of the return page embedded in the query string, in the ReturnUrl parameter? So when is defaultUrl useful?

If a user is redirected to the login page by the authentication module, the ReturnUrl variable is always correctly set and the value of defaultUrl is blissfully ignored. However, if your page contains a link to the login page, or if it needs to transfer programmatically to the login page (for example, after the current user has logged off), you are responsible for setting the ReturnUrl variable. If it is not set, the URL stored in the defaultUrl attribute will be used.

The default way of putting Forms authentication at work is through cookies. The content of the authentication ticket is stored in a cookie named after the value of the name attribute in the <forms> section. The cookie contains any information that helps to identify the user making the request.

By default, a cookie used for authentication lasts 30 minutes and is protected using both data validation and encryption. Data validation ensures that the contents of the cookie have not been tampered with along the way. Encryption uses the Rijndael encryption algorithm (also known as AES) to scramble the content. You can force it to use DES or 3DES if you like, however.

When validation is turned on, the cookie is created by concatenating a validation key with the cookie data, computing a Machine Authentication Code (MAC) and appending the MAC to the outgoing cookie. The validation key, as well as the hash algorithm to use for the MAC, are read out of the <machineKey> section in the web.config file. The same section also specifies the cryptographic key for when encryption is enabled.

Cookies are not the only way of putting Forms authentication to work. ASP.NET can offer an alternative API that exposes a nearly identical programming interface but makes no use of cookies.

When cookieless authentication is on, the ticket it is incorporated into the URL in much the same way as for cookieless sessions. The URL of the page served to an authenticated user follows the pattern shown here:

http://YourApp/(F(XYZ...1234))/samples/default.aspx

The ticket, properly encoded to a URL-compliant alphabet, is inserted in the URL right after the server name.

Cookieless authentication requires an ISAPI filter to intercept the request, extract the ticket, and rewrite the correct path to the application. The filter also exposes the authentication ticket as another request header. The same aspnet_filter.dll component that we saw in Chapter 17, for cookieless sessions is used to parse the URL when cookieless authentication is used. To avoid confusion, each extra piece of information stuffed in the URL is wrapped by unique delimiters: S(…) for a session ID and F(…) for an authentication ticket. The filter extracts the information, removes URL adornments, and places the ticket information in a header named AspAuthenticationTicket.

To enable cookieless authentication, you set the cookieless attribute in the <forms> section of the configuration file to a particular value. The attribute specifies if and how cookies are used to store the authentication ticket. It can take any of the values listed in Table 19-7.

There’s a subtle difference between UseDeviceProfile and AutoDetect. Let’s make it clear with an example. Imagine a user making a request through Internet Explorer. The browser does have support for cookies as reported in the browser capabilities database installed with ASP.NET. However, a particular user might have disabled cookies support for her own browser. AutoDetect can correctly handle the latter scenario, and it will opt for cookieless authentication. UseDeviceProfile doesn’t probe for cookies being enabled, and it stops at what’s reported by the capabilities database. It will incorrectly opt for cookied authentication, causing an exception to be thrown.

The default value for the cookieless attribute is UseDeviceProfile. You should consider changing it to AutoDetect.

HTTP cookies support a path attribute to let you define the application path the cookie is valid within. Pages outside of that path cannot read or use the cookie. If the path is not set explicitly, it defaults to the URL of the page creating the cookie. For authentication cookies, the path defaults to the root of the application so that it is valid for all pages in the application. So far, so good.

In ASP.NET, two applications in the same Internet domain can share their own authentication cookies, implementing a sort of single sign-on model. Typically, both applications provide their own login pages, and users can log on using any of them and then freely navigate between the pages of both. For this to happen, you only have to ensure that some settings in the root web.config files are the same for both applications. In particular, the settings for the name, protection, and path attributes in the <forms> section must be identical. Moreover, a <machineKey> section should be added to both web.config files with explicit validation and decryption keys:

<machineKey
    validationKey="C50B3C89CB21F4F1422FF158A5B42D0...E"
    decryptionKey="8A9BE8FD67AF6979E7D20198C...D"
    validation="SHA1" />

Read Knowledge Base article 312906 (located at http://support.microsoft.com/default.aspx?scid=kb;en-us;312906) for suggestions on how to create machine keys. Note that, by default, validation and decryption keys are set to AutoGenerate. The keyword indicates that a random key has been generated at setup time and stored in the Local Security Authority (LSA). LSA is a Windows service that manages all the security on the local system. If you leave the AutoGenerate value, each machine will use distinct keys and no shared cookie can be read.

Suppose now you run two ASP.NET Web sites, named www.contoso.com and blogs.contoso.com. Each of these sites generates authentication cookies not usable by the other. This is because, by default, authentication cookies are associated with the originating domain. All HTTP cookies, though, support a domain attribute, which takes the flexibility of their path attribute to the next level. If set, the domain attribute indicates the domain the cookie is valid for. Cookies can be assigned to an entire Internet domain, a subdomain, or even multiple subdomains.

In ASP.NET, the domain attribute in the <forms> section determines the value of the domain attribute on the authentication cookie being created.

<forms domain="contoso.com" />

Add the preceding script to the web.config file of the Web sites named www.contoso.com and blogs.contoso.com and you’ll have them share the authentication cookies (if the client browser recognizes the domain attribute of the cookie, which most modern browsers do).

The effect of the setting is that the primary domain (www) and any other subdomains will be able to handle each other’s authentication cookies, always with the proviso that their web.config files are synchronized on the machine key values.

Forms authentication also supports having the login page specified in another application in the same Web site:

<forms loginUrl="/anotherApp/login1.aspx" />

The two applications must have identical machine keys configured for this to work. If the application is using cookied authentication tickets, no additional work is necessary. The authentication ticket will be stored in a cookie and sent back to the original application.

If cookieless authentication is used, some extra work is required to enable the external application to authenticate for us. You need to set the enableCrossAppRedirects attribute in <forms> in the web.config file of both applications.

<forms ... enableCrossAppRedirects="true" />

Upon successful authentication, the ticket is generated and attached to a query string parameter to be marshaled back to the original application.

If the enableCrossAppRedirects attribute is missing and cookieless authentication is used, the external application will throw an exception.

A hacker who manages to steal a valid authentication ticket is in a position to perpetrate a replay attack for the lifetime of the ticket. To mitigate the risk of replay attacks, you can perform authentication over a secured socket. Using secured sockets also removes the threat represented by applications such as Firesheep (http://en.wikipedia.org/wiki/Firesheep) that can sniff unencrypted cookies.

This means that first you must deploy your login page on an HTTPS-capable server, and second you need to set the requireSSL attribute to true in the <forms> section. This setting causes the ASP.NET application to enable the Secure attribute on the HTTP cookie being created. When the Secure attribute is set, compliant browsers send back only the cookie containing the ticket over a resource that is protected with SSL. In this way, you can still use a broad cookie scope, such as the whole application (‘/’) while providing a reasonable security level for the ticket in transit.

If you don’t want to use SSL to protect the ticket, the best you can do to alleviate the risk of replay attacks is set the shortest lifetime for the authentication ticket to a value that is reasonable for the application. Even if the ticket is intercepted, there won’t be much time remaining for the attacker to do his or her (bad) things.

As a final note regarding SSL, consider the following. If requireSSL is set and the user attempts to log in on a request not made over SSL, an exception is thrown. If requireSSL is set and an authentication cookie (a possibly stolen one at that) is provided over a non-SSL request, no exception is thrown; however, the cookie is wiped out and a regular login page is displayed through the browser.

Note that if the same happens with cookieless authentication, no protocol check is made and the request is served to the user…or the attacker.

Functionally speaking, Forms authentication is the most appropriate authentication method for Web and ASP.NET applications. However, a few general security issues shouldn’t pass without comment.

To start with, Forms authentication credentials are sent out as clear text from the client. SSL can be used to protect the communication, but in the end Forms authentication is as weak as IIS Basic authentication.

As mentioned, a stolen authentication cookie can be used to plan replay attacks as long as it is valid. This risk can be partially mitigated by reducing the lifetime of the ticket. Requiring an SSL connection for the cookie transmission resolves the issue if cookied authentication is used, but not if a cookieless solution is employed.

Finally, Forms authentication is based on application code, which is good news and bad news at the same time. It is good because you can keep everything under control. It is bad because any bug you leave in your code opens a security hole. A way to mitigate the risk of vulnerabilities stemming from incorrect code is to resort to the membership API.

The User property on the HttpContext object is of type IPrincipal—the public contract that all principal objects must fulfill. Most of the time, the real type behind the User property is GenericPrincipal. If role management is enabled at the application level, instead, the type is RolePrincipal. (We’ll cover role management in just a few moments.)

Common principal classes are certainly useful but may prove to be quite generic in most applications. In real-world scenarios, you sometimes need to add some custom information to the security context so that once you have authenticated a user you know much more about him than just the user name and roles. Let’s see how to tweak the authentication process to create a custom cookie and then how to retrieve that information and pack it into a custom principal object.

In the event handler responsible for validating credentials, you add the following code:

var customInfo = "some|value";
var ticket = new FormsAuthenticationTicket(
    4,                             // Version number
    userName,                      // Username
    DateTime.Now,                  // Issue date
    DateTime.Now.AddMinutes(30),   // Expiration date
    createPersistentCookie,        // Is it persistent?
    customInfo                     // User data
);
var encTicket = FormsAuthentication.Encrypt(ticket);

// Store the ticket into a cookie
var cookie = FormsAuthentication.GetAuthCookie(
                    FormsAuthentication.FormsCookieName,
                    createPersistentCookie);
cookie.Value = encTicket;

// Append the cookie to the response and redirect
HttpContext.Current.Response.Cookies.Add(cookie);
HttpContext.Response.Redirect(FormsAuthentication.DefaultUrl);

You create your own ticket and stuff some custom data in it. You must get your own instance of the FormsAuthenticationTicket class in order to do so. Next, you encrypt the ticket and write it to a cookie with the default name of authentication cookies. The preceding code replaces the following call, which is what would happen by default:

FormsAuthentication.SetAuthCookie(userName, createPersistentCookie);

The next step is retrieving the custom information stored in the authentication cookie. You can do that in the authentication step of global.asax, as shown here:

protected void Application_PostAuthenticateRequest()
{
    // Collect current security information
    var principal = HttpContext.Current.User as GenericPrincipal;
    if (principal == null)
        return;
    var identity = principal.Identity as FormsIdentity;
    if (identity == null)
        return;

    // Extract user data in the authentication ticket
    var customInfo = identity.Ticket.UserData;
    var tokens = customInfo.Split('|'),

    // Build a richer principal object
    var myPrincipal = new MyPrincipal(identity, roles)
                      {
                          CurrentTime = tokens[0],
                          Number = tokens[1]
                      };

    // Store the new principal in the HttpContext
    HttpContext.Current.User = myPrincipal;
}

Having done all of this, you can now cast the HttpContext.User object to your principal type (MyPrincipal in the example) and use the additional properties in any page. MyPrincipal is a plain class that inherits from GenericPrincipal:

public class MyPrincipal : GenericPrincipal
{
    public MyPrincipal(IIdentity identity, String[] roles) :
        base(identity, roles)
    { }

    // Extra properties
    public String CurrentTime { get; set; }
    public String Number { get; set; }
}

Table 19-8 lists the properties exposed by the Membership class.

The Provider property returns a reference to the membership provider currently in use. As you’ll see in a moment, the provider is selected in the configuration file. ASP.NET comes with a couple of predefined providers that target MDF files in SQL Server Express and Active Directory. However, many more membership providers are in the works from Microsoft and third-party vendors, or you can even derive your own. You can obtain the list of installed providers for a given application through the Providers collection.

All properties are static and read-only. All of them share a pretty simple implementation. Each property just accesses the corresponding member on the current provider, as shown here:

public static int PasswordAttemptWindow
{
   get
   {
      Membership.Initialize();
      return Membership.Provider.PasswordAttemptWindow;
   }
}

As the name suggests, the Initialize method ensures that the internal structure of the Membership class is properly initialized and that a reference to the provider exists.

The class supports fairly advanced functionality, such as estimating the number of users currently using the application. It uses the value assigned to the UserIsOnlineTimeWindow property to determine this number. A user is considered on line if he has done something with the application during the previous time window. The default value for the UserIsOnlineTimeWindow property is 15 minutes. After 15 minutes of inactivity, a user is considered off line.

Table 19-9 details the methods supported by the Membership class. This list clarifies the tasks the class accomplishes.

To build an authentication layer based on the membership API, you start by choosing the default provider and establish the data store. In the simplest case, you can stay with the default predefined provider, which saves user information in a local MDF file in SQL Server Express.

The Web Site Administration Tool (WSAT) in Microsoft Visual Studio provides a user interface for creating and administering the registered users of your application. Figure 19-4 provides a glimpse of the user interface.

Figure 19-4. Configure the membership data model.

To add a new user or to edit properties of an existing one, you use the links shown in the figure. When you edit the properties of a new user, you use the page in Figure 19-5.

Figure 19-5. Choosing a user to edit or delete through the WSAT tool.

At this point, we’re ready to write some code that uses the membership API. Let’s start with the most common operation—authenticating credentials. Using the features of the membership subsystem, you can rewrite the code in the login page you saw previously to authenticate a user as follows:

void LogonUser(Object sender, EventArgs e)
{
    var user = userName.Text;
    var pswd = passWord.Text;

   if (Membership.ValidateUser(user, pswd))
        FormsAuthentication.RedirectFromLoginPage(user, false);
    else
        errorMsg.Text = "Sorry, yours seems not to be a valid account.";
}

This code doesn’t look much different from what you would write without providers, but there’s one big difference: the use of the built-in ValidateUser function. Here is the pseudocode of this method as it is implemented in the system.web assembly:

public static Boolean ValidateUser(String username, String password)
{
   return Membership.Provider.ValidateUser(username, password);
}

As you can see, all the core functionality that performs the authentication lives in the provider. What’s nice is that the name of the provider is written in the web.config file and can be changed without touching the source code of the application. The overall schema is illustrated in Figure 19-6.

Figure 19-6. Membership using the provider model.

The Membership class provides easy-to-use methods for creating and managing user data. For example, to create a new user programmatically, all you do is place a call to the CreateUser method:

Membership.CreateUser(userName, pswd);

To delete a user, you call the DeleteUser method:

Membership.DeleteUser(userName);

You can just as easily get information about a particular user by using the GetUser method. The method takes the user name and returns a MembershipUser object:

var user = Membership.GetUser("DinoE");

Once you’ve got a MembershipUser object, you know all you need to know about a particular user, and you can, for example, programmatically change the password (or other user-specific information). An application commonly needs to execute several operations on passwords, including changing the password, sending a user her password, or resetting the password, possibly with a question/answer challenge protocol. Here is the code that changes the password for a user:

var user = Membership.GetUser("DinoE");
user.ChangePassword(user.GetPassword(), newPswd);

To use the ChangePassword method, you must pass in the old password. In some cases, you might want to allow users to simply reset their password instead of changing it. You do this by using the ResetPassword method:

MembershipUser user = Membership.GetUser("DinoE");
string newPswd = user.ResetPassword();

In this case, the page that calls ResetPassword is also in charge of sending the new password to the user—for example, via e-mail. Both the GetPassword and ResetPassword methods have a second overload that takes a string parameter. If specified, this string represents the answer to the user’s “forgot password” question. The underlying membership provider matches the supplied answer against the stored answers; if a user is identified, the password is reset or returned as appropriate.

All the providers used in ASP.NET—not just membership providers—implement a common set of members: the members defined by the ProviderBase class. The class comes with one method, Initialize, and one property, Name. The Name property returns the official name of the provider class. The Initialize method takes the name of the provider and a name/value collection object packed with the content of the provider’s configuration section. The method is supposed to initialize its internal state with the values just read out of the web.config file.

Many of the methods and properties used with the Membership class are actually implemented by calling into a corresponding method or property in the underlying provider. It comes as no surprise, then, that many of the methods listed in Table 19-10, which are defined by the MembershipProvider base class, support the functions you saw in Table 19-9 that are implemented by the dependent Membership class. However, note that Table 19-9 and Table 19-10 are very similar but not identical.

All these methods are marked as abstract virtual in the class (must-inherit, overridable in Visual Basic .NET jargon). The MembershipProvider class also features a few properties. They are listed in Table 19-11.

The provider can also store additional information with each user. For example, you can derive a custom class from MembershipUser, add any extra members, and return an instance of that class via the standard GetUser method of the membership API.

To use the new class, you cast the object returned by GetUser to the proper type, as shown here:

var user = Membership.GetUser(name) as MyCompanyUser;

In addition to the members listed in Table 19-10 and Table 19-11, a custom membership provider can add new methods and properties. These are defined outside the official schema of the provider base class and are therefore available only to applications aware of this custom provider.

var provider = Membership.Provider as MyCompanyProvider;

var prov = Membership.Providers["ProviderName"];

Unless you’re building an ASP.NET application entirely from scratch with total freedom to decide where and how to store settings and data, you have some legacy code or schema to deal with. A savvy strategy, then, is creating a custom membership provider to provide access to legacy data via a canonical programming interface. I would even say that almost any ASP.NET application needs its own membership provider. Here’s some sample code:

public class MyMembershipProvider : MembershipProvider
{
   public MyMembershipProvider()
   {
   }
   public override bool ChangePassword(string username,
         string oldPassword, string newPassword)
   {
       // If you don't intend to support a given method
       // just throw an exception
       throw new NotSupportedException();
   }

   ...

   public override bool ValidateUser(string username, string password)
   {
       return AuthenticateUser(username, password);
   }

   private bool AuthenticateUser(string username, string pswd)
   {
       // Place here any code that would use the existing API/schema
       // and authenticate against the provided credentials
    }
}

You define a new class derived from MembershipProvider. In this class definition, you have to override all the members in Table 19-10 and Table 19-11. If you don’t intend to support a given method or property, for that method just throw a NotSupportedException exception. For the methods you do plan to support—which for the previous example included only ValidateUser—you write the supporting code. At this point, nothing prevents you from reusing code from your old application. There are two key benefits with this approach: you reuse most of your code (perhaps with a little bit of refactoring), and your application now fully embraces the membership model of ASP.NET.

Generally speaking, when writing providers, there are three key issues to look at: the lifetime of the provider, thread-safety, and atomicity. The provider is instantiated as soon as it proves necessary, but only once per ASP.NET application. This fact gives the provider the status of a stateful component, but it does so at the price of protecting that state from cross-thread access. A provider is not thread-safe, and it will be your responsibility to guarantee that any critical data is locked before use. Finally, some functions in a provider can be made of multiple steps. Developers are responsible for ensuring the atomicity of the operations either through database transactions (whenever possible) or through locks.

You register a new provider through the <membership> section of the web.config file. The section contains a child <providers> element under which additional providers are configured:

<membership>
   <providers>
      <add name="MyMembershipProvider"
           type="Samples.MyMembershipProvider" />
   </providers>
</membership>

You can change the default provider through the defaultProvider attribute of the <membership> section.

With the new provider in place, the code to verify credentials reduces to the following code, which is the same as you saw earlier in the chapter:

void LogonUser(object sender, EventArgs e)
{
    string user = userName.Text;
    string pswd = passWord.Text;
    if (Membership.ValidateUser(user, pswd))
        FormsAuthentication.RedirectFromLoginPage(user, false);
    else
        errorMsg.Text = "Sorry, yours seems not to be a valid account.";
}

There’s more than just this with the membership API. Now a login page has a relatively standard structure and relatively standard code attached. At least in the simplest scenarios, it can be reduced to a composite control with no binding code. This is exactly what security controls do. Before we get to cover this new family of server controls, though, let’s review roles and their provider-based management.

The role management API lets you define roles as well as specify programmatically which users are in which roles. The easiest way to configure role management, define roles, add users to roles, and create access rules is to use WSAT. (See Figure 19-4.) You enable role management by adding the following script to your application’s web.config file:

<roleManager enabled="true" />

You can use roles to establish access rules for pages and folders. The following <authorization> block states that only Admin members can access all the pages controlled by the web.config file:

<configuration>
<system.web>
    <authorization>
       <allow roles="Admin" />
       <deny users="*" />
    </authorization>
</system.web>
</configuration>

The order in which you place <allow> and <deny>tags is important. Permissions and denies are processed in the order in which they appear in the configuration file.

WSAT provides a visual interface for creating associations between users and roles. If necessary, you can instead perform this task programmatically by calling various role manager methods. The following code snippet demonstrates how to create the Admin and Guest roles and populate them with user names:

Roles.CreateRole("Admin");
Roles.AddUsersToRole("DinoE", "Admin");
Roles.CreateRole("Guest");
var guests = new String[2];
guests[0] = "JoeUsers";
guests[1] = "Godzilla";
Roles.AddUsersToRole(guests, "Guest")

At run time, information about the logged-in user is available through the HTTP context User object. The following code demonstrates how to determine whether the current user is in a certain role and subsequently enable specific functions:

if (User.IsInRole("Admin"))
{
      // Enable functions specific to the role
      ...
}

When role management is enabled, ASP.NET looks up the roles for the current user and binds that information to the User object.

When role management is enabled, ASP.NET creates an instance of the Roles class and adds it to the current request context—the HttpContext object. The Roles class features the methods listed in Table 19-12.

Table 19-13 lists the properties available in the Roles class. All the properties are static and read-only. They owe their value to the settings in the <roleManager> configuration section.

Some methods in the Roles class need to query continuously for the roles associated with a given user, so when possible, the roles for a given user are stored in an encrypted cookie. On each request, ASP.NET checks to see whether the cookie is present; if so, it decrypts the role ticket and attaches any role information to the User object. By default, the cookie is a session cookie and expires as soon as the user closes the browser.

Note that the cookie is valid only if the request is for the current user. When you request role information for other users, the information is read from the data store using the configured role provider.

For its I/O activity, the role manager uses the provider model and a provider component. The role provider is a class that inherits the RoleProvider class. The schema of a role provider is not much different from that of a membership provider. Table 19-14 details the members of the RoleProvider class.

You can see the similarity between some of these methods and the programming interface of the Roles class. As you saw for membership, this is not just coincidental.

ASP.NET ships with a few built-in role providers—SqlRoleProvider (default), WindowsTokenRoleProvider, and AuthorizationStoreRoleProvider. The SqlStoreProvider class stores role information in the same MDF file in SQL Server Express as the default membership provider. For WindowsTokenRoleProvider, role information is obtained based on the settings defined for the Windows domain (or Active Directory) the user is authenticating against. This provider does not allow for adding or removing roles. The AuthorizationStoreRoleProvider class manages storage of role information for an authorization manager (AzMan) policy store. AzMan is a Windows download that enables you to group individual operations together to form tasks. You can then authorize roles to perform specific tasks, individual operations, or both. AzMan provides an MMC snap-in to manage roles, tasks, operations, and users. Role information is stored in a proper policy store, which can be an XML file, an Active Directory, or an ADAM server.

Custom role providers can be created deriving from RoleProvider and registered using the child <providers> section in the <roleManager> section. Note that the process for doing this is nearly identical to the process you saw for the custom membership provider we explored previously.

The key idea behind claims-based identity is that an application (and not just an ASP.NET application) uses a third-party provider that assumes responsibility for returning a few true statements about a user. These statements are known as claims. The calling application gets the list of claims and, based on that, decides which sections of the site should be unveiled to the user and which features should be enabled.

For developers, the biggest change is that you don’t include in your codebase anything that deals with authentication and authorization. You simply arrange a conversation with an external identity provider, tell it about the statements you’re interested in verifying, and wait for a response. The user is redirected somewhere else (presumably to the identity provider site), provides requested credentials, and gets authenticated.

So, in the end, it is still about having a piece of code that collects and verifies credentials, isn’t it? Ultimately, it has to be this way because this is the only way in which authentication works. As a developer, though, you just outsource authentication to an external provider that you trust and that you have explicitly selected.

Figure 19-7 illustrates the typical workflow that characterizes a claims-based authentication process. The user initially connects to the application and attempts to log in. If all goes well, the user is ultimately redirected to the requested (and protected) page—nearly the same as in the authentication process we just reviewed. However, everything else is different under the surface.

Figure 19-7. The typical flow of claims-based authentication.

An application designed to take advantage of claims-based identity redirects the user to the identity provider of choice. The user interacts with the site of the provider and enters any information that the provider reckons to be useful to authenticate the request. If the operation is successful, the identity provider issues a security token and redirects back to the application. The security token that is then handed over to the application contains claims about the user. These claims are trusted by the application.

So a claim is nothing more than a statement that has been verified by the identity provider, and the identity provider guarantees it is true. What kind of statements are we talking about, however? A claim is strictly bound to the provider. Different providers can issue different claims, and not all providers can validate a given claim.

A canonical example often discussed to introduce the concept of a claim is an online wine shop that needs to be sure about the age of the people placing orders. In this case, the classic approach of having users register with the site, provide a birth date, and proceed with purchasing products doesn’t work. Who can reliably prove that the user is really of the legal age for purchasing alcohol? Certainly not the user himself!

In a claims-based system, the wine shop application might rely on an identity provider that “claims” to be able to verify the age of a user. The provider can ask for a driver’s license number and cross check that number with the database of the Driving and Licensing department. Any identity provider must expose a policy document that lists its requirements (protocols, endpoints, data formats) and the list of claims it can support. An application must likewise incorporate a policy document with the list of security requirements—facts the application needs to know for sure in order to proceed. Furthermore, the application must include a list of valid and trusted providers.

Issued by the identity provider, a security token travels the network to reach the requesting application and carry information. The security token is digitally signed, can’t be tampered with, and can be related to the issuing provider.

Strictly related to identity providers are the Security Token Service (STS). An STS provides a standards-based method of authenticating users and completely hides the details of how this is done internally.

To make an ASP.NET application claims-aware, you first need to get an STS. To start, you can use SelfSTS—a utility that emulates the minimal behavior of a realistic STS. You can get the STS from http://code.msdn.microsoft.com/SelfSTS.

If you use a Microsoft-provided project template for WIF, you then can rely on some tooling made to measure to add an STS reference and generate proper changes to code and configuration. At the end of the procedure, your authentication mode in the web.config file is probably set to None and a few HTTP modules have been added to the application’s runtime environment.

With STS configured and WIF modules in place, the type behind the HttpContext.User property is IClaimsPrincipal:

var claimsPrincipal = HttpContext.Current.User as IClaimsPrincipal;
var claimsIdentity = (IClaimsIdentity) claimsPrincipal.Identity;

You now own all claims as issued by the sample STS. You can enumerate claims with a plain loop, as shown here:

foreach(var claim in claimsIdentity.Claims)
{
    // Use claims. Properties are ClaimType and Value
}

You use claims to enable or disable the various features of the application on a per-user basis.

For a lot more information about WIF and motivation to use it, I invite you to read Vittorio Bertocci’s excellent book, “Programming Windows Identity Foundation” (Microsoft Press, 2010).

Compared to classic Forms authentication, claims-based identity has one noticeable difference for developers that can influence your decision to go with it or stick to more traditional solutions. You usually can’t have a list of all the users that could log into your application.

All that your application can do is make public the list of claims it needs. After that, the selected (and trusted) STS gains control over the implementation of user accounts, and all your application has to do is check claims presented by users and reject users who don’t match requested claims. In this way, you should never be required to modify the application to accommodate new users, even when these new users come from other sites as might be the case with federated sites.

The Login control is a composite control that provides all the common user interface elements of a login form. To use it, you simply drop the control from the toolbox onto the Web form, or you just type the following code:

<asp:login runat="server" id="MyLoginForm" />

The Login control also has optional user-interface elements for functions such as password reminders, new user registration, help links, error messages, and a custom action used in the case of a successful login. When you drop the control onto a Visual Studio form, the AutoFormat verb lets you choose among a few predefined styles, as shown in Figure 19-9.

Figure 19-9. The predefined styles of the Login control.

The appearance of the control is fully customizable through templates and style settings. All user-interface text messages are also customizable through properties of the class.

The control is modularized, and each constituent part can be individually customized. The parts include the Username and Password text boxes, the Submit button, the button to create a new user, the Remember Me check box, and instructions with guidance to the user.

If you don’t like the standard user interface of the control, you can define your own template too:

<asp:login runat="server" id="MyLoginForm">
     <layouttemplate>
        ...
     </layouttemplate>
</asp:login>

Your template can include new elements, and you can recycle default components. To do the latter, you should use the same ID for the controls as in the default template. To simplify this operation, right-click on the control in the Visual Studio designer, choose Convert To Template, and switch to the Source view. The markup you see is the default template of the control expressed as ASP.NET code. Use it as a starting point for creating your own template.

The Login control fires the server events listed in Table 19-15.

In most common cases, though, you don’t need to handle any of these events, nor will you likely find it necessary to programmatically access any of the numerous properties of the control.

The most common use for the Login control is to use it as a single-control page to set up the user interface of the login page for use with Forms authentication. The control relies entirely on the membership API (and the selected provider) to execute standard operations, such as validating credentials, displaying error messages, and redirecting to the originally requested page in the case of a successful login.

If you have a provider with custom capabilities that you want to be reflected by the Login control, you need to modify the layout to add new visual elements bound to a code-behind method. In the code-behind method, you invoke the custom method on the custom provider.

The LoginStatus control is often used in conjunction with the LoginName control to display the name of the current user (if any), plus a button to let the user log in or out. The style, text, and action associated with the button changes are conveniently based on the authentication state of the user.

The following code creates a table showing the name of the current user and a button to log in or log out:

<table width="100%" border="0"><tr>
    <td>
        <asp:loginname runat="server" FormatString="Welcome, {0}" />
    </td>
    <td align="right">
        <asp:loginstatus runat="server" LogoutText="Log off" />
    </td>
  </tr>
</table>

To detect whether the current user is authenticated and adapt the user interface, you can use the IsAuthenticated property of the User object:

void Page_Load(object sender, EventArgs e)
{
    if (User.Identity.IsAuthenticated)
       // Adjust the UI by outputting some text to a label
        Msg.Text = "Enjoy more features";
    else
        Msg.Text = "Login to enjoy more features.";
}

Although the LoginStatus control is quite useful in its default form, it provides a bunch of properties and events you can use to configure it. The properties are listed in Table 19-16.

The control also features a couple events: LoggingOut and LoggedOut. The former fires before the user clicks to log off. The latter is raised immediately after the logout process has completed.

Table 19-17 lists the properties of the user interface of the LoginView control.

Note that the LoggedInTemplate template is displayed only to logged-in users who are not members of one of the role groups specified in the RoleGroups property. The template (if any) specified in the <roleGroups> tag always takes precedence.

The LoginView control also fires the ViewChanging and ViewChanged events. The former reaches the application when the control is going to change the view (such as when a user logs in). The latter event fires when the view has changed.

The LoginView control lets you define two distinct templates to show to anonymous and logged-in users. You can use the following markup to give your pages a common layout and manage the template to show when the user is logged in:

<asp:loginview runat="server">
   <anonymoustemplate>
      <table width="100%" border="0"><tr><td>
         To enjoy more features,
         <asp:loginstatus runat="server">
      </td></tr></table>
   </anonymoustemplate>
   <loggedintemplate>
      <table width="100%" border="0"><tr>
         <td><asp:loginname runat="server" /></td>
         <td align="right"><asp:loginstatus runat="server" /></td>
      </tr></table>
   </loggedintemplate>
</asp:loginview>

Basically, the LoginView control provides a more flexible, template-based programming interface to distinguish between logged-in and anonymous scenarios, as we did in the previous example by combining LoginStatus and LoginName.

The LoginView control also allows you to define blocks of user interface to display to all logged-in users who belong to a particular role. As mentioned, these templates take precedence over the <loggedintemplate> template, if both apply.

<asp:loginview runat="server">
   <rolegroups>
      <asp:rolegroup roles="Admin">
         <contenttemplate>
            ...
         </contenttemplate>
      </asp:rolegroup>
      <asp:rolegroup roles="Guest">
         <contenttemplate>
            ...
         </contenttemplate>
      </asp:rolegroup>
   </rolegroups>
</asp:loginview>

The content of each <contenttemplate> block is displayed only to users whose role matches the value of the roles attribute. You can use this feature to create areas in a page whose contents are strictly role-specific. For the LoginView control to work fine, role management must be enabled, of course. The control uses the default provider.

For the control to work properly, you must first ensure that the selected membership provider supports password retrieval. The password retrieval also requires the provider to define a MembershipUser object and implement the GetUser methods. Remember that the membership provider decides how to store passwords: clear text, hashed, or encrypted. Best practice, of course, is to only store hashed passwords.

If passwords are stored as hashed values, the control doesn’t work. Hash algorithms are not two-way algorithms. In other words, the hash mechanism is great at encrypting and comparing passwords, but it doesn’t retrieve the clear text. If you plan to use the PasswordRecovery control, you must ensure that the provider stores passwords as clear text or encrypted data.

The PasswordRecovery control supports a child element named MailDefinition:

<asp:passwordrecovery runat="server">
   <maildefinition from="[email protected]" />
</asp:passwordrecovery>

The <MailDefinition> element configures the e-mail message and indicates the sender as well as the format of the body (text or HTML), priority, subject, and carbon-copy (CC). For the same settings, you can also use a bunch of equivalent properties on the associated Framework class and set values programmatically.

If the user who has lost the password has a question/answer pair defined, the PasswordRecovery control changes its user interface to display the question and ask for the answer before the password is retrieved and sent back.

The control first asks the user to provide the user name; next it retrieves associated information and displays the security question, if any is defined for the user. Finally, if an e-mail address is known, the control sends a message with details. Bear in mind that you need to have proper e-mail settings in the web.config file, specifically in the <system.net> section, as shown here:

<system.net>
  <mailSettings>
    <smtp deliveryMethod="Network">
      <network host="your.smtp.server" />
    </smtp>
  </mailSettings>
</system.net>

The ChangePassword control will work in scenarios where a user might or might not be already authenticated. However, note that the User Name text box is optional. If you choose not to display the user name and still permit nonauthenticated users to change their password, the control will always fail.

If the user is not authenticated but the User Name text box is displayed, the user will be able to enter his or her user name, current password, and new password at the same time.

The change of the password is performed using the ChangePassword method on the MembershipUser object that represents the user making the attempt. Note that the provider might pose an upper limit to the invalid attempts to change or reset the password. If set, this limit affects the ChangePassword control. The control won’t work any longer after the limit has been exceeded.

After the password has been successfully changed, the control can send—if properly configured—a confirmation e-mail to the user. The e-mail message is configured through the same <MailDefinition> element you saw earlier for the PasswordRecovery control.

The Continue button points the page with the control to a new destination URL to let users continue working. If you don’t set the ContinuePageDestinationUrl property, clicking the button simply refreshes the current page.