If you create a new website with ASP.NET Core, and select the option for individual user accounts, you’ll end up with a site that uses the Entity Framework implementation of ASP.NET Core Identity.

I’ve found recently that many people believe that this is all there is to identity 🤷‍♂️

The truth is, “identity”, by which I mean the abstractions provided by Microsoft.AspNetCore.Identity, are incredibly flexible and highly pluggable. It’s far easier to plug your existing users database into these abstractions than it ever was to implement a custom Membership provider 🥳

The first thing to remember is that identity is just a set of common abstractions; by default, the rest of the ASP.NET Core framework (MVC etc) understands these abstractions and will use them for authentication and authorisation.

This means that all you need to do is fill in these interfaces to enable out-of-the-box identity management. Let’s work through an example.

dotnet new classlib -o MyCustomIdentityProvider
dotnet add package Microsoft.AspNetCore.Identity
dotnet add package System.Data.SqlClient
dotnet add package Dapper

Our example is going to use a custom SQL Server database, but you could use anything from Postgres to flat XML files to a WCF service contract to get your data.

In this example we’re going to do a minimal implementation, so we’re going to implement the following interfaces:

• Microsoft.AspNetCore.Identity.IUserStore<TUser>
• Microsoft.AspNetCore.Identity.IUserPasswordStore<TUser>
• Microsoft.AspNetCore.Identity.IRoleStore<TRole>
• Microsoft.AspNetCore.Identity.IUserRoleStore<TUser>
• Microsoft.AspNetCore.Identity.IPasswordHasher<TUser>

There are quite a few interfaces in this namespace, but don’t panic – you only need to implement as many as you need to use (for example, if you’re not using 2-factor authentication, there’s no need to implement IUserTwoFactorStore<TUser>).

The other thing to note is that you need to define your user and role objects first. These don’t have to inherit from anything, so long as they’re classes; you’re free to put whatever you want in here. Let’s sketch out a basic example:

public class MyCustomUser
{
  public Guid UserId { get; set; }
  public string Username { get; set; }
}

public class MyCustomRole
{
  public Guid RoleId { get; set; }
  public string RoleName { get; set; }
}

Note that you could go a step further and make these into immutable objects with a bit more effort – I’ve left all properties as get/set for now because it makes this example simpler, but you can go nuts with creating your classes however you want – the power is in your hands!

So far, so simple. Next, we’re going to create a base class for our implementations that can encapsulate data access, and an options object for configuring it:

public class CustomIdentityOptions
{
  public string ConnectionString { get; set; }
}

public abstract class CustomIdentityBase
{
  private readonly string _connectionString;

  protected CustomIdentityBase(IOptions options)
  {
    _connectionString = options.Value.ConnectionString;
  }

  protected SqlConnection CreateConnection()
  {
    var con = new SqlConnection(_connectionString);
    con.Open();
    return con;
  }
}

That’s quite a bit of boilerplate, but it’ll make our lives easier. Next, let’s implement our first interface – IUserStore. To do this, we’ll create a class that extends our base class and implements IUserStore – then, all we need to do is fill in the blanks!

public class CustomUserStore : CustomIdentityBase, IUserStore
{
  public CustomUserStore(IOptions<CustomIdentityOptions> options)
    : base(options)
  {
  }

  public void Dispose()
  {
  }

  /* WHOAH! That's a LOT of methods to fill in! */
}

Don’t despair! Yes, there are now a lot of methods to fill in. This is actually a good thing. By giving you all of these methods, you now have the power to implement identity with as much flexibility as you’re likely to need. Let’s work through some examples:

public async Task CreateAsync(MyCustomUser user, CancellationToken cancellationToken)
{
  using (var con = CreateConnection())
  {
    await con.ExecuteAsync("INSERT INTO Users ( UserId, Username ) VALUES ( @UserId, @Username )", user);
    return IdentityResult.Success;
  }
}

Because the interface is pretty flexible, you can store the user data however you like – in our example, we use ADO.NET and some Dapper magic. Let’s look at some more methods:

public async Task FindByNameAsync(string normalizedUserName, CancellationToken cancellationToken)
{
  using (var con = CreateConnection())
  {
    return await con.QueryFirstAsync(
      "SELECT UserId, Username " +
      "FROM Users " +
      "WHERE Username = @normalizedUserName",
      new { normalizedUserName });
  }
}

Easy, right? You can see that it would be very straightforward to plug in a web service call or a Mongo query in here, depending on your infrastructure.

Next up, some methods that might look a bit odd, because in our example we implement them by loading properties from the user object itself. Take a look:

public Task GetNormalizedUserNameAsync(MyCustomUser user, CancellationToken cancellationToken)
{
  return Task.FromResult(user.Username.ToLowerInvariant());
}

public Task GetUserIdAsync(MyCustomUser user, CancellationToken cancellationToken)
{
  return Task.FromResult(user.UserId.ToString());
}

public Task GetUserNameAsync(MyCustomUser user, CancellationToken cancellationToken)
{
  return Task.FromResult(user.Username);
}

That looks odd, but remember that we might be using a TUser object which doesn’t contain this information, in which case we’d need to look it up from a datastore. Additionally, it helps the framework know which properties of our TUser object represent the user ID and user name without having to restrict us to a specified base class.

Next, we have some other slightly odd methods:

public Task SetNormalizedUserNameAsync(MyCustomUser user, string normalizedName, CancellationToken cancellationToken)
{
  user.Username = normalizedName;
  return Task.CompletedTask;
}

public Task SetUserNameAsync(MyCustomUser user, string userName, CancellationToken cancellationToken)
{
  user.Username = userName;
  return Task.CompletedTask;
}

