Add Logon Security to Your ASP.NET Website

ASP.NET Web Pages (aka Razor) lets you build logon capabilities into any website with relative ease. However, it's not necessarily obvious how to go about doing it. The ASP.NET Web Pages tutorial does include a chapter about how to add security to a website by using membership (logon) capability. But the chapter doesn't show you how to add security to an existing site.

What I want to show you is an absolutely bare-bones way to add logon to your site, and how to do it all manually from scratch. I'll try to keep the discussion straightforward, and I want to emphasize the use of simple APIs to implement security. Along the way, I'll maintain this three-pronged approach to implementing security for each procedure:

A Little Background

Razor has an infrastructure for security and logon that automates much of the process. For starters, membership information (usernames, passwords, and so on) are stored in a database in your site. Razor includes a membership provider, a component that handles the details of managing this database. You never have to think about how or where the logon information is being handled. For this article, I'll assume that you'll be happy with whatever the membership provider is doing under the hood, although I will note a few details about the database.

Razor also includes the WebSecurity helper and the Membership and Roles objects. Among them, these components include the methods you need to manage membership. These include a create-user method, a login method, a logout method, and so on.

This next exercise covers just a few of these basic capabilities. I'll show you how to perform the following tasks to implement security:

Figure 1 shows the site layout.

Figure 1: Simple membership site structure

If you've ever worked with an ASP.NET membership tutorial, these tasks will be familiar because they are, essentially, the things you do with any membership system. The difference here is that I will, as noted, get this up and running in the sparsest way possible.

Initialize the Membership System

Before you use the membership system, the system must be initialized. Technically, you can do this at any time, as long as you do it before you start interacting with the system. In practice, you should initialize the membership system as soon as the application starts, which typically means that you do this in the site's _AppStart.cshtml file. Here is the complete code for the _AppStart.cshtml page:

@{    WebSecurity.InitializeDatabaseConnection("TestMembership", "UserProfile",     "UserId", "Email", true);}

Must do

@{  WebSecurity.InitializeDatabaseConnection("",     "UserProfile", "UserId", "Email", true);}

For the nameOfDatabase placeholder, use the name of the database that you just created. Make sure that the name is in quotation marks; that is, pass the name as a string. Important point: The database you refer to in the initialization method must already exist, even if the database is empty. Details about these values will follow.

Do in a real application

Initialization Values

In the example, the code passes the following values to the initialization method:

Given the circumstances here (simplest possible membership), you needn't worry about these values. Just copy what you see in the example, and substitute your own database name. For more information about these values, see the sidebar "The Purpose of Initialization Values," at the end of this article.

Create a Home Page

The home page is what users see when they first visit the site. If the user has not yet logged on, the home page displays a logon link (see Figure 2).

Figure 2: Simple membership home page

If the user has already logged on, the page displays the username and a logout link (see Figure 3).

Figure 3: Simple membership home page: logged on

Figure 4 shows the complete code for the Home.cshtml page.

                  Home Page    This is the home page.      @if(WebSecurity.IsAuthenticated){      @:Welcome, @WebSecurity.CurrentUserName      @:Log out  }  else{      @:Log in |      @:Register  }            Members area          Manage Roles (must be logged in as the Admin user MikeP)      

Must do

Nice to do

@if(WebSecurity.IsAuthenticated){  Welcome, @WebSecurity.CurrentUserName  Log out}else{  Log in |  Register}

Do in a real application

Create a Register Page

A simple registration (register) page contains text boxes for the username (which can be an email address) and for the password. Typically, you make users enter the password two times because they can't see what they're typing. Figure 5 shows the registration page.

Figure 5: Registration page

Figure 6 shows the complete code for the Register.cshtml page.

@{  var username = "";  var password = "";  var confirmPassword = "";  var errorMessage = "";  if(!IsPost){    if(WebSecurity.IsAuthenticated){  errorMessage = String.Format("You are already logged in. (User name: {0})", WebSecurity.CurrentUserName);    }  }   if(IsPost){    username = Request["username"];    password = Request["password"];    confirmPassword = Request["confirmPassword"];if(username.IsEmpty() || password.IsEmpty()){    errorMessage = "All fields are required!";    }    else{  if(password != confirmPassword){    errorMessage = "Passwords don't match.";  }  else {    if(WebSecurity.UserExists(username)){      errorMessage = String.Format("User '{0}' already exists.", username);    }    else{      WebSecurity.CreateUserAndAccount(username,password,null,false);      WebSecurity.Login(username, password, true);      errorMessage = String.Format("{0} created.", username);    }  }    }  }}                  Register          @if(errorMessage != ""){        @Html.Raw(errorMessage)    }          Username (email):
            Password:
                Confirm password:
                               Log out    
    Home          

