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
2 changes: 0 additions & 2 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,6 @@ updates:
update-types: ["version-update:semver-major"]
- dependency-name: "System.Security.Cryptography.Xml"
update-types: ["version-update:semver-major"]
# IdentityServer4 is EOL, see docs/Decisions/ADR-002-identityserver4-deprecated.md
- dependency-name: "IdentityServer4"
# Never reintroduce FluentAssertions (commercial license since v8), see docs/Dependencies/Known-Issues.md
- dependency-name: "FluentAssertions"

Expand Down
3 changes: 1 addition & 2 deletions .github/workflows/pull-request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,5 +36,4 @@ jobs:
- name: Check vulnerable packages
run: |
dotnet list package --vulnerable --include-transitive 2>&1 | tee vulnerable.txt
# IdentityServer4 is EOL with known advisories and is accepted on purpose (docs/Decisions/ADR-002)
! grep -E '^\s+>' vulnerable.txt | grep -v ' IdentityServer4 '
! grep -E '^\s+>' vulnerable.txt
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ dotnet list NetDevPack.Security.Jwt.sln package --vulnerable --include-transitiv

## Rules
- Package versions only in `Directory.Packages.props` (Central Package Management). Never add `Version=` to a csproj. Microsoft.* packages follow the TFM (10.0.x). See `docs/Dependencies/Policy.md`.
- NuGet Audit warnings NU1901-NU1904 are build errors. IdentityServer4 is the only deliberate exception (deprecated, ADR-002).
- NuGet Audit warnings NU1901-NU1904 are build errors, with no exceptions (IdentityServer4 was dropped, ADR-006).
- Commits: Conventional Commits (no local hook enforces it; semantic-release reads the messages). Use `chore(deps)` for dependency bumps. Breaking change = `feat!:` + `BREAKING CHANGE:` footer. semantic-release owns `CHANGELOG.md` and versions.
- Public API in `src/` is a NuGet contract. Treat changes to it as breaking.
- Encoding: UTF-8 with BOM + CRLF for C#/MSBuild files (enforced by `.editorconfig`). Never save files as UTF-16.
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ dotnet list NetDevPack.Security.Jwt.sln package --vulnerable --include-transitiv

## Rules
- Package versions only in `Directory.Packages.props` (Central Package Management). Never add `Version=` to a csproj. Microsoft.* packages follow the TFM (10.0.x). See `docs/Dependencies/Policy.md`.
- NuGet Audit warnings NU1901-NU1904 are build errors. IdentityServer4 is the only deliberate exception (deprecated, ADR-002).
- NuGet Audit warnings NU1901-NU1904 are build errors, with no exceptions (IdentityServer4 was dropped, ADR-006).
- Commits: Conventional Commits (no local hook enforces it; semantic-release reads the messages). Use `chore(deps)` for dependency bumps. Breaking change = `feat!:` + `BREAKING CHANGE:` footer. semantic-release owns `CHANGELOG.md` and versions.
- Public API in `src/` is a NuGet contract. Treat changes to it as breaking.
- Encoding: UTF-8 with BOM + CRLF for C#/MSBuild files (enforced by `.editorconfig`). Never save files as UTF-16.
Expand Down
2 changes: 0 additions & 2 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,6 @@

<ItemGroup>
<PackageVersion Include="System.IdentityModel.Tokens.Jwt" Version="8.23.0" />
<PackageVersion Include="IdentityServer4" Version="4.1.2" />
<PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />

<!-- Samples -->
<PackageVersion Include="Bogus" Version="35.6.5" />
Expand Down
41 changes: 3 additions & 38 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ It generates keys with RSA and ECDsa algorithms, which are the most recommended
| `NetDevPack.Security.Jwt.AspNetCore` | [![Nuget](https://img.shields.io/nuget/v/NetDevPack.Security.Jwt.AspNetCore)](https://www.nuget.org/packages/NetDevPack.Security.Jwt.AspNetCore) | `/jwks` endpoint and `JwtBearer` validation integration |
| `NetDevPack.Security.Jwt.Store.EntityFrameworkCore` | [![Nuget](https://img.shields.io/nuget/v/NetDevPack.Security.Jwt.Store.EntityFrameworkCore)](https://www.nuget.org/packages/NetDevPack.Security.Jwt.Store.EntityFrameworkCore) | Persist keys in a database |
| `NetDevPack.Security.Jwt.Store.FileSystem` | [![Nuget](https://img.shields.io/nuget/v/NetDevPack.Security.Jwt.Store.FileSystem)](https://www.nuget.org/packages/NetDevPack.Security.Jwt.Store.FileSystem) | Persist keys in a folder |
| `NetDevPack.Security.Jwt.IdentityServer4` | [![Nuget](https://img.shields.io/nuget/v/NetDevPack.Security.Jwt.IdentityServer4)](https://www.nuget.org/packages/NetDevPack.Security.Jwt.IdentityServer4) | ⚠️ **Deprecated** - IdentityServer4 key material |

> `NetDevPack.Security.Jwt.IdentityServer4` is **deprecated and no longer published**. IdentityServer4 reached end of life in 2022 and has known vulnerabilities. 11.0.0 was the last version; migrate to [Duende IdentityServer](https://duendesoftware.com/products/identityserver) or [OpenIddict](https://github.com/openiddict/openiddict-core).

### Supported frameworks

Expand Down Expand Up @@ -129,7 +130,6 @@ app.MapGet("/token", async (IJwtService jwtService) =>
- [Changing Algorithm](#changing-algorithm)
- [Jws](#jws)
- [Jwe](#jwe)
- [IdentityServer4 - Auto jwks\_uri Management](#identityserver4---auto-jwks_uri-management)
- [Why](#why)
- [Load Balance scenarios](#load-balance-scenarios)
- [Best practices](#best-practices)
Expand All @@ -141,7 +141,7 @@ app.MapGet("/token", async (IJwtService jwtService) =>
# 🛡️ What is


The JSON Web Key Set (JWKS) is a collection of public keys used for verifying JSON Web Tokens (JWTs) issued by an authorization server. This component's primary objective is to provide a centralized storage and key rotation for your JWKs while adhering to best practices in JWK generation. It features a plugin for IdentityServer4, enabling automatic rotation of the jwks_uri every 90 days and seamless management of your jwks_uri.
The JSON Web Key Set (JWKS) is a collection of public keys used for verifying JSON Web Tokens (JWTs) issued by an authorization server. This component's primary objective is to provide a centralized storage and key rotation for your JWKs while adhering to best practices in JWK generation.

If your API or OAuth 2.0 is deployed under a Load Balancer in Kubernetes or Docker Swarm, this component is essential. Its functionality is similar to the DataProtection Key in ASP.NET Core.

Expand Down Expand Up @@ -391,7 +391,6 @@ You can find several examples [here](samples):
| ------ | ------------- |
| [1_AspNet.Default](samples/1_AspNet.Default) | Minimal API generating/validating JWS and JWE with the default (DataProtection) store |
| [2_AspNet.Store.EntityFramework](samples/2_AspNet.Store.EntityFramework) | Same as above, persisting keys with EF Core |
| [3_IdentityServer4](samples/3_IdentityServer4) | ⚠️ Deprecated IdentityServer4 integration |
| [Microservice.Sample](samples/Microservice.Sample) | Identity API exposing `/jwks` + client API validating through `NetDevPack.Security.JwtExtensions` |

# Changing Algorithm
Expand Down Expand Up @@ -456,40 +455,6 @@ Encryption options
| Aes256CbcHmacSha512 | A256CBC-HS512 |


# IdentityServer4 - Auto jwks_uri Management

> ⚠️ **Deprecated.** IdentityServer4 reached end of life in 2022 and has known vulnerabilities ([GHSA-55p7-v223-x366](https://github.com/advisories/GHSA-55p7-v223-x366), [GHSA-ff4q-64jc-gx98](https://github.com/advisories/GHSA-ff4q-64jc-gx98)). The package is kept only for backward compatibility and will not receive new features. Consider migrating to [Duende IdentityServer](https://duendesoftware.com/products/identityserver) or [OpenIddict](https://github.com/openiddict/openiddict-core).

`NetDevPack.Security.Jwt` provides `IdentityServer4` key material. It auto generates and rotates the key.


First install
```
Install-Package NetDevPack.Security.Jwt.IdentityServer4
```

Or via the .NET command line interface:

```
dotnet add package NetDevPack.Security.Jwt.IdentityServer4
```

Go to `Startup.cs`

``` c#
public void ConfigureServices(IServiceCollection services)
{
var builder = services.AddIdentityServer()
.AddInMemoryIdentityResources(Config.GetIdentityResources())
.AddInMemoryApiResources(Config.GetApis())
.AddInMemoryClients(Config.GetClients());

services.AddJwksManager().IdentityServer4AutoJwksManager();
}
```

If you want to use a database, follow the [Database](#database) instructions instead.

# Why

When developing applications and APIs using OAuth 2.0 or simply signing a JWT, various algorithms are supported. Among these algorithms, some are considered best practices and superior to others, such as RSA-PSS (PS256) or Elliptic Curve (ES256). Certain Auth servers operate with deterministic algorithms, while others use probabilistic ones. Some servers, like Auth0, do not support multiple JWKs, but IdentityServer4 supports as many as you configure. This component is designed to abstract this layer and offer your application the current best practices for JWK management.
Expand Down
1 change: 1 addition & 0 deletions docs/00-Index.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,4 @@ Open the `docs/` folder as an Obsidian vault, or just read the Markdown on GitHu
- [[ADR-003-central-package-management]]
- [[ADR-004-remove-legacy-asymmetric-sample]]
- [[ADR-005-net10-only]]
- [[ADR-006-drop-identityserver4]]
3 changes: 1 addition & 2 deletions docs/Architecture/Overview.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
tags: [architecture]
updated: 2026-11-17
updated: 2026-11-18
---
# Overview

Expand All @@ -14,7 +14,6 @@ Library that **generates, stores, rotates and publishes** the keys used to sign
| `NetDevPack.Security.Jwt.AspNetCore` | `NetDevPack.Security.Jwt.AspNetCore` | `UseJwksDiscovery()` endpoint + `UseJwtValidation()` — see [[AspNetCore-Integration]] |
| `NetDevPack.Security.Jwt.Store.EntityFrameworkCore` | same | `PersistKeysToDatabaseStore<TContext>()` — see [[Stores]] |
| `NetDevPack.Security.Jwt.Store.FileSystem` | same | `PersistKeysToFileSystem(DirectoryInfo)` |
| `NetDevPack.Security.Jwt.IdentityServer4` | same | **Deprecated**, see [[ADR-002-identityserver4-deprecated]] |

Note: the Core *project* name differs from its *package id* (`NetDevPack.Security.Jwt`).

Expand Down
4 changes: 3 additions & 1 deletion docs/Decisions/ADR-002-identityserver4-deprecated.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
tags: [adr]
status: accepted
status: superseded
date: 2026-10-01
---
# ADR-002 — Keep IdentityServer4 package as deprecated
Expand All @@ -11,4 +11,6 @@ date: 2026-10-01

**Alternatives considered.** Removing it (breaks users). Migrating to Duende (commercial license, big scope). OpenIddict could get a future integration package.

**Superseded** by [[ADR-006-drop-identityserver4]] on 2026-11-18: the package is no longer built or published.

Related: [[Known-Issues]].
20 changes: 20 additions & 0 deletions docs/Decisions/ADR-006-drop-identityserver4.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
tags: [adr]
status: accepted
date: 2026-11-18
---
# ADR-006 — Stop publishing the IdentityServer4 package

**Context.** [[ADR-002-identityserver4-deprecated]] kept `NetDevPack.Security.Jwt.IdentityServer4` building and publishing for backward compatibility. Since [[ADR-005-net10-only]] every package targets .NET 10. IdentityServer4 4.1.2 was built for .NET Core 3.1, has been EOL since 2022 and has advisories that will never be fixed (GHSA-55p7-v223-x366, GHSA-ff4q-64jc-gx98). Keeping it meant the only `NU1902` suppression in the repo, an exception in the CI vulnerability check and a Dependabot ignore rule. It also kept shipping a new version of a package nobody should adopt.

**Decision.**
- Remove `src/NetDevPack.Security.Jwt.IdentityServer4` and `samples/3_IdentityServer4` from the repo and the solution. **11.0.0 is the last version.**
- Mark every version of the package as **deprecated** on nuget.org (reason: legacy, has critical bugs). Point users to `NetDevPack.Security.Jwt.AspNetCore` plus Duende IdentityServer or OpenIddict.
- NuGet Audit and the CI vulnerability check now run with no exceptions.

**Consequences.**
- Existing consumers keep working on ≤ 11.0.0, and NuGet shows them the deprecation warning.
- Not a breaking change for the other packages: the public API of `NetDevPack.Security.Jwt*` doesn't change, so this ships with no release (`chore:`).
- An integration for a maintained server (OpenIddict) can be a new package in the future.

Related: [[Known-Issues]], [[Policy]].
5 changes: 3 additions & 2 deletions docs/Dependencies/Known-Issues.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
tags: [dependencies, tech-debt]
updated: 2026-11-17
updated: 2026-11-18
---
# Known Issues / Tech Debt

## Dependencies
- **IdentityServer4 4.1.2**: EOL, moderate vulnerabilities (GHSA-55p7-v223-x366, GHSA-ff4q-64jc-gx98). `NU1902` is suppressed only in `NetDevPack.Security.Jwt.IdentityServer4` and `samples/3_IdentityServer4`. See [[ADR-002-identityserver4-deprecated]].
- None known. NuGet Audit runs with no exceptions.

## Code
- `JwtServiceValidationHandler` extends the legacy `JwtSecurityTokenHandler` and blocks on `Task.WaitAll(jwtService.GetLastKeys())`. Better: a `JsonWebTokenHandler` + async `IssuerSigningKeyResolver`, or set the keys in `OnMessageReceived`.
Expand All @@ -16,6 +16,7 @@ updated: 2026-11-17
- The `DataProtectionStore` fallback exception message still mentions the old `JwtSigningCredentials` package names.

## Resolved
- 2026-11-18: removed `NetDevPack.Security.Jwt.IdentityServer4` and `samples/3_IdentityServer4` ([[ADR-006-drop-identityserver4]]). IdentityServer4 4.1.2 (EOL, GHSA-55p7-v223-x366, GHSA-ff4q-64jc-gx98) is no longer a dependency, so the `NU1902` suppression and the CI exception are gone.
- 2026-11-17: dropped net8.0/net9.0 ([[ADR-005-net10-only]]). Migrated xunit 2 → **xunit.v3** on Microsoft.Testing.Platform; `Microsoft.NET.Test.Sdk`, `xunit.runner.visualstudio` and `coverlet.collector` removed. Fixed the xUnit1051 warnings in `AspNetCoreTests`.
- 2026-10-01: migrated FluentAssertions 8.11 (Xceed commercial license) → **AwesomeAssertions 9.6** (Apache-2.0 fork, same API, namespace `AwesomeAssertions`). Do not reintroduce FluentAssertions.
- 2026-10-01: 6 `.cs` files in UTF-16 LE (`CryptoService`, `IdentityServer4KeyStore`, `IdentityServerBuilderKeysExtensions`, `EFCoreServiceExtensions`, `ISecurityKeyContext`, `KeyMaterialMap`) were converted to UTF-8 BOM + CRLF. `.editorconfig` now enforces the encoding.
Expand Down
4 changes: 2 additions & 2 deletions docs/Dependencies/Policy.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
tags: [dependencies, policy]
updated: 2026-11-17
updated: 2026-11-18
---
# Dependency Policy

Expand All @@ -23,7 +23,7 @@ dotnet list NetDevPack.Security.Jwt.sln package --vulnerable --include-transitiv
3. `dotnet build -c Release` + `dotnet test -c Release` (see [[Build-Test]]).
4. Commit as `chore(deps): ...` (see [[Release]]).

Dependabot (`.github/dependabot.yml`) runs weekly and ignores majors for `Microsoft.*` and also ignores `IdentityServer4`.
Dependabot (`.github/dependabot.yml`) runs weekly and ignores majors for `Microsoft.*`.

## Adding a new TFM (e.g. net11.0)
1. `src/Directory.Build.props` `TargetFramework` → `TargetFrameworks` + every test/sample csproj.
Expand Down
3 changes: 1 addition & 2 deletions docs/Samples.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
tags: [samples]
updated: 2026-11-17
updated: 2026-11-18
---
# Samples (`samples/`)

Expand All @@ -10,7 +10,6 @@ All samples are in `src/NetDevPack.Security.Jwt.sln`, target net10.0 and use pro
| --- | --- |
| `1_AspNet.Default` | Minimal API: generate/validate JWS & JWE, `[Authorize]` endpoint. **Also the host for `AspNetCoreTests`.** Changing it can break tests |
| `2_AspNet.Store.EntityFramework` | Same, with `PersistKeysToDatabaseStore<DbExample>()` (SQLite/SQL Server) |
| `3_IdentityServer4` | Deprecated IdS4 integration ([[ADR-002-identityserver4-deprecated]]) |
| `Microservice.Sample/Identity` | Token issuer exposing `/jwks` (EF Core store) |
| `Microservice.Sample/Api.Sample` | Client API validating via NuGet `NetDevPack.Security.JwtExtensions` |

Expand Down
4 changes: 2 additions & 2 deletions docs/Workflows/Build-Test.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
tags: [workflow]
updated: 2026-11-17
updated: 2026-11-18
---
# Build & Test

Expand All @@ -20,4 +20,4 @@ dotnet pack -c Release -o ./out # 5 .nupkg + .snupkg, lib/net10.0
- Test projects: `NetDevPack.Security.Jwt.Tests` (about 514 tests) and `NetDevPack.Security.Jwt.AspNetCoreTests`.
- A test can be flaky, see [[Known-Issues]].

CI: `.github/workflows/pull-request.yml` runs restore, build, test and the vulnerability check (IdentityServer4 is the only accepted advisory, see [[ADR-002-identityserver4-deprecated]]).
CI: `.github/workflows/pull-request.yml` runs restore, build, test and the vulnerability check (no accepted advisories, see [[ADR-006-drop-identityserver4]]).
19 changes: 0 additions & 19 deletions samples/3_IdentityServer4/AspNet.IdentityServer4.csproj

This file was deleted.

26 changes: 0 additions & 26 deletions samples/3_IdentityServer4/Config.cs

This file was deleted.

20 changes: 0 additions & 20 deletions samples/3_IdentityServer4/Program.cs

This file was deleted.

28 changes: 0 additions & 28 deletions samples/3_IdentityServer4/Properties/launchSettings.json

This file was deleted.

Loading
Loading