Implementing custom password policy using ASP.NET Identity

We recently released the 2.0.0-alpha1 version of ASP.NET Identity. Learn more here: http://blogs.msdn.com/b/webdev/archive/2013/12/20/announcing-preview-of-microsoft-aspnet-identity-2-0-0-alpha1.aspx

To provide a more secure user experience for the application, you might want to customize the password complexity policy. This might include minimum password length, mandatory special characters in the password, disallowing recently used passwords, etc. More information on password policy can be found here. By default ASP.NET Identity enforces a minimum password length of 6 characters. This article provides a simple walkthrough that shows how to add a few more password policies to an application.

We will create an application using Visual Studio 2013, update the Identity assemblies to 2.0.0-alpha1, and then add code to enforce the following password policies:

i. Change the default password length requirement from 6 characters to 10 characters.

ii. The password should have at least one number and one special character.

iii. The user cannot reuse any of the last 5 previous passwords.

Lastly we’ll run the application to verify if these policies have been successfully enforced.

Create application

In Visual Studio 2013 RTM create a new 4.5 ASP.NET Web application. Choose MVC.

Right-click the project and select ‘Manage Nuget Packages’. Go to the ‘Update’ section and update the Identity packages to 2.0.0-alpha1

Let’s quickly look at the user creation flow in the application. This will help us outline the password validation steps in the Identity system. Under the Controllers folder, the AccountController has actions for user account management.

The Account controller uses an instance of UserManager class which is defined in the Identity framework. This takes a UserStore class which has persistence-specific API for user management. In our case it uses Entity Framework.
The Register post method creates a new user. The call to CreateAsync in turn calls the ‘ValidateAsync’ method on the PasswordValidator property to validate the supplied password.

var user = new ApplicationUser() { UserName = model.UserName };
  
var result = await UserManager.CreateAsync(user, model.Password);
  
if (result.Succeeded)
{
await SignInAsync(user, isPersistent: false);
  
return RedirectToAction("Index", "Home");
}
  
 

On success the user is signed in.

Similarly, password validation is called when the user tries to change the password. This can be observed in the ‘Manage’ post action.

Policy 1: Change the default password length requirement from 6 characters to 10 characters.

By default the PasswordValidator property in UserManager is set to the MinimumLengthValidator class which validates that the password length is at least 6. This value can be changed when instantiating a UserManager object.

The minimum password length value can be changed in the AccountController in the constructor where the UserManager is instantiated or at a global level by defining a separate class derived from UserManager. The second approach is possible by extending the UserManager class in the application and setting the property. Under the IdentityExtensions folder, create a new class ApplicationUserManager which extends from UserManager<ApplicationUser>.

public class ApplicationUserManager : UserManager<ApplicationUser>
{
        public ApplicationUserManager(): base(new UserStore<ApplicationUser>(new ApplicationDbContext()))
        {
              PasswordValidator = new MinimumLengthValidator (10);
        }
}


The UserManager class takes an IUserStore class which is a persistence-specific implementation of user management APIs. Since the UserStore class is EntityFramework-specific, we need to pass in the DbContext object. This call is essentially the same as defined in the constructor of the AccountController class.

The additional advantage of defining the custom ApplicationUserManager class is that we can override methods defined in the UserManager class, which we will be doing for the subsequent password policies.

We then need to hook in the ApplicationUserManager class defined in the above step in the AccountController. Change the constructor and the UserManager Property in the AccountController as below.

public AccountController() : this(new ApplicationUserManager())
        {
        }
  
        public AccountController(ApplicationUserManager userManager)
        {
            UserManager = userManager;
        }
        public ApplicationUserManager UserManager { get; private set; }

This way we are making the AccountController use the custom UserManager. This enables you to do additional customization while keeping the other code in the controller intact.

Run the application and try to register a local user. If the password is less than 10 characters in length, you’ll get the following error message.

Policy 2: Passwords should have at least one special character and one numeral

