Several configuration options are specific to Forms authentication:

Several of these configuration settings are related to the authentication cookie. For example, you can use the web configuration file in Listing 23.2 to change the name of the authentication cookie.

<configuration>

    <system.web>
      <authentication mode="Forms">
        <forms name="MyApp" />
      </authentication>

    </system.web>
</configuration>

Several of these options require additional explanation. In the following sections, you learn how to enable cookieless authentication, modify the cookie expiration policy, and enable authentication across applications.

Normally, Forms authentication uses a cookie to identify a user. However, Forms authentication also supports a feature named cookieless authentication. When cookieless authentication is enabled, a user can be identified without a browser cookie.

By taking advantage of cookieless authentication, you can use Forms Authentication and ASP.NET Membership to authenticate users even when someone is using a browser that does not support cookies or a browser with cookies disabled.

When cookieless authentication is enabled, a user can be identified by a unique token added to a page’s URL. If a user uses relative URLs to link from one page to another, then the token is passed from page to page automatically and the user can be identified across multiple page requests.

When you request a page that requires authentication and cookieless authentication is enabled, the URL in the browser address bar looks like this:

http://localhost:2500/Original/(F(WfAnevWxFyuN4SpenRclAEh_lY6OKWVllOKdQkRk
tOqV7cfcrgUJ2NKxNhH9dTA7fgzZ-cZwyr4ojyU6EnarC-bbf8g4sl6m4k5kk6Nmcsg1))
/SecretFiles/Secret2.aspx

That long, ugly code in the URL is the user’s encoded authentication ticket.

You configure cookieless authentication by assigning a value to the cookieless attribute of the forms element in the web configuration file. The cookieless attribute accepts any of the following four values:

The default value is UseDeviceProfile. By default, the ASP.NET Framework issues a cookie only when a particular type of device supports cookies. The ASP.NET Framework maintains a database of device capabilities in a set of files contained in the following folder:

WINDOWSMicrosoft.NETFrameworkv2.0.50727CONFIGBrowsers

By default, the ASP.NET Framework never uses cookieless authentication with a browser such as Microsoft Internet Explorer. According to the device profile for Internet Explorer, Internet Explorer supports cookies, so cookieless authentication is not used. The Framework doesn’t use cookieless authentication even when cookies are disabled in a browser.

If you want the ASP.NET Framework to automatically detect whether a browser supports cookies, then you need to set the cookieless attribute to the value AutoDetect. When AutoDetect is enabled, the ASP.NET Framework checks whether a browser sends an HTTP COOKIE header. If the COOKIE header is present, then an authentication cookie is assigned to the browser. Otherwise, the ASP.NET Framework uses cookieless authentication.

The web configuration file in Listing 23.3 enables AutoDetect.

<configuration>
    <system.web>
      <authentication mode="Forms">
        <forms cookieless="AutoDetect"/>
      </authentication>
    </system.web>
</configuration>

By default, Forms authentication uses a sliding expiration policy. As long as a user lets no more than 30 minutes pass without requesting a page, the user continues to be authenticated. However, if the user does not request a page for 30 minutes, then the user is logged out automatically.

If you have strict security requirements, you can use an absolute expiration policy rather than a sliding expiration policy. In other words, you can force a user to log in again after a particular interval of time.

The web configuration file in Listing 23.4 forces a user to log in again every minute.

<configuration>
    <system.web>
      <authentication mode="Forms">
        <forms slidingExpiration="false" timeout="1" />
      </authentication>
    </system.web>
</configuration>

By default, Forms authentication is application relative. In other words, if you log in to one application, you aren’t logged in to any other application—even when the other application is located on the same web server.

This creates problems in two situations. First, you don’t want to require the employees of your company to log in multiple times as they move between different applications hosted by your company. An employee should be able to log in once and use any application provided by your company automatically.

Second, if you are hosting a web farm, you don’t want to force a user to log in whenever a request is served by a different web server. From the perspective of a user, a web farm should seem just like a single server.

By default, the Forms authentication cookie is encrypted and signed. Furthermore, by default, each application generates a unique decryption and validation key. Therefore, by default, you can’t share the same authentication cookie across applications.

You specify encryption and validation options with the machineKey element in the web configuration file. Here are the default settings for this element:

<machineKey
  decryption="Auto"
  validation="SHA1"
  decryptionKey="AutoGenerate,IsolateApps"
  validationKey="AutoGenerate,IsolateApps" />

The decryption attribute specifies the algorithm used to encrypt and decrypt the forms authentication cookie. Possible values are Auto, AES (the government standard encryption algorithm), and 3DES (Triple DES). By default, the decryption attribute is set to Auto, which causes the ASP.NET Framework to select the encryption algorithm based on the capabilities of the web server.

The validation attribute specifies the hash or encryption algorithm used when an authentication cookie is signed. Possible values are AES, MD5, SHA1, and TripleDES.

The decryptionKey attribute represents the key used to encrypt and decrypt the authentication cookie. The validationKey represents the key used when the authentication cookie is signed. By default, both attributes are set to the value AutoGenerate, which causes the ASP.NET Framework to generate a random key and store it in the LSA (your web server’s Local Security Authority).

