c#中jwt自定义声明操作需分五步：一、用jwtsecuritytokenhandler签发含自定义claim的jwt；二、解析jwtsecuritytoken提取声明；三、通过claimsprincipal在asp.net core中获取；四、用静态常量管理claim类型；五、对复杂对象先序列化再存入claim。
如果您在C#中使用JWT进行身份验证，需要向令牌中添加业务所需的自定义声明（Claim），或从已签发的JWT中安全提取这些声明，则需准确操作ClaimsIdentity与JwtSecurityToken结构。以下是实现此目标的具体方法：
一、使用JwtSecurityTokenHandler创建含自定义声明的JWT
该方法通过手动构建ClaimsIdentity并传入自定义Claim集合，再经JwtSecurityTokenHandler写入签名生成完整JWT字符串。适用于服务端签发令牌场景。
1、定义自定义声明集合，例如用户角色、部门ID、是否为VIP等：
var claims = new List
{
new Claim(ClaimTypes.Name, "zhangsan"),
new Claim("DepartmentId", "D001"),
new Claim("IsVip", "true"),
new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
};
2、创建ClaimsIdentity实例，并将上述claims传入构造函数：
var identity = new ClaimsIdentity(claims, "JwtAuth");
3、配置SigningCredentials，使用对称密钥（如SymmetricSecurityKey）和签名算法（如HmacSha256）：
var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("your_32_byte_secret_key_here"));
var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
4、构造JwtSecurityToken对象，指定Issuer、Audience、有效期及ClaimsIdentity：
var token = new JwtSecurityToken(
issuer: "https://myapi.com",
audience: "https://clientapp.com",
claims: identity.Claims,
expires: DateTime.UtcNow.AddMinutes(30),
signingCredentials: creds
);
5、使用JwtSecurityTokenHandler.WriteToken()生成最终JWT字符串：
var handler = new JwtSecurityTokenHandler();
string jwtString = handler.WriteToken(token);
二、使用JwtSecurityToken直接解析并读取自定义声明
该方法适用于接收并验证外部传入的JWT字符串，从中提取原始Claim值。无需依赖HttpContext或AuthenticationManager，适合中间件或工具类场景。
1、实例化JwtSecurityTokenHandler：
var handler = new JwtSecurityTokenHandler();
2、调用ReadToken()方法解析JWT字符串，返回JwtSecurityToken对象：
var jwtToken = handler.ReadToken(jwtString) as JwtSecurityToken;
3、检查jwtToken是否为null且HasPayload，避免空引用异常：
if (jwtToken == null || !jwtToken.HasPayload)
throw new ArgumentException(JWT字符串格式无效或无法解析);
4、遍历jwtToken.Payload.Claims集合，按Type匹配自定义声明：
var departmentId = jwtToken.Payload.Claims.FirstOrDefault(c => c.Type == "DepartmentId")?.Value;
var isVip = bool.TryParse(jwtToken.Payload.Claims.FirstOrDefault(c => c.Type == "IsVip")?.Value, out bool vipFlag) ? vipFlag : false;
5、对关键业务声明做存在性校验：
if (string.IsNullOrWhiteSpace(departmentId))
throw new SecurityTokenException(缺少必需声明：DepartmentId);
三、通过ClaimsPrincipal从验证后的JWT中获取声明
该方法适用于ASP.NET Core中已启用JWT Bearer认证的上下文，系统自动将JWT载荷映射为ClaimsPrincipal，可直接访问User属性获取所有声明。
1、确保Startup.cs或Program.cs中已配置AddAuthentication().AddJwtBearer()，且TokenValidationParameters正确设置。
2、在Controller或Service中注入HttpContext或直接使用User属性：
var user = HttpContext.User;
3、使用FindFirst()方法查找单个自定义声明：
var deptClaim = user.FindFirst("DepartmentId");
string deptId = deptClaim?.Value;
4、使用Claims属性遍历全部声明并筛选：
var vipClaim = user.Claims.FirstOrDefault(c => c.Type == "IsVip");
bool isVip = vipClaim != null && bool.TryParse(vipClaim.Value, out bool flag) && flag;
5、强制要求特定声明存在时，可抛出未授权异常：
if (deptId == null)
Context.Response.StatusCode = StatusCodes.Status401Unauthorized;
throw new UnauthorizedAccessException(请求缺少有效DepartmentId声明);
四、使用JwtRegisteredClaimNames以外的常量注册自定义Claim类型
为避免硬编码字符串导致拼写错误或维护困难，建议将自定义Claim类型定义为静态只读字段，统一管理命名规范与语义。
1、在公共类中定义自定义Claim类型常量：
public static class CustomClaimTypes
{
public const string DepartmentId = "DepartmentId";
public const string IsVip = "IsVip";
public const string TenantCode = "TenantCode";
}
2、添加声明时使用常量而非字符串字面量：
new Claim(CustomClaimTypes.DepartmentId, "D001");
3、读取声明时同样使用该常量：
user.FindFirst(CustomClaimTypes.DepartmentId)?.Value;
4、在策略授权（Policy-based Authorization）中引用该类型：
options.AddPolicy("InDepartment", policy => policy.RequireClaim(CustomClaimTypes.DepartmentId));
五、处理Claim值为复杂对象的序列化方式
当需嵌入JSON结构（如用户权限树、配置项集合）作为Claim值时，不能直接传入对象实例，必须先序列化为字符串，否则JwtSecurityToken构造过程会忽略或抛出异常。
1、准备要嵌入的对象，例如权限列表：
var permissions = new[] { "read:order", "write:product" };
2、使用System.Text.Json序列化为JSON字符串：
string jsonPermissions = JsonSerializer.Serialize(permissions);
3、将序列化后字符串作为Claim值添加：
new Claim("Permissions", jsonPermissions);
4、读取时反序列化回目标类型：
var permClaim = jwtToken.Payload.Claims.FirstOrDefault(c => c.Type == "Permissions");
if (permClaim != null)
string[] perms = JsonSerializer.Deserialize
5、捕获反序列化异常以防止令牌损坏导致服务中断：
try { ... } catch (JsonException ex) { throw new SecurityTokenException(Permissions声明内容非合法JSON格式, ex); }
