Skip to content

Jwt.Net, a JWT (JSON Web Token) implementation for .NET

License

Notifications You must be signed in to change notification settings

jwt-dotnet/jwt

Repository files navigation

Build statusRelease status

Jwt.Net, a JWT (JSON Web Token) implementation for .NET

This library supports generating and decoding JSON Web Tokens.

Sponsor

Auth0 logoIf you want to quickly implement a secure authentication to your JWT project, create an Auth0 account; it's Free!

Avaliable NuGet packages

  1. Jwt.Net

NuGetNuGet Pre

  1. Jwt.Net for Microsoft Dependency Injection container

NuGetNuGet Pre

  1. Jwt.Net for ASP.NET Core

NuGetNuGet Pre

Supported .NET versions:

  • .NET Framework 3.5
  • .NET Framework 4.0 - 4.8
  • .NET Standard 1.3, 2.0
  • .NET 6.0

Jwt.NET

Creating (encoding) token

varpayload=newDictionary<string,object>{{"claim1",0},{"claim2","claim2-value"}};IJwtAlgorithmalgorithm=newRS256Algorithm(certificate);IJsonSerializerserializer=newJsonNetSerializer();IBase64UrlEncoderurlEncoder=newJwtBase64UrlEncoder();IJwtEncoderencoder=newJwtEncoder(algorithm,serializer,urlEncoder);conststringkey=null;// not needed if algorithm is asymmetricvartoken=encoder.Encode(payload,key);Console.WriteLine(token);

Or using the fluent builder API

vartoken=JwtBuilder.Create().WithAlgorithm(newRS256Algorithm(certificate)).AddClaim("exp",DateTimeOffset.UtcNow.AddHours(1).ToUnixTimeSeconds()).AddClaim("claim1",0).AddClaim("claim2","claim2-value").Encode();Console.WriteLine(token);

Parsing (decoding) and verifying token

try{IJsonSerializerserializer=newJsonNetSerializer();IDateTimeProviderprovider=newUtcDateTimeProvider();IJwtValidatorvalidator=newJwtValidator(serializer,provider);IBase64UrlEncoderurlEncoder=newJwtBase64UrlEncoder();IJwtAlgorithmalgorithm=newRS256Algorithm(certificate);IJwtDecoderdecoder=newJwtDecoder(serializer,validator,urlEncoder,algorithm);varjson=decoder.Decode(token);Console.WriteLine(json);}catch(TokenNotYetValidException){Console.WriteLine("Token is not valid yet");}catch(TokenExpiredException){Console.WriteLine("Token has expired");}catch(SignatureVerificationException){Console.WriteLine("Token has invalid signature");}

Or using the fluent builder API

varjson=JwtBuilder.Create().WithAlgorithm(newRS256Algorithm(certificate)).MustVerifySignature().Decode(token);Console.WriteLine(json);

The output would be:

{ "claim1": 0, "claim2": "claim2-value" }

You can also deserialize the JSON payload directly to a .NET type:

varpayload=decoder.DecodeToObject<IDictionary<string,object>>(token,secret);

Or using the fluent builder API

varpayload=JwtBuilder.Create().WithAlgorithm(newRS256Algorithm(certificate))         .WithSecret(secret).MustVerifySignature().Decode<IDictionary<string,object>>(token);

Validate token expiration

As described in the RFC 7519 section 4.1.4:

The exp claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.

If it is present in the payload and is past the current time, the token will fail verification. The value must be specified as the number of seconds since the Unix epoch, 1/1/1970 00:00:00 UTC.

IDateTimeProviderprovider=newUtcDateTimeProvider();varnow=provider.GetNow().AddMinutes(-5);// token has expired 5 minutes agodoublesecondsSinceEpoch=UnixEpoch.GetSecondsSince(now);varpayload=newDictionary<string,object>{{"exp",secondsSinceEpoch}};vartoken=encoder.Encode(payload);decoder.Decode(token);// throws TokenExpiredException

Then, as described in the RFC 7519 section 4.1.5:

The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing

If it is present in the payload and is prior to the current time, the token will fail verification.

Parsing (decoding) token header

IJsonSerializerserializer=newJsonNetSerializer();IBase64UrlEncoderurlEncoder=newJwtBase64UrlEncoder();IJwtDecoderdecoder=newJwtDecoder(serializer,urlEncoder);JwtHeaderheader=decoder.DecodeHeader<JwtHeader>(token);vartyp=header.Type;// JWTvaralg=header.Algorithm;// RS256varkid=header.KeyId;// CFAEAE2D650A6CA9862575DE54371EA980643849