Notice that both the decryptionKey and validationKey attributes include an IsolateApps modifier. When the IsolateApps modifier is present, a unique key is created for each application on the same web server.

If you want to share the same authentication cookie across every application hosted on the same web server, then you can override the default machineKey element in the machine root web configuration file and remove the IsolateApps attribute from both the decryptionKey and validationKey attributes. You can add the following machineKey element anywhere within the system.web section in the web configuration file:

<machineKey
  decryption="Auto"
  validation="SHA1"
  decryptionKey="AutoGenerate"
  validationKey="AutoGenerate" />

The root web configuration file is located at the following path:

C:WINDOWSMicrosoft.NETFrameworkv2.0.50727CONFIGWeb.Config

On the other hand, if you need to share the same authentication cookie across separate web servers, then you need to specify the decryptionKey and validationKey manually. You cannot allow the ASP.NET Framework to generate these keys automatically because you need to share the keys across the different web servers.

For example, the following machineKey element contains explicit decryption and validation keys:

<machineKey
  decryption="AES"
  validation="SHA1"
  decryptionKey="306C1FA852AB3B0115150DD8BA30821CDFD125538A0C606DACA53DBB3C3E0AD2"
    validationKey="61A8E04A146AFFAB81B6AD19654F99EA7370807F18F5002725DAB98B8EF
    D19C711337E26948E26D1D174B159973EA0BE8CC9CAA6AAF513BF84E44B2247792265" />

When using AES, you need to set the decryption key to a random sequence of 64 hex characters. When using SHA1, you need to set the decryption key to a random sequence of 128 hex characters. You can use the page in Listing 23.5 to generate these random character sequences for you (see Figure 23.1).

Figure 23.1. Generating cryptographically strong keys.

<%@ Page Language="C#" %>
<%@ Import Namespace="System.Security.Cryptography" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">

    void Page_Load()
    {
        lblAES.Text = GetSequence(64);
        lblSHA1.Text = GetSequence(128);
    }

    private string GetSequence(int length)
    {
        byte[] buffer = new byte[length/2];
        RNGCryptoServiceProvider provider = new RNGCryptoServiceProvider();
        provider.GetBytes(buffer);
        StringBuilder builder = new StringBuilder(length);
        for (int i = 0; i < buffer.Length; i++)
            builder.Append(string.Format("{0:X2}", buffer[i]));
        return builder.ToString();
    }
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>Generate Keys</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>

    AES:
    <asp:Label
        id="lblAES"
        Runat="server" />
    <br /><br />
    SHA1:
    <asp:Label
        id="lblSHA1"
        Runat="server" />

    </div>
    </form>
</body>
</html>

The page in Listing 23.5 uses the RNGCryptoServiceProvider to generate the random sequence of characters. The GetBytes() method returns a cryptographically strong sequence of random values.

You can add a machineKey element with explicit keys to either the machine root web configuration file or to particular application web configuration files. If you don’t want to share the same keys across all the applications on a web server, then you should add the machineKey element only to the applications that you need to share.

In the previous section, you learned how to share the same authentication cookie across applications located on the same server or a different server. But how do you share the same authentication cookie across domains?

A browser cookie is always domain relative. For example, the Amazon website cannot read cookies set by the Barnes and Noble website, which is a good thing. However, you might discover that you need to share authentication information across websites with different domains.

You can work around this problem by passing an authentication ticket in a query string parameter rather than in a cookie. There is nothing to prevent you from passing query strings between domains.

To enable this scenario, you must configure your applications to accept authentication tickets passed in a query string. The web configuration file in Listing 23.6 includes an enableCrossAppRedirects attribute that enables sharing authentication tickets across domains.

<configuration>
  <system.web>
    <authentication mode="Forms">
      <forms enableCrossAppRedirects="true" />
    </authentication>

    <machineKey
      decryption="AES"
      validation="SHA1"
      decryptionKey="306C1FA852AB3B0115150DD8BA30821CDFD125538A0C606 DACA53DBB3C3E0AD2"
      validationKey="61A8E04A146AFFAB81B6AD19654F99EA7370807F18F5002725DAB98B 8EFD19C711337E26948E26D1D174B159973EA0BE8CC9CAA6AAF513BF84E44B2247792265" />

  </system.web>
</configuration>

If you add the web configuration file in Listing 23.6 to two applications located in different domains, the two applications can share the same authentication ticket.

When you link or redirect from one application to another, you must pass the authentication ticket in a query string parameter. The page in Listing 23.7 adds the necessary query string parameter to a hyperlink.

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">

    void Page_Load()
    {
        string cookieName = FormsAuthentication.FormsCookieName;
        string cookieValue = FormsAuthentication.GetAuthCookie(User.Identity.Name, false).Value;
        lnkOtherDomain.NavigateUrl += String.Format("?{0}={1}", cookieName, cookieValue);
    }
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>Query String Authenticate</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>

    <asp:HyperLink
        id="lnkOtherDomain"
        Text="Link to Other Domain"
        NavigateUrl="http://www.OtherDomain.com/Secret.aspx"
        Runat="server" />

    </div>
    </form>
</body>
</html>
</html>

The main application programming interface for interacting with Forms authentication is the FormsAuthentication class. This class supports the following properties:

These properties return the configuration settings for Forms authentication from the web configuration file.

