👁 Image
Plinth.Security.Jwt 1.8.1

README

Plinth.Security.Jwt

JWT signing and encryption utilities, add-on to Plinth.Security

Provides utilities for creating, validating, and refreshing JWTs with support for both signed (JWS) and encrypted (JWE) tokens.

• Supports Signed JWT (JWS) via
  • HMAC with SHA-{256, 384, 512}
  • RSA with SHA-{256, 384, 512}
• Supports Encrypted JWT (JWE) via
  • AES-{128, 192, 256}-CBC-HMAC-{256, 384, 512}
  • RSA-OAEP-{160, 256, 384, 512} with AES-{128, 192, 256}-CBC-HMAC-{256, 384, 512}

Setup

1. Install the Package

dotnet add package Plinth.Security.Jwt

2. Configure JWT Options

Create and configure JwtGenerationOptions with your desired security mode:

using Plinth.Security.Jwt;

// Example using HMAC signature (symmetric key)
var secretKey = new byte[32]; // 32 bytes = 256 bits for HS256
// ... populate secretKey from secure configuration ...

var jwtOptions = new JwtGenerationOptions
{
 SecurityMode = new JwtSecurityModeHmacSignature(secretKey),
 Issuer = "MyApplication",
 Audience = "MyApplicationUsers",
 TokenLifetime = TimeSpan.FromMinutes(15),
 MaxTokenLifetime = TimeSpan.FromHours(24),
 TokenContentLogging = false // Set to true only in development
};

jwtOptions.Validate();

3. Register with Dependency Injection

services.AddSingleton(jwtOptions);
services.AddSingleton<JwtValidator>();
services.AddSingleton<JwtGenerator>();

Usage

Creating JWTs

Use JwtGenerator to create tokens for authenticated users:

public class AuthController : Controller
{
 private readonly JwtGenerator _jwtGenerator;

 public AuthController(JwtGenerator jwtGenerator)
 {
 _jwtGenerator = jwtGenerator;
 }

 [HttpPost("login")]
 public async Task<ActionResult> Login([FromBody] LoginRequest request)
 {
 // ... validate credentials ...

 var userId = Guid.NewGuid(); // from your user database
 var userName = "user@example.com";
 var roles = new[] { "User", "Admin" };

 // Create a JWT with basic user information
 var jwtData = _jwtGenerator.GetBuilder(userId, userName, roles)
 .Build();

 return Ok(new { token = jwtData.Token });
 }
}

Adding Custom Claims

You can add custom claims to the JWT:

var jwtData = _jwtGenerator.GetBuilder(userId, userName, roles)
 .AddClaim("department", "Engineering")
 .AddClaim("employee_id", "12345")
 .Build();

Validating JWTs

Use JwtValidator to validate and extract claims from tokens:

public class SecureController : Controller
{
 private readonly JwtValidator _jwtValidator;

 public SecureController(JwtValidator jwtValidator)
 {
 _jwtValidator = jwtValidator;
 }

 [HttpGet("secure-data")]
 public ActionResult GetSecureData([FromHeader(Name = "Authorization")] string authHeader)
 {
 try
 {
 var token = authHeader.Replace("Bearer ", "");
 var claimsPrincipal = _jwtValidator.Validate(token);

 var userId = claimsPrincipal.JwtUserId();
 var userName = claimsPrincipal.JwtUserName();
 var roles = claimsPrincipal.JwtRoles();

 // ... use claims to authorize and fetch data ...

 return Ok();
 }
 catch (SecurityTokenException ex)
 {
 return Unauthorized(new { error = "Invalid token" });
 }
 }
}

Refreshing Tokens

Refresh an existing token to extend its lifetime (up to MaxTokenLifetime):

[HttpPost("refresh")]
public ActionResult RefreshToken([FromBody] RefreshRequest request)
{
 try
 {
 var newJwtData = _jwtGenerator.Refresh(request.Token);
 return Ok(new { token = newJwtData.Token });
 }
 catch (SecurityTokenExpiredException)
 {
 return Unauthorized(new { error = "Token has reached maximum lifetime" });
 }
}

Security Modes

HMAC Signature (Symmetric)

Use for single-server or shared-secret scenarios:

var secretKey = new byte[32]; // 32 bytes for HS256, 48 for HS384, 64 for HS512
// Load from secure configuration (e.g., Azure Key Vault, environment variable)

var securityMode = new JwtSecurityModeHmacSignature(secretKey);

RSA Signature (Asymmetric)

Use for distributed systems where token validation occurs on different servers:

using System.Security.Cryptography;

var rsa = RSA.Create(2048); // 2048-bit key
// Or load from certificate store

var securityMode = new JwtSecurityModeRsaSignature(rsa, SecurityAlgorithms.RsaSha256);

AES Encryption (Symmetric)

Use when token contents must be encrypted:

var encryptionKey = new byte[32]; // 32 bytes for AES256
// Load from secure configuration

var securityMode = new JwtSecurityModeAesEncryption(encryptionKey);

RSA Encryption (Asymmetric)

Use for encrypted tokens in distributed systems:

var rsa = RSA.Create(2048);
// Or load from certificate store

var securityMode = new JwtSecurityModeRsaEncryption(rsa);

ClaimsPrincipal Extension Methods

The library provides extension methods for extracting JWT claims:

• JwtUserId() - Get the user's unique identifier (Guid)
• JwtUserName() - Get the user's unique name/email
• JwtRoles() - Get the user's roles as an array
• JwtSessionGuid() - Get the session identifier
• JwtOriginalIssue() - Get the original issue date (for refresh tracking)

Best Practices

1. Secure Key Storage: Store encryption/signing keys in secure configuration (Azure Key Vault, AWS Secrets Manager, etc.)
2. Short Token Lifetimes: Keep TokenLifetime short (5-15 minutes) and use refresh tokens
3. Disable Logging in Production: Set TokenContentLogging = false in production to avoid leaking sensitive data
4. HTTPS Only: Always transmit JWTs over HTTPS
5. Validate on Every Request: Always validate tokens on protected endpoints
6. Use Strong Keys: Use at least 256-bit keys for HMAC, 2048-bit for RSA