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