The FormsAuthentication class supports the following methods:

You can use the methods and properties of the FormsAuthentication class to build a user registration and authentication system without using ASP.NET Membership. For example, the web configuration file in Listing 23.8 contains a list of usernames and passwords.

<configuration>
  <system.web>

    <authentication mode="Forms">
      <forms>
        <credentials passwordFormat="Clear">
          <user name="Bill" password="secret" />
          <user name="Jane" password="secret" />
          <user name="Fred" password="secret" />
        </credentials>
      </forms>
    </authentication>

  </system.web>
</configuration>

The web configuration file in Listing 23.8 contains a forms element that contains a credentials element. The credentials element includes a list of usernames and passwords.

Notice that the credentials element includes a passwordFormat attribute that is set to the value Clear. If you prefer, rather than store passwords in clear text, you can store password hash values. That way, anyone working on the web server can’t see everyone else’s passwords. The other two possible values for the passwordFormat attribute are MD5 and SHA1.

The Login page in Listing 23.9 contains a User Name and a Password text box (see Figure 23.2).

Figure 23.2. Authenticating against web configuration credentials.

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
    protected void btnLogin_Click(object sender, EventArgs e)
    {
        if (FormsAuthentication.Authenticate(txtUserName.Text,txtPassword.Text))
            FormsAuthentication.RedirectFromLoginPage(txtUserName.Text, chkRememberMe.Checked);
        else
            lblError.Text = "Invalid user name/password";
    }
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>Forms Login</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>

    <asp:Label
        id="lblError"
        EnableViewState="false"
        ForeColor="Red"
        Runat="server" />

    <br /><br />
    <asp:Label
        id="lblUserName"
        Text="User Name:"
        AssociatedControlID="txtUserName"
        Runat="server" />
    <br />
    <asp:TextBox
        id="txtUserName"
        Runat="server" />
    <br /><br />
    <asp:Label
        id="lblPassword"
        Text="Password:"
        AssociatedControlID="txtPassword"
        Runat="server" />
    <br />
    <asp:TextBox
        id="txtPassword"
        TextMode="Password"
        Runat="server" />
    <br /><br />
    <asp:CheckBox
        id="chkRememberMe"
        Text="Remember Me"
        Runat="server" />
    <br /><br />
    <asp:Button
        id="btnLogin"
        Text="Login"
        OnClick="btnLogin_Click"
        Runat="server" />

    </div>
    </form>
</body>
</html>

When you click the Login button, the btnLogin_Click() handler executes, and the FormsAuthentication.Authenticate() method is used to check whether the username and password entered into the TextBox controls match a username and password in the web configuration file. If the user successfully authenticates, the FormsAuthentication.RedirectFromLoginPage() method is called.

The RedirectFromLoginPage() method does two things. The method adds an authentication cookie to the user’s browser. The method also redirects the user back to whatever page the user originally requested. If the user requests the Login page directly, then the user is redirected to the Default.aspx page.

The second parameter passed to the RedirectFromLoginPage() method indicates whether you want to create a session or persistent cookie. If you create a persistent cookie, then a user does not need to log in when the user returns to the website in the future.

You can use the Page.User or the HttpContext.User property to retrieve information about the current user. The Page.User property exposes a Principal object that supports the following method:

For example, when Windows authentication is enabled, you can use the IsInRole() method to check whether a user is a member of a particular Microsoft Windows group such as the BUILTINAdministrators group:

if (User.IsInRole("BUILTINAdministrators"))
{
   // Do some Administrator only operation
}

The Principal object also includes an Identity property that enables you to get information about the current user’s identity. The Identity object supports the following three properties:

If you want to get the name of the current user, then you can use logic that looks like this:

Dim name As String = User.Identity.Name

If a user is not authenticated, the User.Identity.Name property returns an empty string.

When creating authorization rules, you can authorize by user role. For example, the web configuration file in Listing 23.12 prevents access to any pages in a folder by anyone except members of the Administrators role.

<configuration>
    <system.web>

      <authorization>
        <allow roles="Administrator"/>
        <deny users="*"/>

      </authorization>

    </system.web>
</configuration>

When Forms authentication is enabled, the role refers to a custom role. In the final section of this chapter, “Using the Role Manager,” you learn how to configure and create custom roles. When Windows authentication is enabled, the role refers to a Microsoft Windows group.

By default, authorization rules are applied to all pages in a folder and all subfolders. However, you also have the option of using the location element with the authorization element. The location element enables you to apply a set of authorization rules to a folder or page at a particular path.

For example, imagine that you want to password-protect one, and only one, page in a folder. In that case, you can use the location element to specify the path of the single page. The web configuration file in Listing 23.13 password-protects a page named Secret.aspx.

<configuration>

  <system.web>
    <authentication mode="Forms" />
  </system.web>

  <location path="Secret.aspx">
    <system.web>
      <authorization>
        <deny users="?"/>
      </authorization>
    </system.web>
  </location>

</configuration>

You also can use the location element to apply configuration settings to a particular subfolder. For example, the web configuration file in Listing 23.14 password-protects a folder named SecretFiles.

<configuration>

  <system.web>
    <authentication mode="Forms" />
  </system.web>

  <location path="SecretFiles">
    <system.web>
      <authorization>
        <deny users="?"/>
      </authorization>
    </system.web>
  </location>

