ASP.NET Core Identity框架使用指南

---

前言

ASP.NET Core Identity 是一个用于管理用户身份验证、授权和用户信息的框架，它是 ASP.NET Core 平台的重要组成部分。它为开发者提供了一套完整的工具和 API，用于处理用户注册、登录、密码管理、角色权限、第三方登录（如 Google、Facebook）等常见功能。

一、核心功能

• 用户管理
  支持创建、更新、删除用户，管理用户信息（用户名、邮箱、密码等）。

• 身份验证（Authentication）
  验证用户身份（如登录），支持 Cookie 认证、JWT（用于 API）、OAuth 2.0、OpenID Connect 等。

• 授权（Authorization）
  基于角色（Role-Based）或策略（Policy-Based）控制资源访问权限。

• 密码安全
  内置密码哈希、密码复杂度策略、账户锁定（防暴力破解）等功能。

• 多因素认证（2FA）
  支持短信、邮件、验证器应用（如 Google Authenticator）等二次验证方式。

• 外部登录集成
  快速集成第三方登录（如 Google、Facebook、Microsoft、GitHub 等）。

• 用户声明（Claims）
  支持基于声明的授权模型，灵活定义用户属性。

• 角色和权限管理
  创建角色并为用户分配角色，实现基于角色的访问控制。

二、核心组件

• UserManager<TUser>
  管理用户（创建、删除、查找、修改密码等），泛型 TUser 通常是 IdentityUser 或其子类。

• SignInManager<TUser>
  处理用户登录、登出、外部登录等操作。

• RoleManager<TRole>
  管理角色（创建、删除、分配权限等），TRole 默认为 IdentityRole。

• IdentityUser 和 IdentityRole
  内置的用户和角色模型，可扩展自定义字段。

• Entity Framework Core 集成
  默认使用 EF Core 存储用户和角色数据，支持 SQL Server、SQLite、PostgreSQL 等数据库。

三、使用

1）创建项目

1. 使用 Visual Studio 创建 ASP.NET Core Web API 项目

2）安装必要 NuGet包

1. 核心依赖包括 Identity 和 EF Core 的集成包：

   Install-Package Microsoft.AspNetCore.Identity.EntityFrameworkCore
   Install-Package Microsoft.EntityFrameworkCore.SqlServer
   Install-Package Microsoft.EntityFrameworkCore.Tools
   

3）配置数据库连接字符串

1. 在 appsettings.json 中添加数据库连接配置：

    "ConnectionStrings": {"DefaultConnection": "Server=XXX;Database=XXX;User Id=sa;Password=XXX;TrustServerCertificate=True;Trusted_Connection=True;MultipleActiveResultSets=True"}
   

4）用户与角色实体定义

1. 自定义用户类
   继承 IdentityUser 并扩展属性（如创建时间）：

   using Microsoft.AspNetCore.Identity;namespace IdentityProject.Entity
   {public class ApplicationUser:IdentityUser<long>{public DateTime CreateTime { get; set; }}
   }	
   

2. 自定义角色类
   继承 IdentityRole（主键类型需与用户类一致）：

   using Microsoft.AspNetCore.Identity;namespace IdentityProject.Entity
   {public class ApplicationRole:IdentityRole<long>{}
   }
   

4）配置数据库上下文

1. 创建 DbContext
   继承 IdentityDbContext 并指定用户、角色类型：

   using IdentityProject.Entity;
   using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
   using Microsoft.EntityFrameworkCore;namespace IdentityProject.Data
   {public class MyDbContext : IdentityDbContext<ApplicationUser,ApplicationRole,long>{public MyDbContext(DbContextOptions<MyDbContext> options) : base(options){}}
   }
   

2. 创建MyDbContextDesignTimeFactory.cs

   using Microsoft.EntityFrameworkCore;
   using Microsoft.EntityFrameworkCore.Design;namespace IdentityProject.Data
   {public class MyDbContextDesignTimeFactory : IDesignTimeDbContextFactory<MyDbContext>{public MyDbContext CreateDbContext(string[] args){DbContextOptionsBuilder<MyDbContext> builder=  new DbContextOptionsBuilder<MyDbContext>();builder.UseSqlServer("Server=XXX;Database=XXX;User Id=sa;Password=XXX;TrustServerCertificate=True;Trusted_Connection=True;MultipleActiveResultSets=True");return new MyDbContext(builder.Options);}}
   }
   

5） 注册服务

