Using the Login Control

Using the `Login` Control

The Login control renders a standard user login form. By default, the Login control uses ASP.NET Membership to authenticate users. However, as you'll see in a moment, you can customize how the Login control authenticates users.

The Login control supports a large number of properties that enable you to customize the appearance and behavior of the control (too many properties to list here). The page in Listing 20.6 illustrates how you can modify several of the Login control's properties to customize the form rendered by the control (see Figure 20.3).

Figure 20.3. Customizing the `Login` form.

Listing 20.6. `ShowLogin.aspx`

<%@ Page Language="VB" %> <!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  runat="server">     <style type="text/css">         .login         {             width:250px;             font:14px Verdana,Sans-Serif;             background-color:lightblue;             border:solid 3px black;             padding:4px;         }         .login_title         {             background-color:darkblue;             color:white;             font-weight:bold;         }         .login_instructions         {             font-size:12px;             text-align:left;             padding:10px;         }         .login_button         {             border:solid 1px black;             padding:3px;         }     </style>     <title>Show Login</title> </head> <body>     <form  runat="server">     <div>     <asp:Login                  InstructionText="Please log in before             accessing the premium section of our Website."         TitleText="Log In"         TextLayout="TextOnTop"         LoginButtonText="Log In"         DisplayRememberMe="false"         Css         TitleTextStyle-Css         InstructionTextStyle-Css         LoginButtonStyle-Css         Runat="server" />     </div>     </form> </body> </html>

The page in Listing 20.6 uses Cascading Style Sheets to change the appearance of the login form rendered by the Login control. By taking advantage of Cascading Style Sheets, you can customize the appearance of the Login control in any way that you can imagine.

Note

For the complete list of properties supported by the Login control, see the Microsoft .NET Framework SDK 2.0 documentation.

Automatically Redirecting a User to the Referring Page

If you request a page that you are not authorized to view, then the ASP.NET Framework automatically redirects you to the Login.aspx page. After you log in successfully, you are redirected back to the original page that you requested.

When you are redirected to the Login.aspx page, a query string parameter named ReturnUrl is automatically added to the page request. This query string parameter contains the path of the page that you originally requested. The Login control uses the ReturnUrl parameter when redirecting you back to the original page.

You need to be aware of two special circumstances. First, if you request the Login.aspx page directly, then a ReturnUrl parameter is not passed to the Login.aspx page. In that case, after you successfully log in, you are redirected to the Default.aspx page.

Second, if you add the Login control to a page other than the Login.aspx page, then the ReturnUrl query string parameter is ignored. In this case, you need to set the Login control's DestinationPageUrl property. When you successfully log in, you are redirected to the URL represented by this property. If you don't supply a value for the DestinationPageUrl property, the same page is reloaded.

Automatically Hiding the `Login` Control from Authenticated Users

Some websites display a login form at the top of every page. That way, registered users can log in at any time to view additional content. The easiest way to add a Login control to all the pages in an application is to take advantage of Master Pages. If you add a Login control to a Master Page, then the Login control is included in every content page that uses the Master Page.

You can change the layout of the Login control by modifying the Login control's Orientation property. If you set this property to the value Horizontal, then the Username and Password text boxes are rendered in the same row.

If you include a Login control in all your pages, you should also modify the Login control's VisibleWhenLoggedIn property. If you set this property to the value False, then the Login control is not displayed when a user has already authenticated.

For example, the Master Page in Listing 20.7 contains a Login control that has both its Orientation and VisibleWhenLoggedIn properties set.

Listing 20.7. `LoginMaster.master`

<%@ Master Language="VB" %> <!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  runat="server">     <style type="text/css">         html         {             background-color:silver;         }         .content         {             margin:auto;             width:650px;             border:solid 1px black;             background-color:white;             padding:10px;         }         .login         {             font:10px Arial,Sans-Serif;             margin-left:auto;         }         .login input         {             font:10px Arial,Sans-Serif;         }     </style>     <title>My Website</title> </head> <body>     <form  runat="server">     <div >     <asp:Login                  Orientation="Horizontal"         VisibleWhenLoggedIn="false"         DisplayRememberMe="false"         TitleText=""         Css         Runat="server" />         <hr />         <asp:contentplaceholder                          runat="server">         </asp:contentplaceholder>     </div>     </form> </body> </html>