</configuration>

Authorization rules are applied only to files mapped into the ASP.NET Framework. The Visual Web Developer web server maps all file types to the ASP.NET Framework. Internet Information Server, on the other hand, maps only particular file types to the ASP.NET Framework.

If you are using Internet Information Server, and you add an image to a password-protected folder, then users aren’t blocked from requesting the image. By default, authorization rules apply only to ASP.NET file types such as ASP.NET pages. Files such as images, Microsoft Word documents, and classic ASP pages are ignored by the ASP.NET Framework.

If you need to password-protect a particular type of static file, such as an image or Microsoft Word document, then you need to map the file’s extension to the ASP.NET ISAPI extension.

For example, follow these steps to enable authorization for .gif image files:

After you complete these steps, requests for .gif images are passed to the ASP.NET Framework. You can then use authentication and authorization rules with .gif images.

You can complete the same sequence of steps to password-protect other static file types, such as Microsoft Word documents, Excel spreadsheets, or video files.

You can mix ASP.NET pages and ASP classic pages in the same application. However, normally ASP.NET pages and ASP classic pages live in parallel but separate universes. In particular, ASP.NET authentication and authorization is not applied to ASP classic pages.

If you are using Internet Information Server 6 (available with Windows Server 2003), then you can map ASP classic pages into the ASP.NET Framework. In that case, you can apply ASP.NET authorization rules to ASP classic pages.

Internet Information Server 6 supports a feature named wildcard application mappings. You can use a wildcard mapping to intercept requests for ASP classic pages and process the requests with the ASP.NET Framework. The ASP.NET Framework can then pass the request back to be executed by ASP classic.

To enable wildcard mapping for ASP.NET, follow these steps:

After you complete these steps, then all files, not only ASP classic files, are mapped to the ASP.NET Framework. You can use ASP.NET authorization rules to password-protect ASP classic pages in the same way that you can use these rules to password-protect ASP.NET pages. The authorization rules also work with image files, Microsoft Word documents, and any other type of file.

The main application programming interface for ASP.NET Membership is the Membership class. This class supports the following methods:

This class also supports the following event:

You can use the methods of the Membership class to administer the users of your website. For example, the page in Listing 23.15 displays a list of every registered user (see Figure 23.5).

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>List Users</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>

    <asp:GridView
        id="grdUsers"
        DataSourceID="srcUsers"
        Runat="server" />

    <asp:ObjectDataSource
        id="srcUsers"
        TypeName="System.Web.Security.Membership"
        SelectMethod="GetAllUsers"
        Runat="server" />

    </div>
    </form>
</body>
</html>

Figure 23.5. Displaying registered users.

In Listing 23.15, an ObjectDataSource control is used to represent the Membership class. The GetAllUsers() method is called to get the list of users.

You also can use the methods of the Membership class to create custom Login controls. For example, notice that you can retrieve the number of users currently online by calling the GetNumberOfUsersOnline() method. The custom control in Listing 23.16 displays the value returned by this method.

using System;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace myControls
{
    /// <summary>
    /// Displays Number of Users Online
    /// </summary>
    public class UsersOnline : WebControl
    {
        protected override void RenderContents(HtmlTextWriter writer)
        {
            writer.Write(Membership.GetNumberOfUsersOnline());
        }
    }
}

The page in Listing 23.17 uses the UsersOnline control to display the number of users currently online (see Figure 23.6).

<%@ Page Language="C#" %>
<%@ Register TagPrefix="custom" Namespace="myControls" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>Show UsersOnline</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>

    How many people are online?
    <br/>
    <custom:UsersOnline
        id="UsersOnline1"
        Runat="server" />

    </div>
    </form>
</body>
</html>

Figure 23.6. Display number of users online.

Several of the methods of the Membership class return one or more MembershipUser objects. The MembershipUser object is used to represent a particular website member. This class supports the following properties:

Notice that the MembershipUser class does not contain a property for the user’s password or password answer. This is intentional. If you need to change a user’s password, then you need to call a method.

The MembershipUser class supports the following methods:

Both of the default Membership providers included in the ASP.NET Framework enable you to store user passwords in three ways:

You configure how passwords are stored by setting the passwordFormat attribute in the web configuration file. For example, the web configuration file in Listing 23.18 configures the SqlMembershipProvider to store passwords in plain text.

<configuration>
    <system.web>
      <authentication mode="Forms" />

      <membership defaultProvider="MyProvider">
        <providers>
          <add
            name="MyProvider"
            type="System.Web.Security.SqlMembershipProvider"
            passwordFormat="Clear"
            connectionStringName="LocalSqlServer"/>
        </providers>

      </membership>
    </system.web>
</configuration>

The default value of the passwordFormat attribute is Hashed. By default, actual passwords are not stored anywhere. A hash value is generated for a password and the hash value is stored.

The advantage of storing hash values is that even if your website is compromised by a hacker, the hacker cannot steal anyone’s passwords. The disadvantage of using hash values is that you also cannot retrieve user passwords. For example, you cannot use the PasswordRecovery control to email a user his original password.

Instead of hashing passwords, you can encrypt the passwords. The disadvantage of encrypting passwords is that it is more processor intensive than hashing passwords. The advantage of encrypting passwords is that you can retrieve user passwords.

