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

Break down the differences and relationships between JOSE, JWT, JWS, JWE, JWA, and JWK with clear explanations and examples.

If you've worked with modern authentication or secure data exchange, you've undoubtedly encountered JSON Web Tokens, or JWTs. However, if you dig deeper, you may encounter a series of confusing acronyms: JWS, JWE, JWK, JWA, and the umbrella term, JOSE. What do they all mean? How do they relate to each other?

It's easy to get lost, but these concepts are actually designed to work together in a logical system. Think of it like **a secure shipping company**. You have the package, the tamper-proof seal, the locked box, the keys, and the set of rules for how to handle everything. This article will unpack each of these components, trying to clarify their roles and how they come together to create the secure tokens we rely on.

## What Is JOSE (JSON Object Signing and Encryption)?

Let's start with the big picture: **JOSE**.

JOSE isn't a single technology you can install or a specific format. Instead, it's a **framework** or [a collection of IETF (Internet Engineering Task Force) standards](https://datatracker.ietf.org/wg/jose/documents/). Its purpose is to provide a standardized way to securely transfer [claims](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-claims) between parties.

Think of **JOSE as the entire shipping and logistics company**. It doesn't represent a single box or key, but rather the complete set of rules, tools, and specifications for shipping things securely. It defines how to create signed messages (JWS), encrypted messages (JWE), the keys to use (JWK), and the algorithms allowed (JWA).

The JOSE framework is composed of several key specifications, which we will explore next.

## JWS (JSON Web Signature)

[JWS](https://datatracker.ietf.org/doc/html/rfc7515) is a standard for signing data. Its primary goals are to ensure **integrity** and **authenticity**:

* **Integrity:** Guarantees that the data has not been tampered with in transit.  
* **Authenticity:** Verifies that the sender is who they claim to be.

A JWS object doesn't hide the data; it just adds a signature that the recipient can verify. It's like putting a letter in a clear envelope and sealing it with a unique, tamper-proof wax seal. Anyone can read the letter, but the seal proves it came from the right person and hasn't been opened.

A JWS object, or more simply a JWS, can be represented in a compact, URL-safe string composed of three parts, separated by dots (`.`):

![Diagram showing the three-part structure of a JWS (JSON Web Signature): a Base64Url encoded Header, Payload, and Signature, each separated by a dot.](https://images.ctfassets.net/23aumh6u8s0i/4mDvsqLEA5NtlrbD6hVap5/c6b0a8f7d4eb8ecd53188f9fa0969adb/jws-parts.png)  This representation is called [JWS Compact Serialization](https://datatracker.ietf.org/doc/html/rfc7515#section-7.1).

> A JWS can also be represented as a JSON object in two different flavors:  [General JWS JSON Serialization](https://datatracker.ietf.org/doc/html/rfc7515#section-7.2.1) and [Flattened JWS JSON Serialization](https://datatracker.ietf.org/doc/html/rfc7515#section-7.2.2). 

Here is an example of a JWS object represented through JWS Compact Serialization:

```shell
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```

Decoding each of these parts, you’ll get the following:

* **Header:** Metadata about the signature, such as the signing algorithm used:

```json
{
  "alg": "HS256",
  "typ": "JWT"
}
```

* **Payload:** The actual data being secured (the claims):

```json
{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}
```

* **Signature:** Created by signing the encoded header and payload with a secret key.

## JWE (JSON Web Encryption)

[JWE](https://datatracker.ietf.org/doc/html/rfc7516) is a standard for encrypting data. Its primary goal is **confidentiality**.

Unlike JWS, which leaves the data readable, JWE makes it unreadable to anyone without the correct keys. This is like putting your letter inside a locked metal box before shipping it. Only the person with the key can open it and see the contents.

A JWE object, or more simply a JWE, can also be represented in a compact string, but it has five parts separated by dots (`.`):

![Diagram illustrating the five-part structure of a JWE (JSON Web Encryption): JOSE Header, Encrypted Key, Initialization Vector, Ciphertext, and Authentication Tag.](https://images.ctfassets.net/23aumh6u8s0i/5iLpAkZozPYVkbQkxYFPfD/1e839dd26ce2637c2e52c9657b88efd5/jwe-parts.png)  This is the [JWE Compact Serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-3.1) representation. 

> As for a JWS, a JWE can also be represented as a JSON object in two different flavors:  [General JWE JSON Serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-7.2.1) and [Flattened JWE JSON Serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-7.2.2). 

Here is an example of the JWE Compact Serialization representation:

```shell
eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2v6GZfDqztYe70eG6o0f6ZlH5_yl1TjSGhbyT2KVdD2iM0ik2aO_hJAFy8uMwk2nN25OJaSqa1L58U9b2JTJmYnE9LzE6W1-nZz1tQ1tY4C8z4p2v6G.AxY8DCtDaGlsbGljb3RoZQ.KDlT9LgK3-tV3hVucpYh_g.GawgguFyGrWKav7AX4VKUg
```

Breaking it down, you will find the following parts:

* **JOSE Header:** Contains metadata about the encryption algorithms.  
* **JWE Encrypted Key:** The key used to encrypt the content, which itself is encrypted with the recipient's public key.  
* **JWE Initialization Vector:** A random value to ensure the encryption is unique. If an algorithm does not utilize an Initialization Vector, this value will be an empty octet sequence..  
* **JWE Ciphertext:** The encrypted payload.  
* **JWE Authentication Tag:** A value used to verify the integrity of the encrypted data. In case an algorithm does not use an Authentication Tag, this value will be an empty octet sequence.

## JWA and JWK

Now, both JWS and JWE use algorithms and keys to sign and encrypt data. How do they know *which* algorithms and *which* keys to use? That's where JWA and JWK come in. They represent the tools for sealing, locking, and unlocking in our metaphorical shipping company.

### JWA (JSON Web Algorithms)

[JWA](https://datatracker.ietf.org/doc/html/rfc7518) is simply a specification that defines the cryptographic algorithms that can be used for signing and encryption within the JOSE framework. It doesn't contain any code; it's a registry of identifiers.

For example, when the JWS header contains `"alg": "HS256"`, it's referring to the [HMAC](https://en.wikipedia.org/wiki/HMAC) algorithm using SHA-256 algorithm. Other examples include `"RS256"` for RSA signatures or `"A256GCM"` for [AES-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode) encryption.

### JWK (JSON Web Key)

[JWK](https://datatracker.ietf.org/doc/html/rfc7517) is a standard for representing cryptographic keys in a JSON format. Instead of passing around key files in different formats (like [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) or [DER](https://en.wikipedia.org/wiki/X.690#DER_encoding)), you can represent them as a JSON object. This is especially useful for web-based applications where JSON is the native language.

A JWK contains metadata about the key, such as its type, usage (signing or encryption), and the key values themselves.

Here is an example of an RSA Public JWK:

```json
{
  "kty": "RSA",
  "use": "sig",
  "kid": "my-rsa-key-1",
  "n": "u4V_...",
  "e": "AQAB"
}
```

*   
  `kty` (Key Type): Identifies the crypto family (e.g., "RSA", "EC").  
* `use` (Public Key Use): Defines the intended use (e.g., "sig" for signature, "enc" for encryption).  
* `kid` (Key ID): A unique identifier for the key, useful when an application has multiple keys.  
* `n` and `e`: The modulus and exponent values for the RSA public key.

### JWKS (JWK SET)

You may have heard about [JWKS](https://datatracker.ietf.org/doc/html/rfc7517#section-5). This is a standard specification to represent a set of JWK objects. The following is an example of JWKS object containing two JWK objects:

```json
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "n": "sySYvu...",
      "e": "AQAB",
      "kid": "MDc...",
    },
    {
      "kty": "RSA",
      "use": "sig",
      "n": "rxFxz...",
      "e": "AQAB",
      "kid": "_dqx...",
      "x5t": "IwL...",
      "x5c": [
        "MIIDAz..."
      ],
      "alg": "RS256"
    }
  ]
}
```

The JWKS object must have a `keys` member, which is an array of JWKs.

> Auth0 provides a JWKS endpoint for each tenant at `https://<YOUR-DOMAIN>/.well-known/jwks.json`. This endpoint returns the JWK objects associated with that specific tenant. Applications use this endpoint to dynamically fetch the public keys needed to verify JWTs issued by your Auth0 tenant.

## What About JWT?

Finally, we arrive at the most well-known acronym: [JWT (JSON Web Token)](https://datatracker.ietf.org/doc/html/rfc7519).

A JWT is **not** a new technology separate from the others. A JWT is a specific **type of payload** or a set of claims that is transported *using* JWS or JWE. It's the "what" that goes inside the secure container.

Referring once again to the metaphor of the shipping company, if JWS is the sealed envelope, the **JWT is the letter inside it**. The JWT standard defines a compact, self-contained way for representing information between two parties. It specifies a set of standard claim names like `iss` (issuer), `exp` (expiration time), `sub` (subject), and `aud` (audience).

Here is an example of a JWT Payload (Claims Set):

```json
{
  "iss": "https://my-auth-server.com",
  "sub": "user-123",
  "aud": "my-api",
  "exp": 1664532000,
  "name": "Jane Doe",
  "isAdmin": true
}
```

## Why Is a JWT Often Called a JWS or JWE?

This is the most common point of confusion. People often use "JWT" and "JWS" interchangeably. Is that correct?

Mostly, yes. A JWT is just the set of claims. To be useful, it must be securely transmitted. The way you make it secure is by signing it (creating a JWS) or encrypting it (creating a JWE).

* When you **sign** a JWT payload, the resulting token is technically a **JWS**. This is the most common form of JWT.  
* When you **encrypt** a JWT payload, the resulting token is technically a **JWE**.  
* It's also possible to have a **nested JWT**, where a JWT payload is signed (JWS) and then the entire JWS is encrypted (JWE).

So, when someone says "here is my JWT," they are almost always handing you a **JWS whose payload is a set of JWT claims**. The term "JWT" has become a colloquial shortcut for "a JWS containing JWT claims."

> You learned earlier that JWS and JWE objects can be represented as JSON objects. However, these representations can’t be used for JWTs. As [the specifications say](https://datatracker.ietf.org/doc/html/rfc7519#section-1), a JWT is always represented through JWS or JWE Compact Serialization.

## Recap

Although the JOSE acronyms may seem intimidating, the underlying concepts are actually distinct and logical once understood correctly. So, to summarize:

* **JOSE** is the overarching framework.  
* **JWS** and **JWE** are the secure containers—one is signed, the other is encrypted.  
* **JWA** and **JWK** are the tools—the algorithms and keys used to secure the containers.  
* **JWT** is the content—the standardized set of claims you put inside the container.

For your convenience, here is a summary table that recaps the differences between the items of the JOSE framework, including the references to the secure shipping company’s metaphor:

![A comparison table summarizing the JOSE framework. It defines JWT, JWS, JWE, JWK, and JWA, explaining the purpose and analogy for each specification.](https://images.ctfassets.net/23aumh6u8s0i/1a5zCuR79251Uk5c4JkTIa/98ab9ad626ded2850e3c5b0bed646746/jose-acronyms-table.png)

Demystifying JOSE, the JWT Family: JWS, JWE, JWA, and JWK Explained

0b3b0a5bf530f8c3a1fdee5233979c81?s=200 avatar

0b3b0a5bf530f8c3a1fdee5233979c81?s=200

Director, Engineering

Shawn Meyer

Learn how to start using RS256 for signing and verifying your JWTs.



## TL;DR:

When signing your JWTs it is better to use an asymmetric signing algorithm.  Doing so will no longer require sharing a private key across many applications. Using an algorithm like RS256 and the JWKS endpoint allows your applications to trust the JWTs signed by Auth0.

The code snippets below have been adapted from Auth0's [node-jwks-rsa](https://github.com/auth0/node-jwks-rsa) and [express-jwt](https://github.com/auth0/express-jwt).

Check out the sample [repository](https://github.com/sgmeyer/auth0-node-jwks-rs256).

> [Auth0 offers a generous **free tier**](https://auth0.com/pricing) to get started with modern authentication.

## RS256 vs HS256

 When creating clients and resources servers (APIs) in Auth0, two algorithms are supported for signing JSON Web Tokens (JWTs): RS256 and HS256.  HS256 is the default for clients and RS256 is the default for APIs.  When building applications, it is important to understand the differences between these two algorithms.  To begin, HS256 generates a symmetric MAC and RS256 generates an asymmetric signature.  Simply put HS256 must share a secret with any client or API that wants to verify the JWT.  Like any other symmetric algorithm, the same secret is used for both signing and verifying the JWT.  This means there is no way to fully guarantee Auth0 generated the JWT as any client or API with the secret could generate a validly signed JWT.  On the other hand, RS256 generates an asymmetric signature, which means a private key must be used to sign the JWT and a different public key must be used to verify the signature.  Unlike symmetric algorithms, using RS256 offers assurances that Auth0 is the signer of a JWT since Auth0 is the only party with the private key.

## Verifying RS256

Due to the symmetric nature of HS256, we favor the use of RS256 for signing your JWTs, especially for APIs with 3rd party clients.  However, this decision comes with some extra steps for verifying the signature of your JWTs.  Auth0 uses the [JWK](https://tools.ietf.org/html/rfc7517) specification to represent the cryptographic keys used for signing or verifying tokens.  This spec defines two high level data structures: JWKS and JWK.  Here are the definitions directly from the specification:

> JSON Web Key (JWK)
>
> A JSON object that represents a cryptographic key.  The members of the object represent properties of the key, including its value.

> JWK Set
>
> A JSON object that represents a set of JWKs.  The JSON object MUST have a "keys" member, which is an array of JWKs.

At the most basic level, the JWKS is a set of keys containing the public keys that should be used to verify any JWT issued by the authorization server.  Auth0 exposes a JWKS endpoint for each tenant, which is found at _https://your-tenant.auth0.com/.well-known/jwks.json_.  This endpoint will contain the JWK used to sign all Auth0 issued JWTs for this tenant.  Here is an example of the JWKS used by a demo tenant.

```
{
"keys": [
  {
    "alg": "RS256",
    "kty": "RSA",
    "use": "sig",
    "x5c": [
      "MIIC+DCCAeCgAwIBAgIJBIGjYW6hFpn2MA0GCSqGSIb3DQEBBQUAMCMxITAfBgNVBAMTGGN1c3RvbWVyLWRlbW9zLmF1dGgwLmNvbTAeFw0xNjExMjIyMjIyMDVaFw0zMDA4MDEyMjIyMDVaMCMxITAfBgNVBAMTGGN1c3RvbWVyLWRlbW9zLmF1dGgwLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMnjZc5bm/eGIHq09N9HKHahM7Y31P0ul+A2wwP4lSpIwFrWHzxw88/7Dwk9QMc+orGXX95R6av4GF+Es/nG3uK45ooMVMa/hYCh0Mtx3gnSuoTavQEkLzCvSwTqVwzZ+5noukWVqJuMKNwjL77GNcPLY7Xy2/skMCT5bR8UoWaufooQvYq6SyPcRAU4BtdquZRiBT4U5f+4pwNTxSvey7ki50yc1tG49Per/0zA4O6Tlpv8x7Red6m1bCNHt7+Z5nSl3RX/QYyAEUX1a28VcYmR41Osy+o2OUCXYdUAphDaHo4/8rbKTJhlu8jEcc1KoMXAKjgaVZtG/v5ltx6AXY0CAwEAAaMvMC0wDAYDVR0TBAUwAwEB/zAdBgNVHQ4EFgQUQxFG602h1cG+pnyvJoy9pGJJoCswDQYJKoZIhvcNAQEFBQADggEBAGvtCbzGNBUJPLICth3mLsX0Z4z8T8iu4tyoiuAshP/Ry/ZBnFnXmhD8vwgMZ2lTgUWwlrvlgN+fAtYKnwFO2G3BOCFw96Nm8So9sjTda9CCZ3dhoH57F/hVMBB0K6xhklAc0b5ZxUpCIN92v/w+xZoz1XQBHe8ZbRHaP1HpRM4M7DJk2G5cgUCyu3UBvYS41sHvzrxQ3z7vIePRA4WF4bEkfX12gvny0RsPkrbVMXX1Rj9t6V7QXrbPYBAO+43JvDGYawxYVvLhz+BJ45x50GFQmHszfY3BR9TPK8xmMmQwtIvLu1PMttNCs7niCYkSiUv2sc2mlq1i3IashGkkgmo="
    ],
    "n": "yeNlzlub94YgerT030codqEztjfU_S6X4DbDA_iVKkjAWtYfPHDzz_sPCT1Axz6isZdf3lHpq_gYX4Sz-cbe4rjmigxUxr-FgKHQy3HeCdK6hNq9ASQvMK9LBOpXDNn7mei6RZWom4wo3CMvvsY1w8tjtfLb-yQwJPltHxShZq5-ihC9irpLI9xEBTgG12q5lGIFPhTl_7inA1PFK97LuSLnTJzW0bj096v_TMDg7pOWm_zHtF53qbVsI0e3v5nmdKXdFf9BjIARRfVrbxVxiZHjU6zL6jY5QJdh1QCmENoejj_ytspMmGW7yMRxzUqgxcAqOBpVm0b-_mW3HoBdjQ",
    "e": "AQAB",
    "kid": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg",
    "x5t": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg"
  }
]}
```

**Note:** At the time of writing, Auth0 only supports a single JWK for token verification, however it is important to assume this endpoint could contain multiple JWKs.  As an example, multiple keys can be found in the JWKS when rotating signing certificates.

The JWKS above contains a single key.  Each property in the key is defined by the JWK specification [RFC 7517 Section 4](https://tools.ietf.org/html/rfc7517#section-4).  We will use these properties to determine which key was used to sign the JWT.  Here is a quick breakdown of what each property represents:

* **alg:** is the algorithm for the key
* **kty:** is the key type
* **use:** is how the key was meant to be used.  For the example above, `sig` represents signature verification.
* **x5c:** is the x509 certificate chain
* **e:**   is the exponent for a standard pem
* **n:**   is the moduluos for a standard pem
* **kid:** is the unique identifier for the key
* **x5t:** is the thumbprint of the x.509 cert (SHA-1 thumbprint)

## Verifying a JWT using the JWKS endpoint

Now that we understand JWKS and the specific properties of each JWK let's put this together and verify a JWT signed by Auth0 with RS256.  In our example we are going to build a first party API for our ficticious company c0der.io.  The API will have a single endpoint returning metadata about our API, which requires a valid JWT.  Ideally your resource server would also validate necessary scopes, however, that is beyond this topic.  We will assume an API and client have been created and we will focus on what happens once our API recieves a request.

**Here are the steps for validating the JWT:**

1. Retrieve the JWKS and filter for potential signature verification keys.
2. Extract the JWT from the request's authorization header.
3. Decode the JWT and grab the `kid` property from the header.
4. Find the signature verification key in the filtered JWKS with a matching `kid` property.
5. Using the `x5c` property build a certificate which will be used to verify the JWT signature.
6. Ensure the JWT contains the expected audience, issuer, expiration, etc.

> **Note:** There are many good libraries for verifying a JWT.  You can use the curated list to find one for your language at [JWT.io](https://jwt.io/#libraries-io).

Let's jump into some code and see this in action.

## Retrieving the JWK

The first thing we are going to do is grab the key set from the Auth0 JWKS endpoint.  Using `request` we can simply perform a `GET` to retrieve the JSON blob.

```javascript
/**
 * https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/lib/JwksClient.js#L7-L28
 **/

export class JwksClient {
  constructor(options) {
    this.options = { strictSsl: true, ...options };
  }

  getJwks(cb) {
    request({
      uri: this.options.jwksUri,
      strictSsl: this.options.strictSsl,
      json: true
    }, (err, res) => {
      if (err || res.statusCode < 200 || res.statusCode >= 300) {
        if (res) {
          return cb(new JwksError(res.body && (res.body.message || res.body) || res.statusMessage || `Http Error ${res.statusCode}`));
        }
        return cb(err);
      }

      var jwks = res.body.keys;
      return cb(null, jwks);
    });
  }
}

```

After grabbing the JWKS we will filter out all the keys that are not intended for verifying a JWT.  This step may seem unneccessary as the Auth0 JWKS endpoint typically contains a single signature verification key, however it is good practice to assume multiple keys could be present (i.e. key rotation).

```javascript
export class JwksClient {
  constructor(options) { ... }

  getJwks(cb) { ... }

  /**
   * https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/lib/JwksClient.js#L30-L58
   **/
  getSigningKeys(cb) {
    const callback = (err, keys) => {
      if (err) {
        return cb(err);
      }

      if (!keys || !keys.length) {
        return cb(new JwksError('The JWKS endpoint did not contain any keys'));
      }

      const signingKeys = keys
        .filter(key => key.use === 'sig' // JWK property `use` determines the JWK is for signature verification
                    && key.kty === 'RSA' // We are only supporting RSA (RS256)
                    && key.kid           // The `kid` must be present to be useful for later
                    && ((key.x5c && key.x5c.length) || (key.n && key.e)) // Has useful public keys
        ).map(key => {
          return { kid: key.kid, nbf: key.nbf, publicKey: certToPEM(key.x5c[0]) };
        });

      // If at least one signing key doesn't exist we have a problem... Kaboom.
      if (!signingKeys.length) {
        return cb(new JwksError('The JWKS endpoint did not contain any signature verification keys'));
      }

      // Returns all of the available signing keys.
      return cb(null, signingKeys);
    };

    this.getJwks(callback);
  }
}
```

Quick recap, we have retrieved the set of keys (JWKS) from Auth0 and we have filtered out all keys that are not intended for verifying a JWT with the keytype of RSA.  As an additional measure, we filtered out any key missing a public key and a `kid` property.  This step is important as later we will need to use the `kid` property to find the exact key necessary to verify the JWT.

## Finding the exact signature verification key

Continuing with our example, we will add an additional method to `JwksClient` called `getSigningKey` taking a key identifier (`kid`) as an argument and return the expected key (JWK) used to sign the JWT.   If a JWK is not found, then an error must be thrown.  This means the JWT supplied with the request was signed with a key that is not supported by Auth0.  This should ultimately be treated as a `401 Unauthorized`.  If a matching key is found, then that key will be passed as an argument to the callback.

```javascript
export class JwksClient {
  constructor(options) {
    this.options = { strictSsl: true, ...options };
  }

  getJwks(cb) { ... }

  getSigningKeys(cb) { ... }

  /**
   * https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/lib/JwksClient.js#L67-L84
   **/
  getSigningKey = (kid, cb) => {
    const callback = (err, keys) => {
      if (err) {
        return cb(err);
      }

      const signingKey = keys.find(key => key.kid === kid);

      if (!signingKey) {
        var error = new SigningKeyNotFoundError(`Unable to find a signing key that matches '${kid}'`);
        return cb(error);
      }

      return cb(null, signingKey)
    };

    this.getSigningKeys(callback);
  }
```

So far we have built a client that can be used to retrieve the JWKS and find the signature verification key using the value of the `kid` property.  At this point, we have neither verified the JWT nor extracted it from the request.  

> **Note:** As an optimization for production it would be wise to implement a caching mechanism for the JWKS or keys so that each request does not require a call to the JWKS endpoint.

## Creating a Signing Secret Wrapper

Before we move on to processing the JWT we want to create a quick wrapper for the `JwksClient` that returns a method that will eventually hand off the key we need to verify the JWT.  This class is a bit specific to the node async model, however it is necessary for the final step when we tie together the final middleware.

```javascript
/**
 * https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/lib/expressJwtSecret.js#L4-L38
 **/
const handleSigningKeyError = (err, cb) => {
  // If we didn't find a match, can't provide a key.
  if (err && err.name === 'SigningKeyNotFoundError') {
    return cb(null);
  }

  // Any other error we will bubble up.
  if (err) {
    return cb(err);
  }
};

export default (options) => {
  if (options === null || options === undefined) {
    throw new ArgumentError('An options object must be provided when initializing expressJwtSecret');
  }

  const client = new JwksClient(options);
  const onError = handleSigningKeyError;

  return function secretProvider(req, header, payload, cb) {
    // Only RS256 is supported.
    if (!header || header.alg !== 'RS256') {
      return cb(null, null);
    }

    client.getSigningKey(header.kid, (err, key) => {
      if (err) {
        return onError(err, (newError) => cb(newError, null));
      }

      // Provide the key.
      return cb(null, key.publicKey || key.rsaPublicKey);
    });
  };
};
```

## Grabbing the JWT from the Request

Now we need to move on to extract the JWT from the request.  Most APIs expect the JWT is sent as a [Bearer Token](https://tools.ietf.org/html/rfc6750) in the authorization header or as a URL parameter.  Now we are going to start building an Express middleware that will extract the JWT, create a signing secret, and verify the token using the `jsonwebtoken` module.  We will start by creating a file called `expressJWt.js` and extract the JWT from the request.

```javascript
export default (options) => {

  var middleware = (req, res, next) => {
    // https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/middleware/expressJwt.js#L12-L23
    var authHeader = req.headers.authorization;
    var parts = authHeader.split(' ');

    if (parts.length != 2) {
      throw new UnauthorizedError('credentials_required', { message: 'No authorization token was found' });
    }

    var scheme = parts[0];
    if(!/^Bearer$/i.test(scheme)) {

      throw new UnauthorizedError('credentials_bad_scheme', { message: 'Format is Authorization: Bearer [token]' });
    }
  }

  return middleware;
}

```

> **Note:** It is important to differentiate between verifying and decoding a token.  Decoding simply means to base64url decode the header and payload.  This step is not concerned with validating the signature, audience, expiration, etc.  Verifying the token is the process of ensuring the token's signature, but also the audience, expiration, etc are valid.

At this point the middleware is pretty boring.  It simply parses the authorization header for the format `Authorization: Bearer [token]`.  If the authorization header doesn't exist, is empty, or does not fit the format the we will throw an `UnauthorizedError` which later is treated as a `401 Unauthorized` response.  If the header does meet the criteria the JWT is pulled from the authorization header.

## Decoding the JWT

Now that we have our hands on the JWT we need to decode the token.  This will be important later when we want to grab the `kid` property to find the key we need to verify the signature.  Recall we can decode the JWT as it is simply base 64 url encoded.  To do this we will use the `jsonwebtoken` node module.  If you are interested in learning more about how a JWT is constructed check out our [blog post](https://auth0.com/blog/brute-forcing-hs256-is-possible-the-importance-of-using-strong-keys-to-sign-jwts/).

```javascript
export default (options) => {

  var middleware = (req, res, next) => {
    ...

    // https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/middleware/expressJwt.js#L25-L28
    var token = parts[1];

    // This could fail.  If it does handle as 401 as the token is invalid.
    var decodedToken = jwt.decode(token, {complete: true});
  }

  return middleware;
}

```

## Retrieving the Secret and Verifying the JWT

Now that we have the decoded token we have all the pieces we need to call get the JWKS and find the signature verification key.  First, we will use the `options.secret` to wrap our calls to `JwksClient` and assign it to `getSecret`.  Next, using the `jsonwebtoken` node module, we will verify the token.  Lastly, we will use `async.waterfall` to call `getSecret` and invoke `verifyToken` with the results of `getSecret`.  This will ultimately be used to verify the JWT.

```javascript
export default (options) => {

  var secretCallback = options.secret;

  var middleware = (req, res, next) => {
    ...

    // https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/middleware/expressJwt.js#L30-L58
    if (decodedToken.header.alg !== 'RS256') {
      // we are only supporting RS256 so fail if this happens.
      return cb(null, null);
    }

    var tasks = [
      function getSecret(callback) {
        secretCallback(req, decodedToken.header, decodedToken.payload, callback);
      },
      function verifyToken(secret, callback) {
        jwt.verify(token, secret, options, function(err, decoded) {
          if (err) {
            callback(new UnauthorizedError('invalid_token', err));
          } else {
            callback(null, decoded);
          }
        });
      }
    ];

    async.waterfall(tasks, (err, result) => {
      if (err) {
        return next(err);
      }

      set(req, _requestProperty, result);
      next();
    });
  }

  return middleware;
}

```

## Calling our middleware

Now that we have all the pieces in place to validate an RS256 token, we need to configure the middleware and apply it to the route.

```javascript
/**
 * https://github.com/sgmeyer/auth0-node-jwks-rs256/blob/master/src/middleware/jwtCheck.js#L8-L17
 **/

import expressJwt from './expressJwt';
import expressJwtSecret from '../lib/expressJwtSecret';

export const jwtCheck = expressJwt({
  secret: expressJwtSecret({
    jwksUri: `https://your-tenant.auth0.com/.well-known/jwks.json`
  }),

  // Validate the audience and the issuer.
  audience: 'https://api.c0der.io/v1/',
  issuer: `https://your-tenant.auth0.com/`,
  algorithms: ['RS256']
});

app.get('/meta', jwtCheck, api());

```

As you can see anytime we call the api's `/meta` endpoint a token will be verified.  This is where all of the pieces are pulled together.  Each time a request is made to `/meta` the JWT will be verified against the appropriate key in the JWKS.  Also, if the JWT passes signature verification the audience and issuer will be checked using `jsonwebtoken` module.

> Auth0 provides the simplest and easiest to use [user interface tools to help administrators manage user identities](https://auth0.com/user-management) including password resets, creating and provisioning, blocking and deleting users.

<include src="asides/Jwt" />

## Happy Coding

At this point we have seen an end to end sample for verifying a RS256 signed JWT.  This process not overly difficult, however it does add significant complexity as opposed to a symmetric algorithm like HS256.  Despite the added complexity it offers significant security benefits over HS256 and will surely pay off in the long run.  We highly recommend using RS256 as a means to sign your JWTs.

You can find the full sample on [GitHub](https://github.com/sgmeyer/auth0-node-jwks-rs256).


"jwk"