Or using the fluent builder API

JwtHeaderheader=JwtBuilder.Create().DecodeHeader<JwtHeader>(token);vartyp=header.Type;// JWTvaralg=header.Algorithm;// RS256varkid=header.KeyId;// CFAEAE2D650A6CA9862575DE54371EA980643849

Turning off parts of token validation

If you'd like to validate a token but ignore certain parts of the validation (such as whether to the token has expired or not valid yet), you can pass a ValidateParameters object to the constructor of the JwtValidator class.

varvalidationParameters=newValidationParameters{ValidateSignature=true,ValidateExpirationTime=false,ValidateIssuedTime=false,TimeMargin=100};IJwtValidatorvalidator=newJwtValidator(serializer,provider,validationParameters);IJwtDecoderdecoder=newJwtDecoder(serializer,validator,urlEncoder,algorithm);varjson=decoder.Decode(expiredToken);// will not throw because of expired token

Or using the fluent builder API

varjson=JwtBuilder.Create().WithAlgorithm(newRS256Algorirhm(certificate)).WithSecret(secret).WithValidationParameters(newValidationParameters{ValidateSignature=true,ValidateExpirationTime=false,ValidateIssuedTime=false,TimeMargin=100}).Decode(expiredToken);

Custom JSON serializer

By default JSON serialization is performed by JsonNetSerializer implemented using Json.Net. To use a different one, implement the IJsonSerializer interface:

publicsealedclassCustomJsonSerializer:IJsonSerializer{publicstringSerialize(objectobj){// Implement using favorite JSON serializer}publicTDeserialize<T>(stringjson){// Implement using favorite JSON serializer}}

And then pass this serializer to JwtEncoder constructor:

IJwtAlgorithmalgorithm=newRS256Algorirhm(certificate);IJsonSerializerserializer=newCustomJsonSerializer();IBase64UrlEncoderurlEncoder=newJwtBase64UrlEncoder();IJwtEncoderencoder=newJwtEncoder(algorithm,serializer,urlEncoder);

Custom JSON serialization settings with the default JsonNetSerializer

As mentioned above, the default JSON serialization is done by JsonNetSerializer. You can define your own custom serialization settings as follows:

JsonSerializercustomJsonSerializer=newJsonSerializer{// All keys start with lowercase characters instead of the exact casing of the model/property, e.g. fullNameContractResolver=newCamelCasePropertyNamesContractResolver(),// Nice and easy to read, but you can also use Formatting.None to reduce the payload sizeFormatting=Formatting.Indented,// The most appropriate datetime format.DateFormatHandling=DateFormatHandling.IsoDateFormat,// Don't add keys/values when the value is null.NullValueHandling=NullValueHandling.Ignore,    // Use the enum string value, not the implicit int value, e.g. "red" for enum Color { Red }Converters.Add(newStringEnumConverter())};IJsonSerializerserializer=newJsonNetSerializer(customJsonSerializer);

Jwt.Net ASP.NET Core

Register authentication handler to validate JWT

publicvoidConfigureServices(IServiceCollectionservices){services.AddAuthentication(options =>{options.DefaultAuthenticateScheme=JwtAuthenticationDefaults.AuthenticationScheme;options.DefaultChallengeScheme=JwtAuthenticationDefaults.AuthenticationScheme;}).AddJwt(options =>{// secrets, required only for symmetric algorithms, such as HMACSHA256Algorithm// options.Keys = new[] { "mySecret" };// optionally; disable throwing an exception if JWT signature is invalid// options.VerifySignature = false;});// the non-generic version AddJwt() requires registering an instance of IAlgorithmFactory manuallyservices.AddSingleton<IAlgorithmFactory>(newRSAlgorithmFactory(certificate));// orservices.AddSingleton<IAlgorithmFactory>(newDelegateAlgorithmFactory(algorithm));// or use the generic version AddJwt<TFactory() to use a custom implementation of IAlgorithmFactory.AddJwt<MyCustomAlgorithmFactory>(options => ...);}publicvoidConfigure(IApplicationBuilderapp){app.UseAuthentication();}

Custom factories to produce Identity or AuthenticationTicket

services.AddSingleton<IIdentityFactory,CustomIdentityFctory>();services.AddSingleton<ITicketFactory,CustomTicketFactory>();

License

The following projects and their resulting packages are licensed under Public Domain, see the LICENSE#Public-Domain file.

  • JWT

The following projects and their resulting packages are licensed under the MIT License, see the LICENSE#MIT file.

  • JWT.Extensions.AspNetCore
  • JWT.Extensions.DependencyInjection
close