The web configuration file in Listing 23.19 configures the SqlMembershipProvider to encrypt passwords. Notice that the web configuration file includes a machineKey element. You must supply an explicit decryptionKey when encrypting passwords.

<configuration>
  <system.web>
    <authentication mode="Forms" />

    <membership defaultProvider="MyProvider">
      <providers>
        <add
          name="MyProvider"
          type="System.Web.Security.SqlMembershipProvider"
          passwordFormat="Encrypted"
          connectionStringName="LocalSqlServer"/>
      </providers>
    </membership>

    <machineKey
        decryption="AES"
        decryptionKey="306C1FA852AB3B0115150DD8BA30821CDFD125538A0C606 DACA53DBB3C3E0AD2" />


  </system.web>
</configuration>

By default, passwords are required to contain at least seven characters and one non-alphanumeric character (a character that is not a letter or a number such as *,_, or !). You can set three Membership provider attributes that determine password policy:

The minRequiredNonAlphanumericCharacters attribute confuses everyone. Website users are not familiar with the requirement that they must enter a nonalphanumeric character. The web configuration file in Listing 23.20 illustrates how you can disable this requirement when using the SqlMembershipProvider.

<configuration>
  <system.web>
    <authentication mode="Forms" />

    <membership defaultProvider="MyProvider">
      <providers>
        <add
          name="MyProvider"
          type="System.Web.Security.SqlMembershipProvider"
          minRequiredNonalphanumericCharacters="0"
          connectionStringName="LocalSqlServer"/>
      </providers>
    </membership>

  </system.web>
</configuration>

By default, if you enter a bad password more than five times within 10 minutes, your account is automatically locked out. In other words, it is disabled.

Also, if you enter the wrong answer for the password answer more than five times in a 10-minute interval, your account is locked out. You get five attempts at your password and five attempts at your password answer. (These two things are tracked independently.)

Two configuration settings control when an account gets locked out:

For example, the web configuration file in Listing 23.21 modifies the default settings to enable you to enter a maximum of three bad passwords or bad password answers in one hour.

<configuration>
  <system.web>
    <authentication mode="Forms" />

    <membership defaultProvider="MyProvider">
      <providers>
        <add
          name="MyProvider"
          type="System.Web.Security.SqlMembershipProvider"
          maxInvalidPasswordAttempts="3"
          passwordAttemptWindow="60"
          connectionStringName="LocalSqlServer"/>
      </providers>
    </membership>

  </system.web>
</configuration>

After a user has been locked out, you must call the MembershipUser.UnlockUser() method to re-enable the user account. The page in Listing 23.22 enables you to enter a username and remove a lock (see Figure 23.7).

Figure 23.7. Removing a user lock.

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">

    protected void btnRemove_Click(object sender, EventArgs e)
    {
        MembershipUser userToUnlock = Membership.GetUser(txtUserName.Text);
        if (userToUnlock == null)
        {
            lblMessage.Text = "User not found!";
        }
        else
        {
            userToUnlock.UnlockUser();
            lblMessage.Text = "Lock removed!";
        }
    }
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Remove Lock</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>

    <asp:Label
        id="lblUserName"
        Text="User Name:"
        AssociatedControlID="txtUserName"
        Runat="server" />
    <asp:TextBox
        id="txtUserName"
        Runat="server" />
    <asp:Button
        id="btnRemove"
        Text="Remove Lock"
        Runat="server" OnClick="btnRemove_Click" />
    <br />
    <asp:Label
        id="lblMessage"
        EnableViewState="false"
        Runat="server" />
    </div>
    </form>
</body>
</html>

The SqlMembershipProvider is the default Membership provider. Unless otherwise configured, it stores membership information in the local ASPNETDB.mdf Microsoft SQL Server Express database located in your application’s App_Data folder. This database is created for you automatically the first time that you use Membership.

If you want to store membership information in some other Microsoft SQL Server database, then you need to perform the following two tasks:

To complete the first task, you can use the aspnet_regiis command-line tool. This tool is located in the following folder:

WINDOWSMicrosoft.NETFrameworkv2.0.50727

If you execute the aspnet_regsql tool without supplying any parameters, then the ASP.NET SQL Server Setup Wizard appears (see Figure 23.8). You can use this wizard to select a database and install the Membership objects automatically.

Figure 23.8. Using the ASP.NET SQL Setup Wizard.

If you prefer, rather than use the aspnet_reqsql tool, you can execute the following two SQL batch files to install Membership:

WINDOWSMicrosoft.NETFrameworkv2.0.50727InstallCommon.sql
WINDOWSMicrosoft.NETFrameworkv2.0.50727InstallMembership.sql

If you don’t want to install the .NET Framework on your database server, then you can execute these SQL batch files.

After you have configured your database to support ASP.NET Membership, you must configure your application to connect to your database when using Membership. The web configuration file in Listing 23.23 connects to a database named MyDatabase located on a server named MyServer.