As mentioned in the previous section, the PasswordValidator property in the UserManager class validates the length of the password to 6 characters. Though we can change the ‘RequiredLength’, to add additional checks we would need to extend the behavior through a new class. We can add new password validators by creating a class that implements the IIdentityValidator interface and adding the validations as needed. In our case we want to check for special characters and numbers in the supplied password along with checking if it is of minimum length in the ‘ValidateAsync’ method.

Create a new folder under the root project called IdentityExtensions. Add a new class CustomPasswordValidator implementing IIdentityValidator<string> since password is of type string.

public class CustomPasswordValidator : IIdentityValidator<string>
  
{
  
public int RequiredLength { get; set; }
  
public CustomPasswordValidator(int length)
  
{
  
RequiredLength = length;
  
}
  
public Task<IdentityResult> ValidateAsync(string item)
  
{
  
if (String.IsNullOrEmpty(item) || item.Length < RequiredLength)
  
{
  
return Task.FromResult(IdentityResult.Failed(String.Format("Password should be of length {0}",RequiredLength)));
  
}
  
string pattern = @"^(?=.*[0-9])(?=.*[!@#$%^&*])[0-9a-zA-Z!@#$%^&*0-9]{10,}$";
  
if (!Regex.IsMatch(item, pattern))
  
{
  
return Task.FromResult(IdentityResult.Failed("Password should have one numeral and one special character"));
  
}
  
return Task.FromResult(IdentityResult.Success);
  
}

In the ValidateAsync method, we check if the password is of the specified length. Then we use a regular expression to verify if the password has a special character and a numeric character. Note: The regular expression is not tested fully and should be used as a sample only.

Next we need to set this validator in the PasswordValidator property of the UserManager. Navigate to the ApplicationUserManager created earlier and change the PasswordValidator property from MinimumLengthValidator to CustomPasswordValidator.

public class ApplicationUserManager : UserManager<ApplicationUser[PR6] >
  
{
  
public ApplicationUserManager()
  
: base(new UserStore<ApplicationUser(new ApplicationDbContext()))
  
{
  
PasswordValidator = new CustomPasswordValidator(10);
  
}
  
}

No change is needed in the AccountController class. Now try to create a user with password that does not meet the requirements. An error message is displayed as shown below.

Policy 3: The user cannot reuse the last five previous passwords

When existing users change or reset their password, we can check if they are trying to reuse an old password. This is not done by default since the Identity system does not store the password history per user. We can do this in the application by creating a separate table to store password history per user and then retrieve the password hashes whenever the user tries to reset or change password.

Open the IdentityModels.cs file in the editor. Create a new class called ‘PreviousPassword’ as shown below.

public class PreviousPassword
  
{
  
public PreviousPassword()
  
{
  
CreateDate = DateTimeOffset.Now;
  
}
  
[Key, Column(Order = 0)]
  
public string PasswordHash { get; set; }
  
public DateTimeOffset CreateDate { get; set; }
  
[Key, Column(Order = 1)]
  
public string UserId { get; set; }
  
public virtual ApplicationUser User { get; set; }
  
}

In this class, the ‘Password’ field holds the hashed password for the user referenced by the field ‘UserId’. The ‘CreateDate’ holds the timestamp when the password was added. This can be used to filter the password history to get the last 5 passwords or the latest password.

EntityFramework code first creates a corresponding table called ’PreviousPasswords’ with the ‘UserId’ and the ‘Password’ field forming the composite primary key. You can read more about code first conventions here.

Add a property on the user class ‘ApplicationUser’ to hold a list of previous passwords

public class ApplicationUser : IdentityUser
    {
        public ApplicationUser()
            : base()
        {
            PreviousUserPasswords = new List<PreviousPassword>();
        }
        public virtual IList<PreviousPassword> PreviousUserPasswords { get; set; }
  
    }

As explained in Policy 1, the UserStore class holds the persistence-specific methods for user operations. We need to store the password hash in the history table when the user is created for the first time. Since the UserStore does not define such a method separately, we need to define an override for the existing method to store the password history. This can be done by extending the existing UserStore class and override the existing methods to store the passwords. This is then hooked in the ApplicationUserManager. Add a new class under the IdentityExtensions folder.

public class ApplicationUserStore : UserStore<ApplicationUser>
  
{
  
public ApplicationUserStore(DbContext context)
  
: base(context)
  
{
  
}
  
public override async Task CreateAsync(ApplicationUser user)
  
{
  
await base.CreateAsync(user);
  
await AddToPreviousPasswordsAsync(user, user.PasswordHash);
  
}
  
public Task AddToPreviousPasswordsAsync(ApplicationUser user, string password)
  
{
  
user.PreviousUserPasswords.Add(new PreviousPassword() { UserId = user.Id, PasswordHash = password });
  
return UpdateAsync(user);
  
}
  
}

The ‘AddToPreviousPasswordsAsync’ method stores the password in the ‘PreviousPasswords’ table separately

We need to call the above method whenever user tries to change or reset a password. The API’s to do this are defined in the UserManager class. We need to override them and include the above password history method call. We can do this by overriding the ChangePassword and ResetPassword methods in the ApplicationUserManager class defined in the Policy 2.

public class ApplicationUserManager : UserManager<ApplicationUser>
  
{
  
private const int PASSWORD_HISTORY_LIMIT = 5;
  
public ApplicationUserManager()
  
: base(new ApplicationUserStore(new ApplicationDbContext()))
  