Must do

if(WebSecurity.UserExists(username)){    errorMessage = String.Format("User '{0}' already exists.",    username);}else{    WebSecurity.CreateUserAndAccount(username, password,    null, false);    WebSecurity.Login(username, password, true);    errorMessage = String.Format("{0} created.", username);}

Nice to do

if(WebSecurity.IsAuthenticated){   errorMessage = String.Format("You are already logged in." +   " (User name: {0})", WebSecurity.CurrentUserName);}

Do in a real application

Create a Logon Page

The login page lets the user enter credentials. Figure 7 shows the logon page.

Figure 7: Logon page

Figure 8 shows the complete code for the Login.cshtml page.

@{    var username = "";    var password = "";    var errorMessage = "";     if(IsPost){    username = Request["username"];    password = Request["password"];    if(WebSecurity.Login(username,password,true)){        Response.Redirect("~/Home");    }    else    {        errorMessage = "Login was not successful.";    }    }}                        Login            @if(WebSecurity.IsAuthenticated){        You are currently logged in as @WebSecurity.CurrentUserName.          Log out                }              Username:
                            Password:
                                                   No user name? Register      Return to home page                         @if(errorMessage != ""){        @errorMessage        }       

Must do

if(IsPost){  username = Request["username"];  password = Request["password"];  if(WebSecurity.Login(username,password,true))    {  Response.Redirect("~/Home");    }  else  {     errorMessage = "Login was not successful.";  }}

Nice to do

@if(WebSecurity.IsAuthenticated){  You are currently logged in as @WebSecurity.CurrentUserName.    Log out }

Do in a real application

Membership.MinRequiredNonAlphanumericCharactersMembership.MinRequiredPasswordLengthMembership.PasswordStrengthRegularExpression

Membership.MaxInvalidPasswordAttemptsWebSecurity.GetPasswordFailuresSinceLastSuccess

Typically, you send users to an "account locked" page after a certain number of failed login attempts.

Create a Logout Page

The logout page logs out the user. Under the covers, this page removes the browser cookie on the user's computer that lets ASP.NET know that the user is authenticated. Figure 9 shows the logout page.

Figure 9: Logout page

Figure 10 shows the complete code for the Logout.cshtml page.

@{  WebSecurity.Logout();}                    Logout    You are now logged out!    Return to home page    

Must do

Nice to do

Do in a real application

Protect Content

Protected content can be viewed only by people who are logged in. Typically, you put pages into a folder that's guarded by code that lets users through only if they're logged in (authenticated). Protection does not depend on what username is used. The only criteria here is that the user be logged in. Figure 11 shows a subfolder in a site that can contain protected content.

Figure 11: Site structure listing protected content

Here is the complete code for the _PageStart.cshtml page:

@{    Response.CacheControl = "no-cache";if (!WebSecurity.IsAuthenticated) {    Response.Redirect("~/Login");    }}

Must do

@if (!WebSecurity.IsAuthenticated){    Response.Redirect("~/Login");}

Do in a real application

Create a Page to Manage Roles

Roles are a convenient way to group users. This is handy if you want to grant different logged-on users access to different pages. The following conditions represent a typical example in which roles are used:

There are no built-in roles; a role is just a name that you create. You can think of it as a tag that you assign to a username. You can then look for that tag as a way to determine whether you'll allow someone access to pages.

Typically, you don't let users manage roles themselves. Unlike the other pages that are covered in this article, the page that you'll create here is one that should be available only to an administrator or to a super user (e.g., you). The page for managing roles should be protected so that only users in some sort of admin role can access it. In this example, the page is assumed to be in an administrator folder that you'll protect. (Because there's a chicken-and-egg problem with this scenario, you should protect the folder only after you've added your own username to the administrator role.)

The page that I describe here is just one of many methods you can use to manage roles. However, this page does illustrate the fundamental tasks in managing roles, which include creating and deleting roles, and adding users to and removing users from roles. Figure 12 shows what this page looks like:

Figure 12: SimpleMembership_ManageRoles

Figure 13 shows the complete code for the ManageRoles.cshtml page.

Notice that in this case, there's no "must do" category. This is because there's no one way to manage roles. For example, you could do everything by directly editing the database in WebMatrix. So this method simply shows some ways in which you can use APIs to manage roles.

Nice to do