<configuration>
  <connectionStrings>
    <add name="MyConnection" connectionString="Data Source=MyServer;IntegratedSecurity=True;Initial Catalog=MyDatabase"/>
  </connectionStrings>

  <system.web>
    <authentication mode="Forms" />

    <membership defaultProvider="MyMembershipProvider" >
      <providers>
        <add
          name="MyMembershipProvider"
          type="System.Web.Security.SqlMembershipProvider"
          connectionStringName="MyConnection" />
      </providers>
    </membership>
  </system.web>
</configuration>

In Listing 23.23, a new default Membership provider named MyMembershipProvider is configured. The new Membership provider uses a connection string name that has the value MyConnection. The MyConnection connection string is defined in the connectionStrings element near the top of the configuration file. This connection string represents a connection to a database named MyDatabase located on a server named MyServer.

The other Membership provider included in the ASP.NET Framework is the ActiveDirectoryMembershipProvider. You can use this provider to store user information in Active Directory or ADAM (Active Directory Application Mode).

ADAM is a lightweight version of Active Directory. You can download ADAM from the Microsoft website (www.microsoft.com/adam). ADAM is compatible with both Microsoft Windows Server 2003 and Microsoft Windows XP Professional (Service Pack 1).

If you want to use ASP.NET Membership with ADAM, then you need to complete the following two steps:

The following sections examine each of these steps in turn.

<configuration>

  <connectionStrings>
    <add
      name="ADAMConnection"
      connectionString="LDAP://localhost:389/OU=WebUsers,O=WebUsersDirectory"/>
  </connectionStrings>

  <system.web>
    <authentication mode="Forms" />

    <membership defaultProvider="MyMembershipProvider">
      <providers>
        <add
          name="MyMembershipProvider"
          type="System.Web.Security.ActiveDirectoryMembershipProvider"
          connectionStringName="ADAMConnection"
          connectionProtection="None"
          connectionUsername="CN=ADAMAdministrator,OU=WebUsers,O=WebUsersDirectory"
          connectionPassword="secret_"
          enableSearchMethods="true" />

      </providers>
    </membership>
  </system.web>
</configuration>

Because ASP.NET Membership uses the provider model, you can easily extend ASP.NET membership by creating a custom Membership provider. There are two main situations in which you might need to create a custom Membership provider.

First, imagine that you have an existing ASP.NET 1.x or ASP classic application. You are currently storing membership information in your own custom set of database tables. Furthermore, your table schemas don’t easily map to the table schemas used by the SqlMembershipProvider.

In this situation, it makes sense to create a custom Membership provider that reflects your existing database schema. If you create a custom Membership provider, you can use your existing database tables with ASP.NET Membership.

Second, imagine that you need to store membership information in a data store other than Microsoft SQL Server or Active Directory. For example, your organization might be committed to Oracle or DB2. In that case, you need to create a custom Membership provider to work with the custom data store.

In this section, we create a simple custom Membership provider: an XmlMembershipProvider that stores membership information in an XML file.

Unfortunately, the code for the XmlMembershipProvider is too long to place here. The code is included on the CD that accompanies this book in a file named XmlMembershipProvider.cs, located in the App_Code folder.

The XmlMembershipProvider class inherits from the abstract MembershipProvider class. This class has over 25 properties and methods that you are required to implement.

For example, you are required to implement the ValidateUser() method. The Login control calls this method when it validates a username and password.

You also are required to implement the CreateUser() method. This method is called by the CreateUserWizard control when a new user is created.

The web configuration file used to set up the XmlMembershipProvider is contained in Listing 23.25.

<configuration>
    <system.web>

      <authentication mode="Forms" />

      <membership defaultProvider="MyMembershipProvider">
        <providers>
          <add
            name="MyMembershipProvider"
            type="AspNetUnleashed.XmlMembershipProvider"
            dataFile="~/App_Data/Membership.xml"
            requiresQuestionAndAnswer="false"
            enablePasswordRetrieval="true"
            enablePasswordReset="true"
            passwordFormat="Clear" />
        </providers>
      </membership>

    </system.web>
</configuration>

Notice that the XmlMembershipProvider supports a number of attributes. For example, it supports a passwordFormat attribute that enables you to specify whether passwords are stored as hash values or as plain text. (It does not support encrypted passwords.)

The XmlMembershipProvider stores membership information in an XML file named Membership.xml, located in the App_Data folder. If you want, you can add users to the file by hand. Alternatively, you can use the CreateUserWizard control or the Web Site Administration Tool to create new users.

A sample of the Membership.xml file is contained in Listing 23.26.

<credentials>
  <user name="Steve" password="secret" email="[email protected]" />
  <user name="Andrew" password="secret" email="[email protected]" />
</credentials>

The sample code folder on the CD includes a Register.aspx, Login.aspx, and ChangePassword.aspx page. You can use these pages to try out different features of the XmlMembershipProvider.

The SqlRoleProvider is the default role provider. You can use the SqlRoleProvider to store role information in a Microsoft SQL Server database. The SqlRoleProvider enables you to create custom roles. You can make up any roles that you need.

You can use the SqlRoleProvider with either Forms authentication or Windows authentication. When Forms authentication is enabled, you can use ASP.NET Membership to represent users and assign the users to particular roles. When Windows authentication is enabled, you assign particular Windows user accounts to custom roles. I assume, in this section, that you are using Forms authentication.

The web configuration file in Listing 23.27 enables the SqlRoleProvider.