 {
  
PasswordValidator = new CustomPasswordValidator(10);
  
 }
  
public override async Task<IdentityResult> ChangePasswordAsync(string userId, string currentPassword, string newPassword)
  
{
  
if (await IsPreviousPassword(userId, newPassword))
  
{
  
return await Task.FromResult(IdentityResult.Failed("Cannot reuse old password"));
  
}
  
var result = await base.ChangePasswordAsync(userId, currentPassword, newPassword);
  
if (result.Succeeded)
  
{
  
var store = Store as ApplicationUserStore;
  
await store.AddToPreviousPasswordsAsync(await FindByIdAsync(userId), PasswordHasher.HashPassword(newPassword));
  
}
  
return result;
  
}
  
public override async Task<IdentityResult> ResetPasswordAsync(string userId, string token, string newPassword)
  
{
  
if (await IsPreviousPassword(userId, newPassword))
  
{
  
return await Task.FromResult(IdentityResult.Failed("Cannot reuse old password"));
  
}
  
var result = await base.ResetPasswordAsync(userId, token, newPassword);
  
if (result.Succeeded)
  
{
  
var store = Store as ApplicationUserStore;
  
await store.AddToPreviousPasswordsAsync(await FindByIdAsync(userId), PasswordHasher.HashPassword(newPassword));
  
}
  
return result;
  
}
  
private async Task<bool> IsPreviousPassword(string userId, string newPassword)
  
{
  
var user = await FindByIdAsync(userId);
  
if (user.PreviousUserPasswords.OrderByDescending(x => x.CreateDate).
  
Select(x => x.PasswordHash).Take(PASSWORD_HISTORY_LIMIT).Where(x => PasswordHasher.VerifyHashedPassword(x, newPassword) != PasswordVerificationResult.Failed
  
).Any())
  
{
  
return true;
  
}
  
return false;
  
}
  
}

The ‘PASSWORD_HISTORY_LIMIT’ field is used to get the last ‘X’ number of passwords from the table. Notice we hooked in the ApplicationUserStore in the constructor to get the new method to store the password. Whenever the user changes the password, we validate it against the last 5 passwords stored in the table and return true/false based on the validation.

Create a local user and go to Manage page. Try to change the password using same password when the user is created. You see a message as shown below.

Code Sample

The sample project Identity-PasswordPolicy is checked into http://aspnet.codeplex.com/SourceControl/latest under Samples/Identity.

Summary

This post shows how you can extend the ASP.NET Identity Validation system to enforce different types of password policies for the users of your application. The example uses the MVC template, but the same changes can be applied to a web forms application.

I hope you have found this walkthrough useful. If you have any questions around ASP.NET Identity or find issues, please feel free to open bugs on the Identity Codeplex site, https://aspnetidentity.codeplex.com/ , leave comments on this blog, or ask questions on asp.net/forums or StackOverflow(tag: aspnet-identity). I can also be reached on twitter (@suhasbjoshi).