1. 在 Program.cs 中配置 Identity 和数据库服务：

   var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");builder.Services.AddDbContext<MyDbContext>(opt => {opt.UseSqlServer(connectionString);});builder.Services.AddIdentityCore<ApplicationUser>(opt => {opt.Lockout.MaxFailedAccessAttempts = 5;//登录失败多少次账号被锁定opt.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(1);//锁定多长时间opt.Password.RequireDigit = false;//密码是否需要数字    opt.Password.RequireLowercase = false;//密码是否需要小写字符opt.Password.RequireUppercase = false;//密码是否需要大写字符opt.Password.RequireNonAlphanumeric = false;//密码是否需要非字母数字的字符opt.Password.RequiredLength = 6;//密码长度opt.Tokens.PasswordResetTokenProvider = TokenOptions.DefaultEmailProvider;//密码重置令牌，使用默认的邮箱令牌提供程序来生成和验证令牌。此提供程序通常与用户邮箱关联，生成的令牌会通过邮件发送给用户,保证用户通过邮件接收密码重置链接。opt.Tokens.EmailConfirmationTokenProvider = TokenOptions.DefaultEmailProvider;//配置邮箱确认令牌（Email Confirmation Token）的生成和验证所使用的提供程序（Provider）var idBuilder = new IdentityBuilder(typeof(ApplicationUser), typeof(ApplicationRole), builder.Services);idBuilder.AddEntityFrameworkStores<MyDbContext>().AddDefaultTokenProviders().AddUserManager<UserManager<ApplicationUser>>().AddRoleManager<RoleManager<ApplicationRole>>();
   

6）数据库迁移与初始化

1. 生成迁移文件
   执行 EF Core 命令创建迁移：

   Add-Migration Init
   

2. 更新数据库
   应用迁移以生成 Identity 相关表:

   Update-Database
   

7）用户管理功能实现

1. 创建角色、用户注册、角色分配、用户登录
   使用 UserManager 创建用户：

   using IdentityProject.Entity;
   using Microsoft.AspNetCore.Identity;
   using Microsoft.AspNetCore.Mvc;namespace IdentityProject.Controllers
   {[Route("api/[controller]/[action]")][ApiController]public class TestController : ControllerBase{private readonly UserManager<ApplicationUser> _userManager;private readonly RoleManager<ApplicationRole> _roleManager;private readonly IWebHostEnvironment _webHostEnvironment;public TestController(UserManager<ApplicationUser> userManager, RoleManager<ApplicationRole> roleManager, IWebHostEnvironment webHostEnvironment){_userManager = userManager;_roleManager = roleManager;_webHostEnvironment = webHostEnvironment;}[HttpPost]public async Task<ActionResult<string>> Test(){if (!await _roleManager.RoleExistsAsync("admin")){ApplicationRole role=new ApplicationRole { Name = "admin" };//创建角色var res=await _roleManager.CreateAsync(role);if (!res.Succeeded) return BadRequest("CreateRoleAsync Failed");}ApplicationUser user=await _userManager.FindByNameAsync("LGF");if (user == null){user = new ApplicationUser { UserName="LGF"};//创建用户var res=await _userManager.CreateAsync(user, "123456");if (!res.Succeeded){return BadRequest("CreateUserAsync Failed");}}var inRole=await _userManager.IsInRoleAsync(user, "admin");if (!inRole){//分配角色var res=await _userManager.AddToRoleAsync(user, "admin");if (!res.Succeeded) return BadRequest("UserManager AddToRoleAsync Failed");}return "Success";}/// <summary>/// 登录/// </summary>/// <param name="request"></param>/// <returns></returns>[HttpPost]public async Task<ActionResult> Login(CheckPwdRequest request){string userName=request.UserName;string password=request.Password;var user = await _userManager.FindByNameAsync(userName);if (user == null){if (_webHostEnvironment.IsDevelopment()){return BadRequest("用户不存在");}return BadRequest();}bool locked = await _userManager.IsLockedOutAsync(user);if (locked){return BadRequest($"用户被锁定，锁定结束时间为：{user.LockoutEnd}");}bool validatePwd = await _userManager.CheckPasswordAsync(user, password);if (validatePwd){await _userManager.ResetAccessFailedCountAsync(user);return Ok("登录成功");}else{await _userManager.AccessFailedAsync(user);return BadRequest($"{userName} Login Failed ,Password is wrong");}}}
   }
   

8）认证与授权配置

1. 启用中间件
   在请求管道中添加认证与授权中间件（顺序不可颠倒）：

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

2. 控制器授权
   使用 [Authorize] 属性限制访问：

   [Authorize(Roles = "admin")]
   [ApiController]
   public class AdminController : ControllerBase { }
   

3. 策略授权
   自定义策略（如年龄限制）：

   services.AddAuthorization(options =>
   {options.AddPolicy("AdultOnly", policy => policy.RequireClaim("Age", "18"));
   });
   

四、常见问题与调试

• 迁移错误：检查 DbContext 是否继承自 IdentityDbContext，确保连接字符串正确。

• 中间件顺序：UseAuthentication 必须在 UseAuthorization 之前。

• 密码策略冲突：通过 IdentityOptions 调整复杂度要求。

---

总结

基于 ASP.NET Core Identity 的 Web API 身份系统，支持用户管理、角色授权及扩展功能。