<configuration>
    <system.web>
        <roleManager enabled="true" />
        <authentication mode="Forms" />
    </system.web>
</configuration>

The Role Manager is disabled by default. The configuration file in Listing 23.27 simply enables the Role Manager. Notice that the configuration file also enables Forms authentication.

If you don’t want to type the file in Listing 23.27, you can let the Web Site Administration Tool create the file for you. Open the Web Site Administration Tool in Visual Web Developer by selecting the menu option Website, ASP.NET Configuration. Next, click the Security tab and click the Enable roles link (see Figure 23.11).

Figure 23.11. Enabling Roles with the Web Site Administration Tool.

After you enable the Role Manager, you need to create some roles. You can create roles in two ways. You can use the Web Site Administration Tool or you can create the roles programmatically.

Open the Web Site Administration Tool and click the Create or Manage Roles link located under the Security tab. At this point, you can start creating roles. I’ll assume that you have created a role named Managers.

After you create a set of roles, you need to assign users to the roles. Again, you can do this by using the Web Site Administration Tool or you can assign users to roles programmatically.

If you have not created any users for your application, create a user now by clicking the Create User link under the Security tab. Notice that you can assign a user to one or more roles when you create the user (see Figure 23.12). You can click the Create or Manage Roles link to assign roles to users at a later date.

Figure 23.12. Assigning a new user to a role.

After you finish creating your roles and assigning users to the roles, you can use the roles in the authentication section of a web configuration file. For example, imagine that your website includes a folder named SecretFiles and you want only members of the Managers role to be able to access the pages in that folder. The web configuration file in Listing 23.28 blocks access to anyone except members of the Managers role to the SecretFiles folder.

<configuration>
    <system.web>

      <authorization>
        <allow roles="Managers"/>
        <deny users="*"/>
      </authorization>

    </system.web>
</configuration>

The configuration file in Listing 23.28 authorizes Managers and denies access to everyone else.

If you prefer, you can manage authorization with the Web Site Administration Tool. Behind the scenes, this tool creates web configuration files that contain authorization elements (in other words, it does the same thing as we just did).

Under the Security tab, click the Create Access Rules link. Select the SecretFiles folder from the tree view, select the Managers role, and select Allow (see Figure 23.13). Click the OK button to create the rule. Next, create a second access rule to deny access to users not in the Managers role. Select the SecretFiles folder, select All Users, and select Deny. Click the OK button to add the new rule.

Figure 23.13. Creating authorization rules.

Using a Different Database with the SqlRoleProvider

By default, the SqlRoleProvider uses the same Microsoft SQL Server Express database as ASP.NET Membership: the AspNetDB.mdf database. This database is created for you automatically in your application’s root App_Data folder.

If you want to store role information in another Microsoft SQL Server database, then you must perform the following two configuration steps:

1. Configure the database so that it contains the necessary database objects.

2. Configure your application to use the new database.

Before you can store role information in a database, you need to add the necessary tables and stored procedures to the database. The easiest way to add these objects is to use the aspnet_regsql command-line tool. This tool is located in the following folder:

C:WINDOWSMicrosoft.NETFrameworkv2.0.50727

Note

You don’t need to navigate to the Microsoft.NET folder when you open the SDK Command Prompt.

If you execute aspnet_regsql without any parameters, then the ASP.NET SQL Server Setup Wizard opens (see Figure 23.14). You can use this wizard to connect to a database and add the necessary database objects automatically.

Figure 23.14. Using the SQL Server Setup Wizard.

Alternatively, you can set up a database by executing the following two SQL batch files.

• InstallCommon.sql

• InstallRoles.sql

These batch files are located in the same folder as the aspnet_regsql tool.

After you set up your database, you need to configure a new SqlRoleProvider that includes the proper connection string for your database. The web configuration file in Listing 23.29 configures a new provider named MyRoleProvider that connects to a database named MyDatabase located on a server named MyServer.

Example 23.29. Web.Config

<configuration>
  <connectionStrings>
    <add
      name="MyConnection"
      connectionString="Data Source=MyServer;Integrated Security=True;Initial Catalog=MyDatabase"/>
  </connectionStrings>

  <system.web>
      <authentication mode="Forms" />

      <roleManager enabled="true" defaultProvider="MyRoleProvider">
        <providers>
          <add
            name="MyRoleProvider"
            type="System.Web.Security.SqlRoleProvider"
            connectionStringName="MyConnection"/>
        </providers>
      </roleManager>

  </system.web>
</configuration>

The configuration file in Listing 23.29 creates a new default RoleManager named MyRoleProvider. Notice that the MyRoleProvider provider includes a connectionStringName attribute that points to the MyConnection connection.

When you use the WindowsTokenRoleProvider, roles correspond to Microsoft Windows groups. You must enable Windows authentication when using the WindowsTokenRoleProvider. You cannot use Forms authentication or ASP.NET Membership with the WindowsTokenRoleProvider.

The configuration file in Listing 23.30 configures the WindowsTokenRoleProvider as the default provider.

<configuration>
    <system.web>
      <authentication mode="Windows" />

      <roleManager enabled="true" defaultProvider="MyRoleProvider">
        <providers>
          <add
            name="MyRoleProvider"
            type="System.Web.Security.WindowsTokenRoleProvider" />
        </providers>
      </roleManager>

    </system.web>
