JSON Web Token for .Net

Provides support for JWT. This library aims to propose performant JWT primitives.

Packages

Package	Version	Description
JsonWebToken		Nuget package with JWT primitives. Use this package for common JWT usages.
JsonWebToken.OAuth2		Nuget package with OAuth2 & OIDC primitives. Use this package for more specifics usages like ID tokens, access tokens, state parameter, software statement, vector of trust or client assertion.
JsonWebToken.SecurityEventTokens		Nuget package with specifics SecEvents primitives.
JsonWebToken.KeyVault		Nuget package with Key Vault support. Use this package if your keys are stored into an Azure KeyVault.

Installation

Install the JsonWebToken NuGet Package.

Package Manager Console

Install-Package JsonWebToken -Version 1.9.3

For the latest beta version:

Install-Package JsonWebToken -Version 2.0.0-beta.4

.NET CLI

dotnet add package JsonWebToken

Usage

See the samples for more details.

The Jwt class is used for reading and validating tokens:

if(Jwt.TryParse("eyJhbGc[...]sWBedk", policy, out var jwt)
{
  // Use the JWT
  // ...
  // Then dispose the object
  jwt.Dispose();
}

The JwtWriter is used for writing tokens:

var writer = new JwtWriter();
var token = writer.WriteTokenString(descriptor);

JWT validation

var key = SymmetricJwk.FromBase64Url("R9MyWaEoyiMYViVWo8Fk4TUGWiSoaW6U1nOqXri8_XU");
var policy = new TokenValidationPolicyBuilder()
                .RequireIssuer("https://idp.example.com/", key, SignatureAlgorithm.HmacSha256)
                .RequireAudience("636C69656E745F6964")
                .Build();

if (Jwt.TryParse("eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MDAwMDcyMDAsImlhdCI6MjAwMDAwNzIwMCwiaXNzIjoiaHR0cHM6Ly9pZHAuZXhhbXBsZS5jb20vIiwiYXVkIjoiNjM2QzY5NjU2RTc0NUY2OTY0In0.YrrT1Ddp1ampsDd2GwYZoTz_bUnLt_h--f16wsWBedk", policy, out Jwt jwt))
{
    Console.WriteLine("The token is " + jwt);
}
else
{
    Console.WriteLine("Failed to read the token. Reason: " + Environment.NewLine + jwt.Error.Status);
}

// Do not forget to dispose the Jwt, or you may suffer of GC impacts
jwt.Dispose();

JWT creation

// Creates a symmetric key defined for the 'HS256' algorithm
var signingKey = SymmetricJwk.FromBase64Url("R9MyWaEoyiMYViVWo8Fk4TUGWiSoaW6U1nOqXri8_XU");

// Creates a JWS descriptor with all its properties
var descriptor = new JwsDescriptor(signingKey, SignatureAlgorithm.HmacSha256)
{
    Payload = new JwtPayload
    {
        { Claims.Iat, EpochTime.UtcNow },
        { Claims.Exp, EpochTime.UtcNow + EpochTime.OneHour },
        { Claims.Iss, "https://idp.example.com/" },
        { Claims.Aud, "636C69656E745F6964" }
    }
};
   

// Generates the UTF-8 string representation of the JWT
var writer = new JwtWriter();
var token = writer.WriteTokenString(descriptor);

Console.WriteLine("The JWT is:");
Console.WriteLine(descriptor);
Console.WriteLine();
Console.WriteLine("Its compact form is:");
Console.WriteLine(token);

Performances

See benchmarks for details. This library is about 12x faster than the Microsoft.IdentityModel.Tokens.Jwt when decoding and validating the token, with less than 5-10% memory allocation. (6x faster including signature validation or for encrypted tokens)

In case of invalid token, is is about 25x faster for detecting an invalid signature.

It is about 4x faster when writing a JWS of common size, with less than 1-2% memory allocation. (3x faster including signature generation, 5x faster for encrypted tokens)

The main reason of the efficiency of this library is the usage of the new API provided in .NET Core 2.0, 2.1 & 3.0, like the new Span API, the new JSON API, and the intrisics SIMD API.

Supported JWT

• Signed JWT (JWS). See sample.
• Nested encrypted JWT (JWE): JWE with JWS as payload (know as JWE or Encrypted JWS). See sample.
• Plaintext JWE: JWE with plaintext as payload. See sample.
• Binary JWE: JWE with binary as payload. See sample.
• Compressed JWE : JWE compressed with Deflate compression algorithm.
• Unsecure JWT: JWS without signature. See sample.

Supported algorithms

JWS signing algorithms

JWE encryption algorithms

JWE content encryption key algorithm