Everything that's listed in this "Nice to do" section happens in this role management page. I'll break down the procedure into separate tasks because this page is a little more complex than the other pages.

Display existing roles (and users in roles)

  @foreach(var role in Roles.GetAllRoles())  {    @role    @foreach(var user in Roles.GetUsersInRole(role))    {  @user    }         }

Create and delete roles

// Create new roleif(!Request["buttonCreateRole"].IsEmpty()){  roleName=Request["textRoleName"];  if(!Roles.RoleExists(roleName) && !roleName.IsEmpty())  {    Roles.CreateRole(roleName);  }}

// Delete roleif(!Request["buttonDeleteRole"].IsEmpty()){  roleName=Request["textRoleName"];  if(Roles.GetUsersInRole(roleName).Length == 0 &&    !roleName.IsEmpty())  {    // true means throw if any users are in this role    Roles.DeleteRole(roleName, true);  }}

In this case, you don't have to see whether the role exists. If you call Roles.DeleteRole for a non-existent role, no error occurs.

Add and delete users in roles

var db = Database.Open("nameOfDatabase ");var selectQueryString =    "SELECT UserId, Email FROM UserProfile";// ...Users:  @foreach(var row in db.Query(selectQueryString))  {    @row.Email  }

(A Membership.GetAllUsers method exists that should do this, but that method doesn't work correctly. Therefore, you have to manually query the database.) Note that you must specify the same name for the database (nameOfDatabase in the previous example) that you used previously when you initialized the membership system.

Roles:  @foreach(var role in Roles.GetAllRoles())  {    @role  }

Add a user to a role

// Add user to roleif(!Request["buttonAddUserToRole"].IsEmpty()){  userName = Request["selectUserName"];  roleName = Request["selectRoleName"];  if(!Roles.IsUserInRole(userName, roleName)){    Roles.AddUsersToRoles(    new [] { userName }.ToArray(),    new [] { roleName }.ToArray()    );  }} // if(buttonAddUserToRole)

Delete a user from a role

·         To delete a user from a role, get the name and role. If the user is in that role, call Roles.RemoveUsersFromRoles. This method takes arrays as arguments. Therefore, just as you did with Roles.AddUsersToRoles, you must put the username and role name into one-element arrays, as follows:

// Delete user from roleif(!Request["buttonDeleteUserFromRole"].IsEmpty()){  userName = Request["selectUserName"];  roleName = Request["selectRoleName"];  if(Roles.IsUserInRole(userName, roleName))  {    Roles.RemoveUsersFromRoles(  new [] { userName }.ToArray(),  new [] { roleName }.ToArray()    );  }} // if(buttonDeleteUseFromRole)

Do in a real application

Protect Content by Role

The point of roles is to protect content so that only users in certain roles can see the content. This is almost exactly like protecting content by limiting it to authenticated users. As noted earlier, you should add this protection after you've added yourself to the admin role. Otherwise, you'll never be able to access this page. Here is the complete code for the _PageStart.cshtml page for roles:

@{    Response.CacheControl = "no-cache";    // Determine whether current user is in Admin role    if (!Roles.IsUserInRole(WebSecurity.CurrentUserName, "Admin")){  Response.SetStatus(HttpStatusCode.Forbidden);    }}

Must do

if (!Roles.IsUserInRole(WebSecurity.CurrentUserName,  "Admin")){  Response.Redirect("~/Home");}

Nice to do

if (!Roles.IsUserInRole(WebSecurity.CurrentUserName,  "Admin")){  Response.SetStatus(HttpStatusCode.Forbidden);}

A Handy Website Security Technique

As you can see, you can set up basic security to your website by adding about eight pages to your site (even fewer if you don't care about roles) and a few pages' worth of code. Most of the work is handled by the membership provider together with a few helpers. The real trick lies is in knowing how to wield the dozen or so methods and properties that do all this work.

Obviously, there are many niceties that you can add to this system, both for the requirements for real-world applications (some of which are mentioned here) and just to make everything look nice. For example, you don't necessarily need a separate logon page. Instead, you can integrate the logon process in your home page. Even so, you'll still work with the APIs that you've seen here and with others that are exposed by the membership system. Considering how much work it might take to implement all this by yourself, the ASP.NET membership system is a very handy feature to get to know.

This article is adapted from a blog entry written and published by the author on his blog (mikepope.com/blog).

Mike Pope ([email protected]) is a technical writer and editor on the Microsoft ASP.NET documentation team. He is a specialist in .NET Framework, ASP.NET, and Visual Basic technologies.