</configuration>

The page in Listing 23.31 contains a LoginView control. The LoginView control displays different content to the members of the Windows Administrators group than it displays to everyone else (see Figure 23.15).

Figure 23.15. Displaying different content to members of the Windows Administrators group.

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>Show Windows Roles</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>

    <asp:LoginView
        id="LoginView1"
        Runat="server">
        <RoleGroups>
        <asp:RoleGroup Roles="BUILTINAdministrators">
            <ContentTemplate>
            <h1>Welcome Administrator!</h1>
            </ContentTemplate>
        </asp:RoleGroup>
        </RoleGroups>
        <LoggedInTemplate>
            <h1>Welcome Average User!</h1>
        </LoggedInTemplate>
    </asp:LoginView>

    </div>
    </form>
</body>
</html>

If you request the page in Listing 23.31 after enabling the WindowsTokenRoleProvider, then you see the content displayed by the LoginView control only when you are a member of the Windows Administrators group.

Authorization Manager (AzMan) is a component of Windows Server 2003. You can use AzMan to define roles, tasks, and operations.

AzMan supports more features than the authorization framework included in the ASP.NET Framework. For example, AzMan supports role inheritance, which enables you to easily define new roles based on existing roles.

AzMan can store role information in three different ways. You can create an authorization store by using an XML file, by using Active Directory, or by using Active Directory Application Mode (ADAM).

Before you use AzMan with the ASP.NET Framework, you need to create an authorization store. Role information is stored in an XML file local to the application. Follow these steps:

After you complete these steps, a new XML file is added to your application. This XML file contains the authorization store.

Next, you need to configure the ASP.NET Role Manager to use the authorization store. The web configuration file in Listing 23.32 uses the WebRoles.xml authorization store.

<configuration>
  <connectionStrings>
    <add
      name="AZConnection"
      connectionString="msxml://~/App_Data/WebRoles.xml"/>
  </connectionStrings>

  <system.web>
    <authentication mode="Windows" />

    <roleManager enabled="true" defaultProvider="MyRoleProvider">
      <providers>
        <add
          name="MyRoleProvider"
          type="System.Web.Security.AuthorizationStoreRoleProvider"
          connectionStringName="AZConnection"
          applicationName="WebRoles"
            />
      </providers>
    </roleManager>

  </system.web>
</configuration>

You should notice a couple of things about the configuration file in Listing 23.32. First, notice that the connection string uses the prefix msxml: to indicate that the connection string represents a connection to an XML file.

Second, notice that the AuthorizationStoreRoleProvider includes an applicationName attribute. This attribute must contain the name of the AzMan application that you created in the preceding steps.

After you complete these configuration steps, you can use the AzMan just as you do the default SqlMembershipProvider. You can define new roles by using either the Web Site Administration Tool or the Authorization Manager interface (see Figure 23.17).

Figure 23.17. Creating a new role definition with Authorization Manager.

To improve your application’s performance, you can cache user roles in a browser cookie. That way, the Role Manager does not have to perform a query against the Role provider each and every time a user visits a page.

Caching roles in cookies is disabled by default. You can enable this feature with the web configuration file in Listing 23.33.

<configuration>
    <system.web>
      <roleManager
        enabled="true"
        cacheRolesInCookie="true"
        createPersistentCookie="true" />
    </system.web>
</configuration>

The web configuration in Listing 23.33 enables role caching. Furthermore, it causes the roles to be cached in a persistent cookie rather than a session cookie.

You can set a number of attributes that are related to the roles cookie:

The Roles class exposes the main application programming interface for manipulating roles. If you need to create roles programmatically, delete roles, or assign users to roles, then you use the methods of the Roles class.

The Roles class includes the following methods:

The page in Listing 23.34 illustrates how you can use the methods of the Roles class. The Page_Load() method creates two roles named Sales and Managers (if they don’t already exist). Next, it assigns the current user to both roles. The body of the page contains a GridView that displays all the roles to which the current user belongs (see Figure 23.18).

Figure 23.18. Displaying a user’s roles.

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
    void Page_Load()
    {
        // If user is not authenticated, redirect to Login page
        if (!Request.IsAuthenticated)
        {
            FormsAuthentication.RedirectToLoginPage();
            Response.End();
        }
        // Create two roles
        if (!Roles.RoleExists("Managers"))
            Roles.CreateRole("Managers");
        if (!Roles.RoleExists("Sales"))
            Roles.CreateRole("Sales");

        // Add current user to both roles
        if (!Roles.IsUserInRole("Managers"))
            Roles.AddUserToRole(User.Identity.Name, "Managers");
        if (!Roles.IsUserInRole("Sales"))
            Roles.AddUserToRole(User.Identity.Name, "Sales");
    }
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>Show Roles</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>

    <h1>Your Roles</h1>

    <asp:GridView
        id="grdRoles"
        DataSourceID="srcRoles"
        EmptyDataText="You are not a member of any roles"
        GridLines="none"
        Runat="server" />

    <asp:ObjectDataSource
        id="srcRoles"
        TypeName="System.Web.Security.Roles"
        SelectMethod="GetRolesForUser"
        Runat="server" />

    </div>
    </form>
</body>
</html>