Migrate to ASP.NET Core Identity Auth

Migrate from ServiceStack Auth to Identity Auth​

Migrating from ServiceStack Auth to Identity Auth should be relatively straight-forward as ServiceStack uses a compatible Identity v2 password hashing format, which should let you migrate your users to Identity Auth without them noticing.

1. Rename old AppUser table​

You'll want to use a different name so it doesn't conflict with the new Identity ApplicationUser. This is only needed to query the User data to migrate to Identity Auth, you'll be able to remove it after successfully migrating all Users.

You don't need to include all the properties of the UserAuth base table, just the ones you want to migrate to Identity Auth, which for Blazor Diffusion was only:

// Used by OrmLite to fetch User data to migrate from old ServiceStack `AppUser` table
[Alias("AppUser")]
public class OldAppUser
{
    [AutoIncrement]
    public int Id { get; set; }
    public string UserName { get; set; }
    public string DisplayName { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string? Handle { get; set; }
    public string Email { get; set; }
    public string PasswordHash { get; set; }
    public string? ProfileUrl { get; set; }
    public string? Avatar { get; set; } //overrides ProfileUrl
    public string? LastLoginIp { get; set; }
    public DateTime? LastLoginDate { get; set; }
    public string RefIdStr { get; set; }
    public DateTime? LockedDate { get; set; }
    public DateTime CreatedDate { get; set; }
    public DateTime ModifiedDate { get; set; }
}

2. Create Identity Auth Data Model​

If you have a lot of existing references to the AppUser name you'll want to retain the same name so the existing references wont need to be updated. Essentially your custom EF IdentityUser will want a copy of all the properties you want to migrate other than Id, Email, and PasswordHash that's already defined in the base IdentityUser class:

[Alias("AspNetUsers")] // Tell OrmLite which table this EF Data Model maps to
public class AppUser : IdentityUser<int>
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
    public string? DisplayName { get; set; }
    public string? ProfileUrl { get; set; }
    [Input(Type = "file"), UploadTo("avatars")]
    public string? Avatar { get; set; } //overrides ProfileUrl
    public string? Handle { get; set; }
    public int? RefId { get; set; }
    public string RefIdStr { get; set; } = Guid.NewGuid().ToString();
    public bool IsArchived { get; set; }
    public DateTime? ArchivedDate { get; set; }
    public string? LastLoginIp { get; set; }
    public DateTime? LastLoginDate { get; set; }
    public DateTime CreatedDate { get; set; } = DateTime.UtcNow;
    public DateTime ModifiedDate { get; set; } = DateTime.UtcNow;
}

The AppUser Data Model and int primary key would also need to be registered in your Configure.Auth.cs:

public class ConfigureAuth : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost => {
            appHost.Plugins.Add(new AuthFeature(IdentityAuth.For<AppUser,int>(
                options => {
                    options.EnableCredentialsAuth = true;
                    options.SessionFactory = () => new CustomUserSession();
                })
            ));
        });
}

3. Add Authentication Configuration​

You'll need to configure Entity Framework and add your desired ASP.NET Identity Auth configuration to your Program.cs.

We recommend copying from a new Microsoft or ServiceStack .NET 8 Project which closely matches the Authentication options you want to enable.

Using Identity Auth Application Cookie​

For example you can start with the recommended Authentication for a new Blazor Project from its Program.cs:

services.AddAuthentication(IdentityConstants.ApplicationScheme)
    .AddIdentityCookies();
services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo("App_Data"));

// $ dotnet ef migrations add CreateIdentitySchema
// $ dotnet ef database update
var connectionString = config.GetConnectionString("DefaultConnection") ?? throw new InvalidOperationException("Connection string 'DefaultConnection' not found.");
services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlite(connectionString, b => b.MigrationsAssembly(nameof(MyApp))));
services.AddDatabaseDeveloperPageExceptionFilter();

services.AddIdentityCore<ApplicationUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddRoles<IdentityRole>()
    .AddEntityFrameworkStores<ApplicationDbContext>()
    .AddSignInManager()
    .AddDefaultTokenProviders();

services.AddSingleton<IEmailSender, NoOpEmailSender>();
services.AddScoped<IUserClaimsPrincipalFactory<ApplicationUser>, AdditionalUserClaimsPrincipalFactory>();

Using Identity Auth OAuth Providers​

Alternatively if you want to add support for external OAuth logins you can copy from the MVC Tailwind Authentication configuration in its Program.cs which will also require adding the NuGet dependencies of the OAuth providers you want to support which you can get from its MyApp.csproj

4. Create and Run EF Migrations​

After your App is properly configured you'll want to create the EF Migrations for your the Identity Auth User tables by installing the dotnet-ef tool and running:

Which should create the EF Migrations in the /Migrations folder, you can then run the migrations to create the Identity Auth tables in your App's configured database:

5. Implement the Migrate Users Task​

This could be implemented in a separate Application or Unit Test although we've found the easiest way to migrate existing users is to implement a custom App Task as it's able to make use of your App's configured Authentication, EF and OrmLite dependencies that can then be run from the command-line.

The implementation should be fairly straight-forward, you'll basically just need to create a new Identity Auth User using the UserManager<AppUser> dependency for each of your existing users:

