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