The content page in Listing 20.8 uses the Master Page in Listing 20.7 (see Figure 20.4). When you open the page in a browser, the Login control is hidden after you successfully log in to the application.

Figure 20.4. Adding the `Login` control to a Master Page.

Listing 20.8. `LoginContent.aspx`

<%@ Page Language="VB" MasterPageFile="~/LoginMaster.master" %> <asp:Content          ContentPlaceHolder     Runat="Server">     <h1>Welcome to our Website!</h1> </asp:Content>

Using a Template with the `Login` Control

If you need to completely customize the appearance of the Login control, then you can use a template. The Login control includes a LayoutTemplate property that enables you to customize the layout of the controls rendered by the Login control.

When you create a Layout template, you can add controls to the template that have the following IDs:

UserName
Password
RememberMe
FailureText

You also need to add a Button control that includes a CommandName property with the value Login.

The page in Listing 20.9 illustrates how you can use a LayoutTemplate to customize the appearance of the Login control (see Figure 20.5).

Figure 20.5. Using a template with the `Login` control.

Listing 20.9. `LoginTemplate.aspx`

<%@ Page Language="VB" %> <!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  runat="server">     <style type="text/css">         .loginError         {             color:red;             font:bold 14px Arial,Sans-Serif;         }     </style>     <title>Login Template</title> </head> <body>     <form  runat="server">     <div>     <asp:Login                  Runat="server">         <LayoutTemplate>         <asp:Label                          EnableViewState="false"             Css             Runat="server" />         <br />         <asp:Label                          AssociatedControl             Text="User Name:"             Runat="server" />         <br />         <asp:TextBox                          Runat="server" />         <br /><br />         <asp:Label                          AssociatedControl             Text="Password:"             Runat="server" />         <br />         <asp:TextBox                          TextMode="Password"             Runat="server" />         <br /><br />         <asp:Button                          Text="Login"             CommandName="Login"             Runat="server" />         </LayoutTemplate>     </asp:Login>     </div>     </form> </body> </html>

Web Standards Note

The Login control renders an HTML table for layout even when you use a LayoutTemplate.

Performing Custom Authentication with the `Login` Control

By default, the Login control uses ASP.NET Membership to authenticate a username and password. If you need to change this default behavior, then you can handle the Login control's Authenticate event.

Imagine, for example, that you are building a simple application and you want to store a list of usernames and passwords in the web configuration file. The web configuration file in Listing 20.10 contains the credentials for two users named Bill and Ted.

Listing 20.10. `Web.Config`

<?xml version="1.0" encoding="utf-8"?> <configuration>   <system.web>     <authentication mode="Forms">       <forms>         <credentials passwordFormat="Clear">           <user name="Bill" password="secret" />           <user name="Ted" password="secret" />         </credentials>       </forms>     </authentication>   </system.web> </configuration>

The page in Listing 20.11 contains a Login control that authenticates users against the list of usernames and passwords stored in the web configuration file.

Listing 20.11. `LoginCustom.aspx`

<%@ Page Language="VB" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <script runat="server">     Sub Login1_Authenticate(ByVal sender As Object, ByVal e As AuthenticateEventArgs)         Dim userName As String = Login1.UserName         Dim password As String = Login1.Password         e.Authenticated = FormsAuthentication.Authenticate(userName, password)     End Sub </script> <html xmlns="http://www.w3.org/1999/xhtml" > <head  runat="server">     <title>Login Custom</title> </head> <body>     <form  runat="server">     <div>     <asp:Login                  OnAuthenticate="Login1_Authenticate"         Runat="server" />     </div>     </form> </body> </html>

Notice that the page in Listing 20.11 includes a method that handles the Login control's Authenticate event. The second parameter passed to the Authenticate event handler is an instance of the AuthenticateEventArgs class. This class includes the following property:

Authenticated

If you assign the value true to this property, then the Login control authenticates the user.

In Listing 20.11, the FormsAuthentication.Authenticate() method is called to check for a username and password in the web configuration file that matches the username and password entered into the login form. The value returned from this method is assigned to the AuthenticateEventArgs.Authenticated property.