asp-net-core-identity-patterns

Imported from wshaddix/dotnet-skills (skills/asp-net-core-identity-patterns/SKILL.md). Install upstream with npx skills add wshaddix/dotnet-skills --skill asp-net-core-identity-patterns. Copyright stays with the author.

You are a senior .NET security & identity architect. When the task involves user authentication, registration, login, roles, claims, 2FA, external logins, or authorization in ASP.NET Core (especially Razor Pages), strictly follow these patterns. Prioritize OWASP compliance, least privilege, observability, and minimal attack surface. Target .NET 8+ with nullable enabled.

Rationale

ASP.NET Core Identity provides robust membership (users, roles, claims, tokens) but defaults are developer-friendly, not production-hardened. Misconfigurations lead to weak passwords, session hijacking, enumeration attacks, or compliance failures (GDPR, SOC2). These patterns enforce secure defaults, proper flows, and testable integration.

Core Setup (Program.cs / Startup)

• Use AddDefaultIdentity<IdentityUser>() or AddIdentity<IdentityUser, IdentityRole>() for role support.
• Chain with AddEntityFrameworkStores<ApplicationDbContext>().
• Always configure options early:

builder.Services.AddDefaultIdentity<IdentityUser>(options =>
{
    // Password policy - enforce strong defaults
    options.Password.RequiredLength = 12;
    options.Password.RequireDigit = true;
    options.Password.RequireLowercase = true;
    options.Password.RequireUppercase = true;
    options.Password.RequireNonAlphanumeric = true;
    options.Password.RequiredUniqueChars = 6;

    // Lockout - prevent brute force
    options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(15);
    options.Lockout.MaxFailedAccessAttempts = 5;
    options.Lockout.AllowedForNewUsers = true;

    // Sign-in requirements
    options.SignIn.RequireConfirmedAccount = true;          // Email confirmation mandatory
    options.SignIn.RequireConfirmedEmail = true;
    options.SignIn.RequireConfirmedPhoneNumber = false;     // Optional 2FA/SMS

    // User settings
    options.User.RequireUniqueEmail = true;
    options.User.AllowedUserNameCharacters = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._@+";
})
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();  // For password reset, email confirmation, 2FA

• Add authentication & authorization middleware after UseRouting():

app.UseAuthentication();
app.UseAuthorization();
app.MapRazorPages();

• Enable HTTPS enforcement globally:

app.UseHsts();
app.UseHttpsRedirection();

Razor Pages Integration

• Scaffold Identity UI selectively:

dotnet aspnet-codegenerator identity -dc ApplicationDbContext \
  --files "Account.Register;Account.Login;Account.Logout;Account.ForgotPassword;Account.ConfirmEmail;Account.Manage.Index;Account.Manage.ChangePassword;Account.Manage.TwoFactorAuthentication"

• Inject services in PageModels:

private readonly UserManager<IdentityUser> _userManager;
private readonly SignInManager<IdentityUser> _signInManager;
private readonly ILogger<RegisterModel> _logger;

public RegisterModel(
    UserManager<IdentityUser> userManager,
    SignInManager<IdentityUser> signInManager,
    ILogger<RegisterModel> logger)
{
    _userManager = userManager;
    _signInManager = signInManager;
    _logger = logger;
}

• Always validate anti-forgery in forms: @Html.AntiForgeryToken() and [ValidateAntiForgeryToken] on POST handlers.
• Use [Authorize] on protected PageModels:

[Authorize(Policy = "RequireAdminRole")]
public class AdminModel : PageModel { ... }

Authorization Patterns

• Prefer policy-based over role-based where possible:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("RequireAdminRole", policy =>
        policy.RequireRole("Admin"));

    options.AddPolicy("CanEditContent", policy =>
        policy.RequireClaim("Permission", "EditContent")
              .RequireAuthenticatedUser());
});

• Apply via [Authorize(Policy = "CanEditContent")] or in RequireAuthorization() on endpoints.

Security Hardening

• Cookie configuration:

builder.Services.ConfigureApplicationCookie(options =>
{
    options.Cookie.HttpOnly = true;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;  // HTTPS only
    options.Cookie.SameSite = SameSiteMode.Strict;            // Mitigate CSRF
    options.ExpireTimeSpan = TimeSpan.FromDays(14);
    options.SlidingExpiration = true;
    options.LoginPath = "/Identity/Account/Login";
    options.AccessDeniedPath = "/Identity/Account/AccessDenied";
});

• Enable 2FA by default for sensitive apps: Guide users via TwoFactorAuthentication page.
• Use email confirmation tokens; never auto-sign-in unconfirmed users in production.
• Rate-limit login/registration endpoints (via AspNetCoreRateLimit or middleware).
• Log identity events via Microsoft.AspNetCore.Identity meters (new in .NET 10+) for anomaly detection.

External Providers

• Add Google, Microsoft, etc.:

builder.Services.AddAuthentication()
    .AddGoogle(options =>
    {
        options.ClientId = builder.Configuration["Authentication:Google:ClientId"];
        options.ClientSecret = builder.Configuration["Authentication:Google:ClientSecret"];
    });

• Display schemes dynamically in login page using SignInManager.GetExternalAuthenticationSchemesAsync().

Custom User / Claims

• Extend IdentityUser sparingly (add properties like FirstName, LastName):

public class ApplicationUser : IdentityUser
{
    public string FullName { get; set; } = string.Empty;
}

• Add claims post-login via SignInManager or custom claims factory.

Testing & Observability

• Unit test with UserManager / SignInManager mocks (Moq).
• Integration test auth flows with WebApplicationFactory.
• Monitor via OpenTelemetry / App Insights for sign-in durations, failures, lockouts.

Example: Secure Register Handler Snippet

public async Task<IActionResult> OnPostAsync()
{
    if (!ModelState.IsValid) return Page();

    var user = CreateUser();  // Factory method
    await _userStore.SetUserNameAsync(user, Input.Email, CancellationToken.None);
    await _emailStore.SetEmailAsync(user, Input.Email, CancellationToken.None);

    var result = await _userManager.CreateAsync(user, Input.Password);
    if (result.Succeeded)
    {
        _logger.LogInformation("User created a new account with password.");

        var code = await _userManager.GenerateEmailConfirmationTokenAsync(user);
        // Send email with confirmation link...

        if (_userManager.Options.SignIn.RequireConfirmedAccount)
            return RedirectToPage("RegisterConfirmation", new { email = Input.Email });

        await _signInManager.SignInAsync(user, isPersistent: false);
        return LocalRedirect(returnUrl);
    }

    foreach (var error in result.Errors) ModelState.AddModelError(string.Empty, error.Description);
    return Page();
}

Anti-Patterns

• Disabling email confirmation in production → Allows fake/spam accounts.
• Weak password policies → Use at least 12 chars + complexity.
• Storing secrets in code → Use User Secrets / Azure Key Vault.
• Using [Authorize(Roles = "Admin")] everywhere → Prefer claims/policies.
• Ignoring lockout → Enables brute-force attacks.
• Publishing full Identity UI assets in prod → Scaffold only needed pages; exclude static files.

References

• Microsoft Docs: https://learn.microsoft.com/en-us/aspnet/core/security/authentication/identity
• OWASP .NET Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/DotNet_Security_Cheat_Sheet.html
• .NET 10 Identity Metrics: Microsoft.AspNetCore.Identity meter docs

Apply this skill when auth/identity tasks appear. Cross-reference with razor-pages-patterns, web-security-hardening, or dependency-injection-patterns.