Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,9 @@ jobs:
name: test-results-${{ matrix.os }}-${{ matrix.dotnet-version }}
path: src/MiniJwt.Tests/TestResults/*.trx

- name: Build samples
run: |
dotnet build samples/ConsoleMinimal/ConsoleMinimal.csproj -c Release
dotnet build samples/ASPNetCoreAuth/ASPNetCoreAuth.csproj -c Release
dotnet build samples/WorkerService/WorkerService.csproj -c Release

45 changes: 38 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# MiniJwt.Core
# MiniJwt.Core

<!-- Continuous Integration (main test/build workflow) -->
[![CI](https://img.shields.io/github/actions/workflow/status/jeanlrnt/MiniJwt.Core/ci.yml?label=CI&style=flat-square&logo=github)](https://github.com/jeanlrnt/MiniJwt.Core/actions)
Expand All @@ -16,9 +16,22 @@
[![License](https://img.shields.io/github/license/jeanlrnt/MiniJwt.Core?style=flat-square)](https://github.com/jeanlrnt/MiniJwt.Core/blob/main/LICENSE)
[![Last commit](https://img.shields.io/github/last-commit/jeanlrnt/MiniJwt.Core?style=flat-square)](https://github.com/jeanlrnt/MiniJwt.Core/commits)

MiniJwt.Core is a small library for generating and validating JWTs using attributes on object properties to define claims.
MiniJwt.Core is a lightweight, minimal JWT library for .NET that provides a simple and efficient way to generate and validate JWT tokens using attributes on object properties to define claims. It's designed to be dependency-injection friendly, multi-target framework compatible, and easy to integrate.

This README shows how to install the package, register it in the DI of a .NET application, and provides usage examples (generation, validation and deserialization). It also contains tips for unit tests and debugging.
## Documentation

**[Getting Started Guide](docs/getting-started.md)** - Installation and quick start
**[Configuration Guide](docs/configuration.md)** - Detailed configuration options
**[Examples](docs/examples.md)** - Code examples and integration patterns
**[FAQ](docs/faq.md)** - Common questions and security best practices

## Sample Applications

The repository includes three runnable sample applications demonstrating different integration scenarios:

- **[ConsoleMinimal](samples/ConsoleMinimal/)** - Basic console app for token generation and validation
- **[ASPNetCoreAuth](samples/ASPNetCoreAuth/)** - Full ASP.NET Core web API with JWT authentication
- **[WorkerService](samples/WorkerService/)** - Background service example with periodic token generation

## Requirements

Expand Down Expand Up @@ -172,13 +185,31 @@ A: You can use `/p:PackageVersion=1.2.3` with `dotnet pack` or pack from a proje
**Q: Why does `ValidateAndDeserialize<T>` require `T` to have a parameterless constructor?**
A: The service creates an instance of `T` using the parameterless constructor and then assigns properties from the claims.

## Contributing

Contributions are welcome! Please:
- Follow the existing code style
- Add tests for new features
- Update documentation as needed
- Keep the library minimal and focused

See the [examples documentation](docs/examples.md) for development guidelines.

## Support

If you encounter issues, open an issue on the GitHub repository with:
If you encounter issues:

1. Check the [FAQ](docs/faq.md)
2. Review the [sample applications](samples/)
3. Search [existing issues](https://github.com/jeanlrnt/MiniJwt.Core/issues)
4. Open a new issue with:
- .NET version used
- Minimal reproduction code
- Logs/stacktraces

## License

- the .NET version used
- a minimal reproduction
- logs/stacktraces
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

Expand Down
304 changes: 304 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,304 @@
# Configuration Guide

This guide explains all configuration options available in MiniJwt.Core and best practices for different scenarios.

## MiniJwtOptions

The `MiniJwtOptions` class provides the following configuration properties:

### SecretKey

**Type:** `string`
**Required:** Yes
**Default:** Empty string

The secret key used for signing JWT tokens with the HMAC-SHA256 (HS256) algorithm.

**Requirements:**
- Must be at least 32 bytes (256 bits) for HS256
- Should be a securely generated random string
- Must be kept confidential and never committed to source control

**Example:**
```csharp
options.SecretKey = "your-secret-key-at-least-32-bytes-long-for-hs256-algorithm";
```

**Security Best Practice:**
```csharp
// Load from environment variables
options.SecretKey = Environment.GetEnvironmentVariable("JWT_SECRET_KEY");

// Or from Azure Key Vault, AWS Secrets Manager, etc.
```

### Issuer

**Type:** `string`
**Required:** No (but recommended)
**Default:** Empty string

The issuer claim (`iss`) identifies the principal that issued the JWT. This is typically your application's name or URL.

**Example:**
```csharp
options.Issuer = "https://api.myapp.com";
// or
options.Issuer = "MyApplicationName";
```

**Validation:**
- When set, tokens will be validated to ensure they were issued by this issuer
- When empty, issuer validation is disabled

### Audience

**Type:** `string`
**Required:** No (but recommended)
**Default:** Empty string

The audience claim (`aud`) identifies the recipients that the JWT is intended for. This is typically your API or client application identifier.

**Example:**
```csharp
options.Audience = "https://api.myapp.com";
// or
options.Audience = "MyClientApp";
```

**Validation:**
- When set, tokens will be validated to ensure they are intended for this audience
- When empty, audience validation is disabled

### ExpirationMinutes

**Type:** `double`
**Required:** No
**Default:** 60 minutes

The lifetime of generated tokens in minutes. After this time, tokens will be considered expired and validation will fail.

**Example:**
```csharp
options.ExpirationMinutes = 60; // 1 hour
options.ExpirationMinutes = 1440; // 24 hours
options.ExpirationMinutes = 0.5; // 30 seconds
```

**Best Practices:**
- Use shorter lifetimes (15-60 minutes) for access tokens
- Implement refresh tokens for longer sessions
- Consider your security requirements vs. user experience

## Configuration Methods

### 1. Using appsettings.json (Recommended)

**appsettings.json:**
```json
{
"MiniJwt": {
"SecretKey": "your-secret-key-here",
"Issuer": "MyApp",
"Audience": "MyClient",
"ExpirationMinutes": 60
}
}
```

**Program.cs:**
```csharp
builder.Services.AddMiniJwt(options =>
{
var config = builder.Configuration.GetSection("MiniJwt");
options.SecretKey = config["SecretKey"];
options.Issuer = config["Issuer"];
options.Audience = config["Audience"];
options.ExpirationMinutes = double.Parse(config["ExpirationMinutes"] ?? "60");
});
```

### 2. Using IConfiguration Binding

```csharp
builder.Services.Configure<MiniJwtOptions>(
builder.Configuration.GetSection("MiniJwt"));

builder.Services.AddMiniJwt(options =>
{
// Options are bound from configuration automatically
});
```

### 3. Direct Configuration

```csharp
builder.Services.AddMiniJwt(options =>
{
options.SecretKey = "my-secret-key-at-least-32-bytes-long";
options.Issuer = "MyApp";
options.Audience = "MyClient";
options.ExpirationMinutes = 120;
});
```

### 4. Environment-Based Configuration

**appsettings.Development.json:**
```json
{
"MiniJwt": {
"SecretKey": "development-secret-key-at-least-32-bytes",
"Issuer": "MyApp-Dev",
"Audience": "MyClient-Dev",
"ExpirationMinutes": 1440
}
}
```

**appsettings.Production.json:**
```json
{
"MiniJwt": {
"SecretKey": "",
"Issuer": "MyApp",
"Audience": "MyClient",
"ExpirationMinutes": 60
}
}
```

**Program.cs (loading secret from environment):**
```csharp
builder.Services.AddMiniJwt(options =>
{
var config = builder.Configuration.GetSection("MiniJwt");

// Load secret from environment variable in production
options.SecretKey = Environment.GetEnvironmentVariable("JWT_SECRET_KEY")
?? config["SecretKey"];
options.Issuer = config["Issuer"];
options.Audience = config["Audience"];
options.ExpirationMinutes = double.Parse(config["ExpirationMinutes"] ?? "60");
});
```

## Multi-Tenant Configuration

For applications serving multiple tenants with different JWT configurations:

```csharp
public class TenantJwtService
{
private readonly Dictionary<string, IMiniJwtService> _services = new();

public TenantJwtService(IServiceProvider serviceProvider)
{
// Register services for each tenant
_services["tenant1"] = CreateServiceForTenant("tenant1", serviceProvider);
_services["tenant2"] = CreateServiceForTenant("tenant2", serviceProvider);
}

private IMiniJwtService CreateServiceForTenant(string tenantId, IServiceProvider sp)
{
var options = new MiniJwtOptions
{
SecretKey = GetSecretForTenant(tenantId),
Issuer = $"MyApp-{tenantId}",
Audience = $"MyClient-{tenantId}",
ExpirationMinutes = 60
};

return new MiniJwtService(
Options.CreateMonitor(Options.Create(options)),
sp.GetRequiredService<ILogger<MiniJwtService>>(),
new JwtSecurityTokenHandler { MapInboundClaims = false }
);
}

public IMiniJwtService GetServiceForTenant(string tenantId)
{
return _services.TryGetValue(tenantId, out var service)
? service
: throw new InvalidOperationException($"Unknown tenant: {tenantId}");
}
}
```

## Configuration Validation

MiniJwt.Core includes built-in validation that runs on startup:

- Validates that `SecretKey` is not empty
- Validates that `SecretKey` is at least 32 bytes for HS256
- Validates that `ExpirationMinutes` is positive

**Validation errors will prevent application startup** when using `ValidateOnStart()` (which is enabled by default when using `AddMiniJwt`).

## Dynamic Configuration Updates

MiniJwt.Core supports runtime configuration updates using `IOptionsMonitor<MiniJwtOptions>`:

```csharp
public class ConfigurationUpdateService : IHostedService
{
private readonly IOptionsMonitor<MiniJwtOptions> _optionsMonitor;
private IDisposable _listener;

public ConfigurationUpdateService(IOptionsMonitor<MiniJwtOptions> optionsMonitor)
{
_optionsMonitor = optionsMonitor;
}

public Task StartAsync(CancellationToken cancellationToken)
{
_listener = _optionsMonitor.OnChange(options =>
{
Console.WriteLine("JWT configuration updated!");
// MiniJwtService automatically picks up the changes
});
return Task.CompletedTask;
}

public Task StopAsync(CancellationToken cancellationToken)
{
_listener?.Dispose();
return Task.CompletedTask;
}
}
```

## Common Configuration Patterns

### Short-Lived Access Tokens

```csharp
options.ExpirationMinutes = 15; // 15 minutes
```

Use with a refresh token mechanism for secure, long-lived sessions.

### Development/Testing

```csharp
#if DEBUG
options.ExpirationMinutes = 1440; // 24 hours for easier debugging
#else
options.ExpirationMinutes = 60; // 1 hour in production
#endif
```

### API Gateway Integration

```csharp
options.Issuer = "https://api-gateway.company.com";
options.Audience = "microservice-a";
```

Each microservice can use the same issuer but different audiences.

## Next Steps

- Learn about [practical examples](examples.md)
- Read [security best practices](faq.md#security-best-practices)
- Explore [sample applications](../samples/)
Loading
Loading