Rig.TUnit.Security.Jwt 0.1.0-beta.2

This is a prerelease version of Rig.TUnit.Security.Jwt.

dotnet add package Rig.TUnit.Security.Jwt --version 0.1.0-beta.2

NuGet\Install-Package Rig.TUnit.Security.Jwt -Version 0.1.0-beta.2

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Rig.TUnit.Security.Jwt" Version="0.1.0-beta.2" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Rig.TUnit.Security.Jwt" Version="0.1.0-beta.2" />
                    

                            Directory.Packages.props

<PackageReference Include="Rig.TUnit.Security.Jwt" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Rig.TUnit.Security.Jwt --version 0.1.0-beta.2

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Rig.TUnit.Security.Jwt, 0.1.0-beta.2"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Rig.TUnit.Security.Jwt@0.1.0-beta.2

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Rig.TUnit.Security.Jwt&version=0.1.0-beta.2&prerelease
                    

                            Install as a Cake Addin

#tool nuget:?package=Rig.TUnit.Security.Jwt&version=0.1.0-beta.2&prerelease
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Rig.TUnit.Security.Jwt

Fluent JwtBuilder producing tokens a real JwtBearerHandler accepts — no test-only bypass. HS256 / RS256, kid rotation, negative builders.

What this package is

A JWT testing kit that produces tokens that pass through Microsoft's real JwtBearerHandler validation pipeline. Supports HS256 / RS256 signing, kid rotation, issuer/audience binding, and — critically — negative builders (BuildExpired, BuildNotYetValid, BuildTampered) so tests can prove the server rejects bad tokens rather than silently accepting them.

No AuthenticationScheme.AllowAnonymous bypass, no AuthorizeFilter override — the production auth code runs unchanged.

When to use it

Integration tests where an API requires a valid JWT.
Verifying negative paths: expired, tampered, not-yet-valid, wrong audience.
Kid-rotation testing for key-rollover scenarios.
Not for: unit tests of claims transformation — use a ClaimsPrincipal factory directly.

Prerequisites

.NET 10 SDK
Project under test uses Microsoft.AspNetCore.Authentication.JwtBearer.

Quick start

using Rig.TUnit.Security.Jwt.Builder;

var token = JwtBuilder.Create(new JwtBuilderOptions
                {
                    DefaultIssuer = "my-issuer",
                    DefaultAudience = "my-audience",
                })
            .Subject("alice")
            .Claim("role", "admin")
            .ExpiresIn(TimeSpan.FromMinutes(15))
            .SignedWithHs256(keyBytes)
            .Build();

Options

Property	Type	Default	Description
`DefaultIssuer`	`string`	`"rig.tunit"`	Issuer claim
`DefaultAudience`	`string`	`"test-audience"`	Audience claim
`DefaultTtl`	`TimeSpan`	`15m`	TTL when `ExpiresIn` not called
`DefaultAlgorithm`	`string`	`"HS256"`	Override in `SignedWith…`

Fixture + helper APIs

Rig.TUnit.Security.Jwt.Builder.JwtBuilder
Rig.TUnit.Security.Jwt.Options.JwtBuilderOptions
Rig.TUnit.Security.Jwt.Helpers.JwksKeyRotationHelper

Per-test isolation

Each JwtBuilder instance is standalone; no global state. Keys can be per-test via IsolationKey.FromExecutionContext() as seed material.

Parallelism + performance

HS256 signing: ~50 µs.
RS256 signing: ~2 ms (key generation dominant).
Safe under full parallelism.

Troubleshooting

Token rejected with IDX10503 (signature invalid) — the signing key and the handler's validation key don't match. Ensure TokenValidationParameters.IssuerSigningKey uses the same bytes.
BuildExpired token accepted — the handler's ClockSkew default is 5 minutes; BuildExpired(TimeSpan.FromMinutes(10)) clears that window.

See docs/troubleshooting.md#jwt.

Provider quirks + edge cases

kid rotation: JwksKeyRotationHelper.SetCurrentKid("new") updates the JWKS endpoint's active key; tokens signed with the old kid continue validating if the handler caches the full key set.
HS256 key material must be at least 256 bits (32 bytes); shorter keys are padded and the handler rejects them.
BuildTampered flips one bit of the signature — the resulting token round-trips the header/claims fine and fails only at signature check.

Benchmarks

See JwtBenchmarks.cs; baseline in benchmarks/baseline-005.json.

License

MIT. See LICENSE.

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- Bogus (>= 35.6.1)
- Microsoft.Extensions.Configuration (>= 10.0.0)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Options (>= 10.0.0)
- Microsoft.Extensions.Options.DataAnnotations (>= 10.0.0)
- Microsoft.IdentityModel.JsonWebTokens (>= 8.3.0)
- Microsoft.IdentityModel.Tokens (>= 8.3.0)
- Rig.TUnit.Security (>= 0.1.0-beta.2)
- System.IdentityModel.Tokens.Jwt (>= 8.3.0)
- TUnit.Core (>= 1.34.5)

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Rig.TUnit.Security.Jwt:

Package	Downloads
Rig.TUnit.All Meta-package containing every Rig.TUnit.* package. DISCOURAGED — prefer per-feature or per-stack meta-packages (Rig.TUnit, Rig.TUnit.Microservices).	87
Rig.TUnit.Security.OAuth TUnit fixture for OAuth flows (auth-code+PKCE, client-credentials) against an in-process IdentityServer or stub provider.	87
Rig.TUnit.Microservices Meta-package: Core + Mediator + Grpc + Outbox + Tracing + Jwt + Seq — the opinionated microservice testing kit.	79

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
0.1.0-beta.2	41	4/27/2026
0.0.0-alpha.0.14	51	4/26/2026