andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Learn how to validate a JSON Web Token (JWT) in different contexts using C# in .NET.

**JSON Web Tokens (JWTs)** have become very popular. Many developers use them in their applications for authentication and authorization purposes, but not all of them really know why and how to validate their JWTs.

This article will explain why you need to validate a JWT, what it means in general, and give you an overview of the many ways you can do it in the .NET platform.

## What Are JWTs?

If you landed on this article, you probably know what a JSON Web Token is. If not, [here is a great introduction to JWTs](https://jwt.io/introduction) and [a tool to decode them](https://jwt.io/#debugger-io).

Simply put, JSON Web Token is an [open standard](https://datatracker.ietf.org/doc/html/rfc7519) that defines how to share information between parties using the [JSON format](https://datatracker.ietf.org/doc/html/rfc8259). The [JWT structure](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-structure) consists of three concatenated Base64 url-encoded strings, separated by dots: the header, the payload, and the signature The information carried by a JWT is **digitally signed so you can verify its origin and trust it**. The digital signature also guarantees the integrity of the information, but it doesn't guarantee privacy unless explicitly encrypted.

Besides this, the JWT specification doesn't define the specific purpose of a token. While most developers think of authentication when dealing with JWTs, this is not an intrinsic property of tokens in the JWT format. JWT is just a format. The meaning of the token depends on the specific context or application.

For example, in the [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC) context, the JWT format is used for the ID token, which is the token that proves a user is authenticated. In the [OAuth 2.0](https://auth0.com/docs/authenticate/protocols/oauth) context, the [JWT format can optionally be used for the access token](https://datatracker.ietf.org/doc/html/rfc9068), which is the token that allows a client application to access a specific resource on behalf of the user.

> To learn more about ID and access tokens and their differences, you can read [this blog post](https://auth0.com/blog/id-token-access-token-what-is-the-difference/) or watch [this video](https://www.youtube.com/watch?v=vVM1Tpu9QB4) instead.

<include src="ebook-ads/JwtHandbook" />

## What Does Token Validation Mean?

The main purpose of a JWT is to carry information that the recipient can trust. So, the first thing your application needs to do when it receives a JWT is to ensure that the information it carries is trustworthy. This is where validation comes in.

In short, validating a JSON Web Token means ensuring that the token has the structure defined in the standard specification and that you can trust the information it carries.

The JWT validation is based on the following five criteria:

- **Token structure**. The first check is about the token's structure. Does the token match the structure of a JSON Web Token? If the token doesn't follow the standard guidelines, it's not valid.

- **Token integrity**. The next check is for the token's integrity. Has the token been tampered with? You can verify this by checking the signature. If you verify that the token's signature is valid, then it has not been altered in any way.
- **Token expiration**. JWTs have an expiration time defined in the `exp` claim. Is the token expired when it has been received? If a token has expired, you should no longer trust its contents.
- **Expected authority**. The next check is to verify that the token was issued and signed by the expected sender (authority). There are two steps to this check:
  - Verify that the authority is the one expected by your application by comparing it to the `iss` claim (issuer).
  - Verify that the key used to sign the JWT actually belongs to the expected authority.
- **Expected audience**. Finally,  verify that the token is intended for your application. In other words, you should check that the `aud` claim matches with the value that identifies your application. For example, in an ID token, the value for the audience is the client ID; in an access token in JWT format, the value for the audience is the [API identifier](https://auth0.com/docs/get-started/apis/api-settings#general-settings).

> To learn more about [digital signatures, read this article](https://auth0.com/blog/how-to-explain-public-key-cryptography-digital-signatures-to-anyone/). Check out [this article](https://auth0.com/blog/rs256-vs-hs256-whats-the-difference/) for the differences between the signing algorithms used in a JWT.

Token validation doesn't involve the custom information carried by the token. This is an application-specific logic, which is out of the scope of token validation. For example, validating an ID token does not include verifying that the user's email address in the `email` claim exists.

## Validate a JWT Using an Auth0 SDK

Now that you know what validating a JWT means, you are ready to learn how to validate your tokens in .NET.

Before jumping into the validation code, you should evaluate whether you really need to explicitly validate the JWTs you receive from an issuer like Auth0. Depending on the specific application, you may want to use an Auth0 SDK, which will take care of all the validation steps for you. For example, if you are developing an ASP.NET Core MVC application or a Blazor Server application, you can use the [Auth0 ASP.NET Core Authentication SDK](https://github.com/auth0/auth0-aspnetcore-authentication). This SDK will take care of the entire process of obtaining the JWT tokens for your application, including token validation. Check out [this article](https://auth0.com/blog/exploring-auth0-aspnet-core-authentication-sdk/) for an overview of this specific SDK.

So, if your application can benefit from an SDK, the best move is to write less code and get the JWT validation for free. Take a look at [this article to learn which Auth0 SDK is right for your .NET application type](https://auth0.com/blog/choose-the-right-dotnet-sdk-for-auth0/). 

## Using the ASP.NET Core Middleware

If, for some reason, you can't use an Auth0 SDK, you can configure your ASP.NET Core application by using two middleware:

- The [OpenIdConnect middleware](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.OpenIdConnect), which allows your ASP.NET Core web applications to authenticate users and get ID and access tokens via [OpenId Connect](https://openid.net/developers/how-connect-works/).
- The [JwtBearer middleware](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer), which enables your ASP.NET Core web API to handle access tokens.

Both middleware provide you with a convenient way to obtain and validate JWT tokens. The following code snippet shows an example of how to configure OpenIdConnect middleware:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);


builder.Services.AddAuthentication(options => {
    options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  })
  .AddCookie()
  .AddOpenIdConnect("Auth0", options => {
    options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";
    options.ClientId = builder.Configuration["Auth0:ClientId"];
    options.CallbackPath = new PathString("/callback");
  });

// ...other code...
```

The next example shows how to use the JwtBearer middleware:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
  .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
  {
    options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";
    options.Audience = builder.Configuration["Auth0:Audience"];
  });

// ...other code...
```

In both cases, by configuring the `Authority` option, you implicitly ask the middleware to validate your tokens. The middleware will use this value to retrieve the issuer's signing key, which is needed to validate the token's signature. All the other required validation steps are performed automatically. There is nothing else you need to do.

### Simplified configuration for the JwtBearer middleware

Starting with .NET 7, you can [use the JwtBearer middleware in a simplified way](https://auth0.com/blog/whats-new-in-dotnet-7-for-authentication-and-authorization/#Simplified-Configuration). You define your validation values in the `appsettings.json` file, as in the following example:

```json
// appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Authentication": {
    "Schemes": {
      "Bearer": {
        "Authority": "https://{DOMAIN}",
        "ValidAudiences": [ "{AUDIENCE}" ],
        "ValidIssuer": "{DOMAIN}"
      }
    }
  }
}
```

Then you can simply add the middleware to your ASP.NET Core application, as follows:

```csharp
// Program.cs

// ...existing code...

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication().AddJwtBearer();

// ...existing code...
```

The behavior is exactly the same as before but with much less code.

### Custom validation with the ASP.NET Core middleware

If you have specific needs, you can customize the JWT validation using the `TokenValidationParameters` option. For example, if you already have the issuer's public key stored on your file system, you can configure your middleware as shown in the following example:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
  .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
  {
    options.Audience = builder.Configuration["Auth0:Audience"];
    options.TokenValidationParameters = 
      new Microsoft.IdentityModel.Tokens.TokenValidationParameters
      {
        ValidateIssuer = true,
        ValidIssuer = $"{builder.Configuration["Auth0:Domain"]}",
        ValidateIssuerSigningKey = true,
        IssuerSigningKey = new X509SecurityKey(new X509Certificate2(certificateFilePath)),
        ValidateLifetime = true
      };
  });

// ...other code...
```

You can see that the `Audience` option is still there while the `Authority` option is missing. Instead of the `Authority` option, you find the `TokenValidationParameters` option, which is assigned an instance of the `TokenValidationParameters` class. The properties of this instance define what to check in order to complete the JWT validation. Specifically, you ask to validate the issuer (`ValidateIssuer`) and provide the value to match with (`ValidIssuer`). You ask to validate the issuer's signature (`ValidateIssuerSigningKey`) and provide the issuer's public signing key (`IssuerSigningKey`) embedded in a certificate stored in the file system. And finally, you ask to check the expiration time (`ValidateLifetime`).

You can see how removing the `Authority` option from the middleware configuration forces you to manually specify what to check in order to validate the token.

## Validate a JWT “By Hand”

In case you can't use the ASP.NET Core middleware, for example, when you are not developing a web application, don't get desperate. .NET gives you what you need, although this requires some effort on your side.

### Validate your token

First, you need to install the `Microsoft.IdentityModel.Tokens` package from NuGet:

```bash
dotnet add package Microsoft.IdentityModel.Tokens
```

This package provides everything you need for token manipulation, including validation, of course.

Have a look at the following function:

```csharp
public bool ValidateToken(
  string token, 
  string issuer, 
  string audience, 
  ICollection<SecurityKey> signingKeys,
  out JwtSecurityToken jwt
)
{
  var validationParameters = new TokenValidationParameters {
          ValidateIssuer = true,
          ValidIssuer = issuer,
          ValidateAudience = true,
          ValidAudience = audience
          ValidateIssuerSigningKey = true,
          IssuerSigningKeys = signingKeys,
          ValidateLifetime = true
  };

  try
  {
    var tokenHandler = new JwtSecurityTokenHandler();
    tokenHandler.ValidateToken(token, validationParameters, out SecurityToken validatedToken);
    jwt = (JwtSecurityToken)validatedToken;
    
    return true;
  } catch (SecurityTokenValidationException ex) {
    // Log the reason why the token is not valid
    return false
  }
}
```

This function takes a token and validates it by using the other parameters: the issuer, the audience, and the signing keys. If the token is valid, it returns `true` and provides a `JwtSecurityToken` instance representing the token as the `jwt` output parameter.

Once again, you see the `TokenValidationParameters` class, which allows you to define the validation criteria. This time there is no implicit validation. You need to specify all the required validation criteria and the valid values. Then you create a token handler (`JwtSecurityTokenHandler`) and use it to validate the token against the validation parameters. If the validation succeeds, you get an object representing the token, which you assign to the output parameter after casting to `JwtSecurityToken`. Finally, the function returns `true`.

If the validation fails, it should log the reason for the failed validation and return `false`.

### Get the signing keys

The `ValidateToken()` function expects you to pass the basic information for the token validation: the token issuer identifier, the audience, and the issuer's signing keys. You may have all this information on hand or need to retrieve some of it. For example, you can obtain the signing key of the issuer online. According to the [OIDC standard](https://openid.net/specs/openid-connect-discovery-1_0.html), you can find the set of keys (*JSON Web Key Sets*) to verify the issuer's signatures at a public and well-defined URL: `https://{DOMAIN}/.well-known/openid-configuration`.

Read [this document to learn more about the JSON Web Key Sets](https://auth0.com/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets).

To validate a JWT using the `ValidateToken()` function, you must first retrieve the signing key from this URL. As you can see, things start to get complex. This is why I suggest using an Auth0 SDK in the first place, or at least the ASP.NET Core middleware, if possible.

However, if using one of these tools is not feasible in your specific case, here is what you need to do to get the issuer's signing keys.

First, you need to install another package from NuGet: the `Microsoft.IdentityModel.Protocols.OpenIdConnect` package:

```bash
dotnet add package Microsoft.IdentityModel.Protocols.OpenIdConnect
```

This package provides you with the `ConfigurationManager` class, which helps you retrieve the JSON Web Key Sets. The following code shows you how to obtain the signing key of your JWT issuer:

```csharp
var configurationManager = new ConfigurationManager<OpenIdConnectConfiguration>(
  $"https://{builder.Configuration["Auth0:Domain"]/.well-known/openid-configuration}",
  new OpenIdConnectConfigurationRetriever(),
  new HttpDocumentRetriever());

  var discoveryDocument = await configurationManager.GetConfigurationAsync();
  var signingKeys = discoveryDocument.SigningKeys;
```

Once you have the signing keys, you are ready to use the `ValidateToken()` function.

## Recap

Throughout this article, you have learned what JWT validation is and why you need to do it. You also learned that as a .NET developer, you have many options for validating the JWTs your application receives: from a zero-code approach to an almost manual validation.

With the Auth0 SDKs, you get the JWT validation for free. No specific code is required. The SDKs validate tokens for you.

Using the ASP.NET Core middleware, OpenIdConnect and JwtBearer, you get implicit token validation in the default cases. However, you can customize your validation criteria if you are dealing with special cases.

In case you need full control over the validation process, you can rely on the `Microsoft.IdentityModel.Tokens` package for the JWT manipulation and validation and on the `Microsoft.IdentityModel.Protocols.OpenIdConnect` package for retrieving the issuer's signing keys.

Of course, the suggestion is to delegate as much as possible to the SDKs and middleware because the less code you write, the fewer bugs you may create 🙂.


How to Validate JWTs in .NET

001c9ddc5ceb9829b6aaf24f5d28502a

I am software developer with a keen interest in open-source technologies, Linux, and native development. I've worked on many different platforms Android, iOS, Win32, Linux, FreeRTOS, the Web, and others. I've gone through the whole stack and I enjoy learning and using the latest technologies. I now work as a full-stack developer at Auth0.

Senior Engineer

Sebastian Peyrott

We have released new versions of JWT.io and the JWT Debugger extension, learn what's new.



We have released another round of updates for our [JWT.io](https://jwt.io/) website and the JWT Debugger extensions ([Chrome](https://chrome.google.com/webstore/detail/jwt-debugger/ppmmlchacdbknfphdeafcbmklcghghmd), [Firefox](https://addons.mozilla.org/en-US/firefox/addon/jwtio-debugger)). Among the new features are [HMAC](https://en.wikipedia.org/wiki/HMAC) secret length hints, common claim descriptions, simplified library updates for the website, a share button for the website, support for plain RSA public keys, and more token types can be passed in the URL! In this post, we will go over these new features.

<include src="TweetQuote" quoteText="A new round of updates for JWT.io and the JWT Debugger extensions have been released!"/>

---

## JWT.io and the JWT Debugger extension
[JSON Web Tokens (JWTs)](https://jwt.io/introduction/) are a convenient way to exchange claims between parties. The key features of JWTs are their simple format (Base64-encoded JSON) and the use of signatures and/or encryption. [JWT.io](https://jwt.io/) provides a convenient way to debug and inspect [JSON Web Tokens (JWTs)](https://auth0.com/e-books/jwt-handbook), along with an introduction to some of the key concepts behind them. It also provides a list of libraries and frameworks that can be used with them in many different programming languages.

The JWT Debugger extensions ([Chrome](https://chrome.google.com/webstore/detail/jwt-debugger/ppmmlchacdbknfphdeafcbmklcghghmd), [Firefox](https://addons.mozilla.org/en-US/firefox/addon/jwtio-debugger)) are the [Web Extension](https://browserext.github.io/browserext/) versions of JWT.io. The debugger has the same features as the website but can be used offline. It also provides additional features like automatic inspection of web storage and cookies to easily find and edit JWTs in websites!

Now, let's go over the new features of this release!

## New Features
### HMAC Secret Length Hints
As [we have seen on our blog before](https://auth0.com/blog/brute-forcing-hs256-is-possible-the-importance-of-using-strong-keys-to-sign-jwts/), the length of the HMAC secret is one of the fundamental properties to ensure it cannot be brute forced. For this reason, we have added two hints:

- The default secret for all HMAC token examples now hints at the minimum required length.

![Default secret for HS256 example](https://images.ctfassets.net/23aumh6u8s0i/7bsOiqkha9rbIRXBIaeVhm/ffafe28856d614488a591a39dcdf4cbc/1-hmac-hint-1)

- When typing, a tooltip appears if the secret is too short to be considered safe.

<video src="https://cdn.auth0.com/blog/jwt-io-updates-2/2-hmac-hint-2.mp4" controls autoplay loop></video>

Do note, however, that length is not the only thing that is important for secrets. They must also be hard to guess, or, in other words, completely random.

### Share Button
A `share button` to easily pass tokens in URL form has been requested many times, and indeed, it was already available in the extension. Now it is also available on the website!

<video src="https://cdn.auth0.com/blog/jwt-io-updates-2/3-share-button.mp4" controls autoplay loop></video>

### Easy Library Updates
Since its inception, adding a new library to the library list at JWT.io has been a cumbersome process. Several [Pug](https://pugjs.org/) and CSS files needed to be edited. Furthermore, editing an existing library had its problems too: to change features one had to remember class names, for example. We have finally modernized the process. Now libraries are located in the `views/website/libraries` folder. There, you will find a JSON file for each language or framework. Inside the JSON file you'll see something like this:

```json
{
  "name": "Node.js",
  "uniqueClass": "node",
  "image": "/img/2.svg",
  "bgColor": "rgb(138, 194, 68)",
  "libs": [
    {
      "minimumVersion": "4.2.2",
      "support": {
        "sign": true,
        "verify": true,
        "iss": false,
        "sub": false,
        "aud": true,
        "exp": true,
        "nbf": false,
        "iat": false,
        "jti": false,
        "hs256": true,
        "hs384": true,
        "hs512": true,
        "rs256": true,
        "rs384": true,
        "rs512": true,
        "es256": true,
        "es384": true,
        "es512": true
      },
      "authorUrl": "https://github.com/auth0",
      "authorName": "Auth0",
      "gitHubRepoPath": "auth0/node-jsonwebtoken",
      "repoUrl": "https://github.com/auth0/node-jsonwebtoken",
      "installCommandHtml": "npm install jsonwebtoken"
    }
  ]
}
```

Multiple libraries go in the `libs` array. Most of the JSON file is self-explanatory, but some values are optional. For full details, check out the [README](https://github.com/jsonwebtoken/jsonwebtoken.github.io/blob/master/README.md) file.

To add a language or framework, a new JSON file must be created. The name of the file should start with a number, followed by a name, and end with `.json`. No further changes are required (other than editing the contents of the file).

It really is that simple!

### JWT.io as OpenID Connect Callback
One of the uses that JWT.io originally supported, was to be set as the callback for OpenID Connect operations (you can do this from the Auth0 Dashboard). That way, after a successful login, developers could be sent automatically to JWT.io with the returned token in the editor. This was disabled a long time ago during refactors. But now, that feature is back!

<video src="https://cdn.auth0.com/blog/jwt-io-updates-2/4-jwt-io-callback.mp4" controls autoplay loop></video>

The following URL parameters are recognized: `access_token`, `id_token`, `token`, and `value`.

<a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">Sign up for a free Auth0 account</a> to try this out!

### Common Claims Tooltips
In our previous update, we had enabled tooltips for dates in claims. This time, we have extended tooltips to also show a short description of what the claim means.

<video src="https://cdn.auth0.com/blog/jwt-io-updates-2/5-claims-tooltips.mp4" controls autoplay loop></video>

Of course, human-readable dates still work.

### Plain RSA Public Keys
Some RSA implementations work using the [old PEM-encoded RSA public key without the X.509 `SubjectPublicKeyInfo` header](https://stackoverflow.com/questions/18039401/how-can-i-transform-between-the-two-styles-of-public-key-format-one-begin-rsa) that is much more common nowadays. Unfortunately, old versions of JWT.io did not support these keys. But that's no longer the case! Plain RSA keys of yore are now supported, try it out!

<include src="TweetQuote" quoteText="The new round of features for JWT.io include: HMAC secret length hints, a share button, easy library updates, JWT.io as OIDC callback, common claim tooltips, and plain RSA pubkeys!"/>

## Other Changes
Of course, not every change in this release is related to new features. In this release, we have also:

- Merged **all PRs**.
- Added **6 new libraries** (thanks to external contributors!).
- Updates **12 libraries** (thanks again to external contributors!).
- Improved the [README file](https://github.com/jsonwebtoken/jsonwebtoken.github.io/blob/master/README.md).
- Implemented some **design changes**.
- Passed the **100 combined tests** mark!
- And fixed a good deal of bugs.

<include src="asides/Jwt" />

## What's Next
After all these changes, we will now let the codebase stabilize for a while. Of course, if you find any bugs, please report them in [the bug tracker](https://github.com/jsonwebtoken/jsonwebtoken.github.io/issues).

But that is not all! We are also thinking of more ways of improving JWT.io. Here are some of the ideas we are considering at the moment:

- Adding a button to clear the last saved token.
- Allowing the selection of different tokens passed in as URL parameters (`access_token` vs `id_token` for example).
- Support more algorithms, such as `ES512` or the [new EdDSA signatures](https://tools.ietf.org/html/rfc8037).
- Undock capability for the extensions (if possible).

What are your thoughts? Don't hesitate to tell us in the comments or by opening an enhancement request in the [bug-tracker](https://github.com/jsonwebtoken/jsonwebtoken.github.io/issues). Hack on!


Another Round of JWT.io and JWT Debugger Extension Updates

Learn the best practices for keeping your JWTs secure.

A Look at The Draft for JWT Best Current Practices



We have released a major update to our [JWT.io](https://jwt.io/) website and the [JWT Debugger](https://chrome.google.com/webstore/detail/jwt-debugger/ppmmlchacdbknfphdeafcbmklcghghmd) extension based on it. Among the new features, there are new signing algorithms, improved public-key handling, human-readable timestamps, and even [Firefox support](https://addons.mozilla.org/en-US/firefox/addon/jwtio-debugger) for the extension! In this post, we will go over these new features.

<include src="TweetQuote" quoteText="JWT.io and the JWT Debugger extension have been updated with new features!"/>

---

## JWT.io and the JWT Debugger extension
[JSON Web Tokens (JWTs)](https://jwt.io/introduction/) are a convenient way to exchange claims between parties. The key features of JWTs are their simple format (Base64-encoded JSON) and the use of signatures and/or encryption. [JWT.io](https://jwt.io/) provides a convenient way to debug and inspect [JSON Web Tokens (JWTs)](https://auth0.com/e-books/jwt-handbook), along with an introduction to some of the key concepts behind them. It also provides a list of libraries and frameworks that can be used with them in many different programming languages.

The [JWT Debugger extension](https://chrome.google.com/webstore/detail/jwt-debugger/ppmmlchacdbknfphdeafcbmklcghghmd) is the [Web Extension](https://browserext.github.io/browserext/) version of JWT.io. The debugger has the same features as the website but can be used offline. It also provides additional features like automatic inspection of web storage and cookies to easily find and edit JWTs in websites!

New versions of JWT.io and the JWT Debugger extension have been released. Let's go over the changes.

## New Features
### New Signing Algorithms
For a long time, JWT.io and the JWT Debugger extension only supported the two most popular algorithms: HS256 and RS256. HS256 is an HMAC-based algorithm that relies on a shared secret between parties to produce and verify signatures. On the other hand, RS256 is an RSA-based algorithm, relying on public and private key pairs to sign and verify signatures. The advantages of RS256 are clear: signatures can only be produced by the private-key holder, while verification can be performed by anyone holding the public key. However, the complexity of the implementation for RS256 can make HS256 signatures better for certain use cases (embedded, small devices, etc.).

![New algorithms](https://images.ctfassets.net/23aumh6u8s0i/1NaGCSea11eRFPXlrqP2EO/daed2abf80e328068b91d25647d6f087/1-new-algs)

The new version of JWT.io and the extensions support many more algorithms:

#### HMAC
- HS384
- HS512

These are variants of HS256. HMAC signatures rely on a hash function to produce and verify the signature. In the case of HS256, the hash function is SHA-256. For the other two, the hash functions are SHA-384 and SHA-512. For certain use cases, SHA-512 exhibits better performance than the other two. Security wise, none of these hash functions has been broken.

#### RSA
- RS384
- RS512
- PS256
- PS384

Much like the HMAC counterparts, RSA signatures also rely on a hash function to produce and verify a signature. The same thing changes between RS256, RS384, and RS512.

PS256/384 use a different type of signature (RSA-PSS) that also relies on the RSA algorithm as the baseline. In particular, it uses an encoding method that relies on a random salt value. This produces probabilistic rather than deterministic signatures. It is considered stronger than RS256/384/512 signatures as long as the random salt is truly random. In case the salt is not truly random, it provides the same level of strength as the baseline RSA algorithm

#### ECDSA
- ES256
- ES384

These algorithms rely on the elliptic-curve digital signing algorithm (ECDSA) rather than RSA. The main advantage of ECDSA is that keys can be smaller for a similar level of cryptographic strength. A 256-bit ECDSA key provides a cryptographic strength similar to a 3248-bit RSA key. This makes ECDSA keys better for certain hardware limited devices.

> If you are interested in a detailed rundown of JWT signing algorithms, don't forget to check our [JWT Handbook](https://auth0.com/e-books/jwt-handbook). Chapter 7 goes over all signing algorithms in detail.

#### "none"
JWTs also support setting the `alg` claim to `none`. This means that the JWT is not signed. Unfortunately, this has resulted in [critical vulnerabilities in JSON Web Token libraries](https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/). For this reason, JWT.io and the JWT Debugger extensions now consider `alg: "none"` tokens always _invalid_.

### Automatic Public-Key Download
Another interesting feature that has been added is automatic public key downloads. Public-key algorithms, such as RSA, RSA-PSS, and ECDSA, rely on public-keys to verify signatures. Public-keys, like their name implies, can be safely shared without compromising the security of the signature. For this reason, it is not uncommon for JWT public-keys to be available either embedded in the token itself, or in a public URL.

JWT.io and the JWT Debugger extensions now attempt to get public keys in different ways according to the claims embedded in the token.

If the token contains both the `iss` and `kid` claims, JWT.io will attempt to download the token from a specially crafted URL. For example:

```javascript
header: {
  kid: 1
},
payload: {
  iss: "https://username.auth0.com/"
}
```

In this case, JWT.io and the extensions will attempt to download the key with `kid = 1` from the special URL `https://username.auth0.com/.well-known/jwks.json`. This is a [common scheme used by Auth0](https://auth0.com/docs/jwks). In other words, all Auth0 JWTs can now be verified in JWT.io and the JWT Debugger extension by simply pasting the token!

<include src="TweetQuote" quoteText="With automatic key downloads, all Auth0 JWTs can now be verified in JWT.io and the JWT Debugger extension by simply pasting the token!"/>

Of course, since the JWK and JWS standards declare other common schemes for specifying keys, these are also supported: the `jwk`, `jku`, `x5c`, and `x5u` claims. These are used to either embed a key within the token (`jwk` and `x5c`) or to declare a URL to get the keys or certificates (`jku` and `x5u`). For example:

```javascript
header: {
  kid: 1,
  jku: "https://username.auth0.com/.well-known/jwks.json"
}
```

In this case, JWT.io and the extensions will attempt to download the key with `kid = 1` from the URL `https://username.auth0.com/.well-known/jwks.json` specified in the `jku` claim.

### Human Readable Timestamps
Several JWT claims are time-based. For instance, the `iat` claim specifies the exact time the JWT was issued at, the `exp` claim specifies the expiration time for the JWT, the `nbf` sets the time when the JWT becomes valid, etc. Unfortunately, these claims are based on the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time): they specify the number of seconds elapsed since January 1st, 1970. Understanding these values by simply looking at them is hard. For this reason, now JWT.io and the JWT Debugger extensions display a tooltip when the mouse hovers over a supported time claim.

![Human readable timestamps](https://images.ctfassets.net/23aumh6u8s0i/KAGGuSxmdUdMO3YeLBJfh/a21a8482154c72bf97bb527ed7b670b0/2-timestamps)

The supported claims are: `exp`, `iat`, `nbf`, `auth_time`, and `updated_at`.

### Firefox Support
Yes! It's finally here. Ever since the first release of the JWT Debugger extension for Chrome we have received requests for a Firefox version. Now it's here and supports all the features of the Chrome extension. [Get it here](https://addons.mozilla.org/en-US/firefox/addon/jwtio-debugger)!

![JWT Debugger on Firefox](https://images.ctfassets.net/23aumh6u8s0i/3oxA0AoIwuIHbRGmi2gcqh/eb843e039c0aa895d02963ecd0eabb51/3-firefox)

## Streamlined Codebase
Although the new features are the cool part of the release, we have also done a ton of internal work on both JWT.io and the extensions. In particular:

- We have closed over 40 issues and merged over 15 pull requests (some with more libraries!).
- We have synchronized the codebases of JWT.io and the JWT Debugger extensions to always get the latest features out to you, regardless of what you use more.
- We have updated all internal dependencies to the latest versions. This has fixed many bugs here and there and also improved the experience on mobile platforms.
- We have performed a major refactor to improve code quality and latencies during page load. JWT.io is now faster than ever!
- We have added more tests to our test suite. Do check that these pass before submitting new PRs!
- Build scripts are now simpler. Want to contribute? Doing so is as simple as:

Steps:

1. [Checkout from Git](https://github.com/jsonwebtoken/jsonwebtoken.github.io/).
2. `npm install`
3. `grunt`

That's it! You will now find JWT.io available on [http://localhost:8000](http://localhost:8000) and ready for your changes. The extension is also built but you'll need to load it manually in your browser, see the Chrome or Firefox docs for help with this. The resulting code can always be found in the `dist` folder. Send your PRs!

<include src="asides/Jwt" />

## What's Next
Although we have just finished with these changes, there's still more in our pipeline!

- **Key-length tips:** we will show you tooltips when your shared secrets are not long enough.
- **Share button:** the extensions already support this, now it's coming to JWT.io!
- **Library submission process:** we get tons of PRs with new libraries, we want to formalize the process and setup tools so that you can easily review any steps that are required to add your library to JWT.io

We hope you enjoy all the new features and changes at [JWT.io](https://jwt.io/) and the JWT Debugger extensions. Please report any bugs at the [GitHub repository](https://github.com/jsonwebtoken/jsonwebtoken.github.io/) and don't forget to leave us your comments or requests here or in the issue tracker at GitHub. Cheers!



JWT.io and JWT Debugger Extension Updates

Learn all about the different JWT signing algorithms and how to choose the correct one for your use case!



JSON Web Tokens are used in the industry more and more. The spec which defines them ([RFC7519](https://tools.ietf.org/html/rfc7519)) describes them as a compact, URL-safe means of representing claims between parties by encoding them as JSON objects which can be digitally signed or encrypted. There are several algorithms which take place in this process, we will explore some of the most common ones below. Read on!

For an in-depth introduction to JSON Web Tokens, download our **free JWT Handbook** below.

<include src="ebook-ads/JwtHandbook" />

## JSON Web Token
A JSON Web Token encodes a series of *claims* in a JSON object. Some of these claims have specific meaning, while others are left to be interpreted by the users. Common claims are:

- Issuer (iss)
- Subject (sub)
- Audience (aud)
- Expiration time (exp)
- Not before (nbf)
- Issued at (iat)
- JWT ID (jti)

Some of these claims are very common. The subject claim (sub) normally describes to whom or to which application the JWT is issued. The issued at claim (iat) can be used to store the time at which the JWT is created, thus allowing JWTs to be invalidated after a certain amount of time. Other custom claims can be added.

A JWT is usually complemented with a signature or encryption. These are handled in their own specs as [JSON Web Signature (JWS)](https://tools.ietf.org/html/rfc7515) and [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516).

A signature allows a JWT to be *validated* against modifications. Encryption, on the other hand, makes sure the content of the JWT is only readable by certain parties.

### JOSE header
Signed and encrypted JWTs carry a header known as the JOSE header (JSON Object Signing and Encryption). This header describes what algorithm (signing or encryption) is used to process the data contained in the JWT. The JOSE header typically defines two attributes: `alg` and `typ`.

- alg: the algorithm used to sign or encrypt the JWT
- typ: the content that is being signed or encrypted (usually 'JWT').

### Compact Representation
JWS also defines a *compact* representation for a signed JWT:

```
BASE64URL(UTF8(JWS Protected Header)) + '.' +
BASE64URL(JWS Payload) + '.' +
BASE64URL(JWS Signature)
```

The compact representation is basically the concatenation of the JOSE header, the JWT and the details of the signature. Each component is BASE64 encoded and separated by a single dot ('.').

This results in the typical JWT representation we find in the web:

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
```

[jwt.io](http://jwt.io) is an excellent playfield to test JWTs. Go to [http://jwt.io](http://jwt.io) and input the string above in the encoded field.

### Compact Representation for Encrypted JWTs
The compact representation for encrypted JWTs is somewhat different:

```
BASE64URL(UTF8(JWE Protected Header)) + '.' +
BASE64URL(JWE Encrypted Key) + '.' +
BASE64URL(JWE Initialization Vector) + '.' +
BASE64URL(JWE Ciphertext) + '.' +
BASE64URL(JWE Authentication Tag)
```

The ciphertext would normally contain a JWT.

Signed and encrypted JWTs are usually *nested*. That means that a signed JWT is first produced and then an encrypted version of the signed result is then created. This provides two benefits:

- The signature can't be stripped.
- The signature is private (can't be seen by others).

## Common JWT Signing Algorithms
Most JWTs in the wild are just signed. The most common algorithms are:

- HMAC + SHA256
- RSASSA-PKCS1-v1_5 + SHA256
- ECDSA + P-256 + SHA256

> The specs defines many more algorithms for signing. You can find them all in [RFC 7518](https://tools.ietf.org/html/rfc7518#section-3).

### HMAC algorithms
This is probably the most common algorithm for signed JWTs.

Hash-Based Message Authentication Codes (HMACs) are a group of algorithms that provide a way of signing messages by means of a shared key. In the case of HMACs, a cryptographic hash function is used (for instance SHA256). The strength (i.e. how hard it is to forge an HMAC) depends on the hashing algorithm being used.

The main objective in the design of the algorithm was to allow the combination of a key with a message while providing strong guarantees against tampering. Ad-hoc solutions (for example, appending the key to the message and then hashing the result) suffer from mathematical flaws that allow potential attackers to forge the signature. The HMAC algorithm is designed against that.

The algorithm per-se is quite simple (JavaScript pseudo-code with Node.js extensions):

```
// Key: Buffer with key, Message: Buffer with message
function hmacSha256(key, message) {
    // The algorithm requires the key to be of the same length as the
    // "block-size" of the hashing algorithm (SHA256 = 64-byte blocks).
    // Extension is performed by appending zeros.
    var fullLengthKey = extendOrTruncateKey(key);

    var outterKeyPad = 0x5c; // A constant defined by the spec.
    var innerKeyPad = 0x36; // Another constant defined by the spec.

    var outterKey = new Buffer(fullLengthKey.length);
    var innerKey = new Buffer(fullLengthKey.length);
    for(var i = 0; i < fullLengthKey.length; ++i) {
        outterKey[i] = outterKeyPad ^ fullLengthKey[i];
        innerKey[i] = innerKeyPad ^ fullLengthKey[i];
    }

    // sha256(outterKey + sha256(innerKey, message))
    // (Buffer.concat makes this harder to read)
    return sha256(Buffer.concat([outterKey, sha256(Buffer.concat([innerKey, message]))]));
}
```

HMACs are used with JWTs when you want a simple way for all parties to create and validate JWTs. Any party knowing the key can create new JWTs. In other words, with shared keys, it is possible for party to impersonate another one: HMAC JWTs do not provide guarantees with regards to the creator of the JWT. Anyone knowing the key can create one. For certain use cases, this is too permissive. This is where asymmetric algorithms come into play.

## RSA and ECDSA algorithms
Both RSA and ECDSA are asymmetric encryption and digital signature algorithms. What asymmetric algorithms bring to the table is the possibility of verifying or decrypting a message without being able to create a new one. This is key for certain use cases. Picture a big company where data generated by the sales team needs to be verified by the accounting team. If an HMAC were to be used to sign the data, then both the sales team and the accounting team would need to know the same key. This would allow the sales team to sign data and make it pass as if it were from the accounting team. Although this might seem unlikely, especially in the context of a corporation, there are times when the ability to verify the creator of a signature is essential. JWTs signed or encrypted with RSA or ECDSA provide this capability. A party uses its private key to sign a JWT. Receivers in turn use the public key (which must be shared in the same way as an HMAC shared key) of that party to verify the JWT. The receiving parties cannot create new JWTs using the public key of the sender.

Both RSA and ECDSA algorithms are more complex than HMAC. If you are interested in the gritty details, read [RFC 3447](https://tools.ietf.org/html/rfc3447) for RSA encryption, and the original [ECDSA paper](http://cs.ucsb.edu/~koc/ccs130h/notes/ecdsa-cert.pdf).

The main difference between RSA and ECDSA lies in speed and key size. ECDSA requires smaller keys to achieve the same level of security as RSA. This makes it a great choice for small JWTs. RSA, however, is usually faster than ECDSA. As usual, pick the one that best aligns with your requirements.

<include src="asides/Jwt" />

## Conclusion
JWTs are a convenient way of representing authentication and authorization claims for your application. They are easy to parse, human readable and compact. But the killer features are in the JWS and JWE specs. With JWS and JWE all claims can be conveniently signed and encrypted, while remaining compact enough to be part of every API call. Solutions such as session-ids and server-side tokens seem old and cumbersome when compared to the power of JWTs. If you haven't worked with these technologies yet, we strongly recommend you do so in your next project. You won't be disappointed.

<include src="TweetQuote" quoteText="JWTs are a convenient way of representing authentication and authorization claims for your application."/>


"json-web-token"