Again, these look odd because of the structure of our object, but they would also enable you to call remote services for validation, etc.

If we implemented IUserEmailStore<TUser>, then we could start adding logic for storing email addresses and, importantly, storing whether those addresses are confirmed (useful for scenarios where users must confirm their email before being allowed to log in).

---

Phew, we’re getting there! Now let’s move on and add support for password validation. We’re going to make a tweak to our user store class:

public class CustomUserStore :
CustomIdentityBase,
IUserStore,
<strong>IUserPasswordStore</strong>

This will now require us to fill in three new methods. In our example, let’s assume that passwords are stored in a separate table (for security reasons):

public async Task SetPasswordHashAsync(MyCustomUser user, string passwordHash, CancellationToken cancellationToken)
{
  using (var con = CreateConnection())
  {
    // TODO: insert or update logic skipped for brevity
    await con.ExecuteAsync(
      "UPDATE Passwords SET PasswordPash = @passwordHash " +
      "WHERE UserId = @userId",
    new { user.UserId, passwordHash });
  }
}

public async Task GetPasswordHashAsync(MyCustomUser user, CancellationToken cancellationToken)
{
  using (var con = CreateConnection())
  {
    return await con.QuerySingleOrDefaultAsync(
      "SELECT PasswordHash " +
      "FROM Passwords" +
      "WHERE UserId = @userId",
    new { user.UserId });
  }
}

public async Task HasPasswordAsync(MyCustomUser user, CancellationToken cancellationToken)
{
  return !string.IsNullOrEmpty(await GetPasswordHashAsync(user, cancellationToken));
}

Again, you can get the password from wherever you want. Perhaps you want to store passwords in a super-secure database with TDE and massively locked-down access; if so then no problem! Just open a different connection. Passwords in a dedicated key store? Fine, we can do whatever we like in this class.

Speaking of passwords and hashing, our datastore uses BCrypt to hash passwords. Let’s implement a basic hasher so that our users can verify their passwords:

dotnet add package BCrypt.Net-Next

public class CustomPasswordHasher : IPasswordHasher
{
  public string HashPassword(MyCustomUser user, string password)
  {
    return BCrypt.Net.BCrypt.HashPassword(password);
  }

  public PasswordVerificationResult VerifyHashedPassword(MyCustomUser user, string hashedPassword, string providedPassword)
  {
    return BCrypt.Net.BCrypt.Verify(providedPassword, hashedPassword) ?
      PasswordVerificationResult.Success :
      PasswordVerificationResult.Failed;
  }
}

For more on using BCrypt and a far more complete implementation of a custom password hasher, see “Migrating passwords in ASP.NET Core Identity with a custom PasswordHasher” by Andrew Lock.

---

Now we’re going to quickly move on to implement roles – I won’t include all the details because by now this should be pretty familiar. The implementation looks a bit like this:

public class CustomRoleStore : CustomIdentityBase, IRoleStore
{
  public CustomRoleStore(IOptions options)
    : base(options)
  {
  }

/* snip */

  public async Task FindByNameAsync(string normalizedRoleName, CancellationToken cancellationToken)
  {
    using (var con = CreateConnection())
    {
      return await con.QueryFirstOrDefaultAsync(
        "SELECT RoleId, RoleName FROM Roles " +
        "WHERE RoleName = @normalizedRoleName",
      new { normalizedRoleName });
    }
  }

/* snip */
}

Finally, we need to be able to link our users to roles. Go back to our custom user store and add the following line:

public class CustomUserStore :
CustomIdentityBase,
IUserStore,
IUserPasswordStore,
<strong>IUserRoleStore
</strong>

Now we need to implement a bunch of methods, as so:

public async Task AddToRoleAsync(MyCustomUser user, string roleName, CancellationToken cancellationToken)
{
  using (var con = CreateConnection())
  {
    await con.ExecuteAsync(
      "INSERT INTO UserRoles ( RoleId, UserId ) " +
      "SELECT @userId, RoleId " +
      "FROM Roles " +
      "WHERE RoleName = @roleName",
      new { user.UserId, roleName });
  }
}

public async Task GetRolesAsync(MyCustomUser user, CancellationToken cancellationToken)
{
  using (var con = CreateConnection())
  {
    return (await con.QueryAsync(
      "SELECT r.RoleName " +
      "FROM UserRoles AS ur " +
      "JOIN Roles AS r ON ur.RoleId = r.RoleId " +
      "WHERE ur.UserId = @userId",
      new { user.UserId })
    ).ToList();
  }
}

public async Task GetUsersInRoleAsync(string roleName, CancellationToken cancellationToken)
{
  using (var con = CreateConnection())
  {
    return (await con.QueryAsync(
      "SELECT u.UserId, u.Username " +
      "FROM UserRoles AS ur " +
      "JOIN Roles AS r ON ur.RoleId = r.RoleId " +
      "JOIN Users AS u ON ur.UserId = u.UserId " +
      "WHERE r.RoleName = @roleName",
      new { roleName })
    ).ToList();
  }
}

public async Task IsInRoleAsync(MyCustomUser user, string roleName, CancellationToken cancellationToken)
{
  var roles = await GetRolesAsync(user, cancellationToken);
  return roles.Contains(roleName);
}

And that’s it! We now have a custom bare-bones identity provider. To use this, we can just hook it up in Startup.cs, as follows:

services.Configure(options =>
{
  options.ConnectionString = Config.GetConnectionString("MyCustomIdentity");
});

services.AddScoped();
services.AddIdentity()
  .AddUserStore()
  .AddRoleStore();