public class ConfigureDbMigrations : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost => {
            AppTasks.Register("migrate.users", _ => {
                var log = appHost.GetApplicationServices().GetRequiredService<ILogger<ConfigureDbMigrations>>();

                log.LogInformation("Running migrate.users...");
                var scopeFactory = appHost.GetApplicationServices().GetRequiredService<IServiceScopeFactory>();
                using var scope = scopeFactory.CreateScope();
                using var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
                using var db = scope.ServiceProvider.GetRequiredService<IDbConnectionFactory>().Open();
                var migrateUsers = db.Select(db.From<OldAppUser>().OrderBy(x => x.Id));

                log.LogInformation("Migrating {Count} Existing ServiceStack Users to Identity Auth Users...", migrateUsers.Count);
                MigrateExistingUsers(dbContext, scope.ServiceProvider, migrateUsers).Wait();
            });
            AppTasks.Run();
        });

    private async Task MigrateExistingUsers(ApplicationDbContext dbContext, IServiceProvider services, 
        List<OldAppUser> migrateUsers, string tempPassword="p@55wOrd")
    {
        var userManager = services.GetRequiredService<UserManager<AppUser>>();
        var now = DateTime.UtcNow;

        foreach (var user in migrateUsers)
        {
            var appUser = new AppUser
            {
                Id = user.Id,
                UserName = user.Email,
                Email = user.Email,
                DisplayName = user.DisplayName,
                FirstName = user.FirstName,
                LastName = user.LastName,
                Handle = user.Handle,
                ProfileUrl = user.ProfileUrl,
                Avatar = user.Avatar,
                RefIdStr = user.RefIdStr ?? Guid.NewGuid().ToString(),
                LockoutEnabled = true,
                LockoutEnd = user.LockedDate != null ? now.AddYears(10) : now,
                LastLoginDate = user.LastLoginDate,
                LastLoginIp = user.LastLoginIp,
                CreatedDate = user.CreatedDate,
                ModifiedDate = user.ModifiedDate,
                // Verify you want existing Users emails to be confirmed
                EmailConfirmed = true,
            };
            await userManager.CreateAsync(appUser, tempPassword);

            // Update raw Password Hash using EF
            if (user.PasswordHash != null)
            {
                dbContext.Users
                    .Where(x => x.Id == user.Id)
                    .ExecuteUpdate(setters => setters.SetProperty(x => x.PasswordHash, user.PasswordHash));
            }
        }
    }
}    

As there's no official API for updating the raw PasswordHash you'll need to use EF's ExecuteUpdate() API to update it on the AspNetUsers table directly.

It should be noted that ServiceStack Auth still uses ASP.NET Core's previous Identity v2 format for hashing its passwords, this will be automatically re-hashed using the latest ASP.NET Identity v3 format after users successfully sign in.

Optimizing the PasswordHash Update​

Whilst migrating users should be a once-off task, if you have a lot of users you may want to optimize the PasswordHash update from a N+1 query per user to a single query that updates all users in a single command.

You'll need to use the UPDATE FROM syntax that's supported by your RDBMS's, here's an example of how to do it in SQLite:

UPDATE AspNetUsers
SET PasswordHash = u.PasswordHash
FROM (SELECT Email, PasswordHash FROM AppUser WHERE PasswordHash is NOT NULL) AS u
WHERE u.Email = AspNetUsers.Email;

Migrating Roles​

Migrating Roles will depend how their stored in your App, you'll first need to ensure each role is created in the AspNetRoles table with:

string[] allRoles = [...]; // All Roles in your App
var roleManager = services.GetRequiredService<RoleManager<IdentityRole>>();
foreach (var roleName in allRoles)
{
    var roleExist = await roleManager.RoleExistsAsync(roleName);
    if (!roleExist)
    {
        await roleManager.CreateAsync(new IdentityRole(roleName));
    }
}

You can then assign Roles to Users using the UserManager<AppUser>, e.g:

string[] roles = [...]; // Roles to assign to User 
var newUser = await userManager.FindByEmailAsync(user.Email!);
await userManager.AddToRolesAsync(user, roles);

6. Run the migrate.users Task​

With everything in place, all that's left is to run the migrate.users App Task from the command-line:

7. Verify Users can Sign In​

After successfully migrating all your users you should check the new IdentityUser table to verify all the User data you want has been migrated as well as verifying they can sign in with their existing credentials.

The easiest way to include the Identity Auth UI Pages to your App is to copy your Application into a new .NET 8 Project that already includes them, you can create a new Blazor App with:

Or create a new MVC App with:

Alternatively you can manually copy the pages from the project template repositories, for Blazor most of the Identity Auth UI Pages are in the Components/Identity and Pages/Account folders.

For MVC, most of the Identity UI are in the Account and Manage controllers as well as their Views/Account and Views/Manage folders.

SMTP IEmailSender​

The .NET 8 Templates include a nice solution for sending Identity Auth emails through the IEmailSender interface which drops the Email Request in the registered Background MQ in Configure.Mq.cs which uses it to invoke the SendEmail API in EmailServices in a managed background worker:

public class EmailSender(IMessageService messageService) : IEmailSender
{
    public Task SendEmailAsync(string email, string subject, string htmlMessage)
    {
        using var mqClient = messageService.CreateMessageProducer();
        mqClient.Publish(new SendEmail
        {
            To = email,
            Subject = subject,
            BodyHtml = htmlMessage,
        });

        return Task.CompletedTask;
    }
}

To enable it you'll need to register your preferred SMTP Server in your App's appsettings.json:

{
  "SmtpConfig": {
    "Username": "username",
    "Password": "password",
    "Host": "smtp.mailtrap.io",
    "Port": 587,
    "FromEmail": "mail@example.org"
  }
}

Then replace the IEmailSender registration in your Program.cs

services.AddSingleton<IEmailSender, EmailSender>();