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

Dive deep into the common myths surrounding JSON Web Tokens (JWTs), from their security to their role as access tokens, and why they aren't a one-size-fits-all solution for session management.

JSON Web Tokens, or JWTs, are a cornerstone of modern application security and API protection. You've likely encountered them when implementing login flows, securing microservice communication, or working with standards like OAuth 2.0 and OpenID Connect. Their popularity, however, has given rise to a series of persistent myths and dangerous anti-patterns.

Many developers treat JWTs as a magical black box, leading to implementations that are either insecure or overly complex. Believing these myths can expose your application to significant vulnerabilities.

In this article, we will dissect and debunk five of the most common misconceptions about JWTs. By understanding what a JWT is&mdash;and what it isn't&mdash;you can leverage its power correctly and build more secure and robust systems.


**Ready to see JWTs in action?** Watch this quick video for a visual overview of how JSON Web Tokens work and why misconceptions around them are so common.
<iframe width="560" height="315" src="https://www.youtube.com/embed/Q53HnM3iVLg?si=9XWET4vBTMC4a-fg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Myth 1: A JWT Is Just Another Name for a Token

One of the most fundamental misunderstandings is that "token" and "JWT" are synonymous. While a JWT is a type of token, not all tokens are JWTs.

A "token" in the general sense is simply a piece of data that represents a fact, usually an authorization grant. Historically, many of these tokens have been **opaque strings**. An opaque token is a random, meaningless string from the client's perspective. It acts as a reference, like a ticket stub. To get any information from it (like who the user is or what permissions they have), the receiving server must make a call back to the issuing server. Here is an example of an opaque token:

```shell
w3VzBypV4S1zaYd1-390AFda9d1t3-A4fWsdr23as
```

In contrast, a JSON Web Token (JWT) is a **structured token**. As defined in [RFC 7519](https://tools.ietf.org/html/rfc7519), a JWT is a compact, URL-safe means of representing claims to be transferred between two parties. It's not opaque; it's a self-contained JSON object that is digitally signed or encrypted.

> To learn more about JWTs, check out the [JWT Handbook](https://auth0.com/resources/ebooks/jwt-handbook) and use [jwt.io](http://jwt.io) to decode them.

Because it's self-contained, a service that trusts the issuer can validate a JWT and use its claims without needing to contact the issuer. **This is the core benefit of JWTs: stateless, decentralized validation**.

## Myth 2: JWT and Access Token Are Interchangeable Terms

This myth often follows the first. In OAuth 2.0 terminology, an **access token** is a credential used by a client to access protected resources. The crucial detail is that the OAuth 2.0 specification *does not mandate a specific format* for access tokens. They can be opaque tokens, or they can be JWTs.

So, why the confusion? JWTs have become a very popular format for access tokens. The benefits are clear:

* A resource server (e.g., a web API application) can validate a JWT-based access token without calling the authorization server on every request. It just needs the issuer's public key to check the signature.  
* The token itself can carry essential data, such as the user ID and [permissions (scopes)](https://auth0.com/blog/permissions-privileges-and-scopes/), reducing the need for extra database lookups.

However, an authorization server could just as easily issue an opaque access token and require resource servers to validate it via an [introspection endpoint](https://datatracker.ietf.org/doc/html/rfc7662). This stateful approach offers a major benefit: the token can be revoked instantly.

As a takeaway, remember that an access token is a *concept*&mdash;a key that unlocks a door. A JWT is a *format* for that key. You can have an access token that is not a JWT, but you can't say a JWT is always an access token, as it could be an [ID token](https://auth0.com/blog/id-token-access-token-what-is-the-difference/) or used for other purposes.

## Myth 3: JWTs Are Vulnerable Because Their Payload Is Readable

As mentioned before, you can decode a JWT by using [jwt.io](http://jwt.io). The following screenshot shows the content of a test JWT:

![The jwt.io debugger showing the decoded header and payload of a sample JSON Web Token, demonstrating that the payload data is visible by default.](https://images.ctfassets.net/23aumh6u8s0i/m0lLoapwO9AvmrYuLOdi9/aabdf7590adc697c787b1d3aa433bbe5/jwt-decoder-online.png)

A common reaction upon seeing a JWT for the first time is alarm. "I can decode this\! The data is exposed\! JWT is an insecure format\!"

A standard JWT is normally signed. Its payload is simply Base64Url encoded, not encrypted. You can easily paste the payload into any Base64 decoder and read its contents.

This visibility is by design. The purpose of the signature on a JWT is to guarantee **integrity** and **authenticity**, not **confidentiality**. The signature ensures that:

1. The data has not been tampered with since it was signed.  
2. The token was genuinely created by the party holding the signing key.

You should **never** put sensitive or secret information in the payload of a JWT. If you need confidentiality, you must use [JWE (JSON Web Encryption)](https://auth0.com/docs/secure/tokens/access-tokens/json-web-encryption), which encrypts the payload.

## Myth 4: A Signature Makes a JWT Inherently Secure

The signature is the most critical security feature of a JWT, but it's not a silver bullet. A signature is only as strong as the processes around it. Believing that "it's signed, so it's safe" is a dangerous oversimplification.

For a signed JWT to be truly secure, you must:

- **Use a strong algorithm:** Always use strong signing algorithms like [`RS256` or `ES256`](https://auth0.com/blog/rs256-vs-hs256-whats-the-difference/). Critically, your validation library **must** prevent the "none" algorithm attack, where an attacker strips the signature and changes the `alg` header to `"none"`.  
- **Validate all relevant claims:** A valid signature only proves the token hasn't been modified. It doesn't mean the token is still usable. You must always validate the standard claims:  
   * `exp`: Is the token expired?  
   * `nbf`: Is the token being used before it's valid?  
   * `iss`: Was the token issued by the authority you trust?  
   * `aud`: Was this token intended for your service (the audience)?  
- **Protect your signing keys:** If an attacker steals your symmetric secret (`HS256`) or your private key (`RS256`), they can forge valid tokens for any user. Key management is paramount.  
- **Transmit securely:** Always transmit JWTs over a secure channel (HTTPS) to prevent man-in-the-middle attacks from stealing the token in transit.

A signature doesn't protect against token theft via [Cross-Site Scripting (XSS)](https://auth0.com/blog/cross-site-request-forgery-csrf/) or compromised client devices. It's one piece of a larger security puzzle.

## Myth 5: JWTs Are a Modern Replacement for Sessions

This is perhaps the most contentious and widely debated myth. Many tutorials present JWTs as the "modern" way to handle user sessions, replacing old-fashioned server-side sessions. This is a misleading and often harmful narrative.

Traditional server-side sessions store session data on the server and give the client a simple, opaque session ID (usually in an `HttpOnly` cookie). JWTs, when used for sessions, move this state to the client inside the token.

This "stateless" approach has a massive drawback for user sessions: **revocation is extremely difficult**.

* **You can't easily log a user out:** If a user clicks "log out," how do you invalidate their JWT? It remains valid until its expiration time.  
* **A compromised token is a lasting threat:** If a JWT is stolen, the attacker can use it until it expires. You have no immediate way to kill that session.

Workarounds like blocklisting tokens exist, but they reintroduce server-side state, defeating the primary purpose of using JWTs for statelessness in the first place. At that point, you've just built a more complicated version of traditional sessions.

JWTs excel for short-lived, transactional scenarios where statelessness is a key architectural driver (e.g., authorizing a request in a microservices mesh). For managing user login state, the ability to centrally manage and instantly revoke sessions often makes the "old-fashioned" server-side session model a safer and simpler choice.

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

## Myths at a Glance

When applied correctly, JSON Web Tokens are a powerful and useful specification. They provide a standard for creating self-contained, verifiable tokens ideal for stateless systems and inter-service communication.

However, understanding their limitations is just as important as knowing their benefits. Here is a quick recap of the myths analyzed in this article:

![A summary table debunking five common JWT myths, covering topics like JWT security, access tokens vs. JWTs, payload visibility, signature security, and session management.](https://images.ctfassets.net/23aumh6u8s0i/P4pyLFEAKbhF9OKDX4Ss3/74a24471de857f1b8465b79aa31ce9d7/jwt-myths-vs-reality.png)

By moving past these common myths, you can make more informed architectural decisions. Don't treat JWTs as a generic solution for all things authentication and session-related. Instead, see them as a specialized tool in your developer toolkit—one that is incredibly effective when used for the right job.

Five Myths About JWTs Debunked

joey devilla headshot 900px

I’m a Senior Developer Advocate at Auth0, and I like to work on various technologies. I’ve developed software for all sorts of platforms, from CD-ROM and the PalmPilot to my current area of focus, mobile phones, IoT devices, and AI. When I’m not looking for strange new platforms to write software for, I’m playing a strange old instrument — the accordion!

Senior Developer Advocate

Joey deVilla

peterfernandez_360

As an Architect, Consultant, and Engineer, I have more than 30 years of experience designing and developing secure and robust software solutions. When not helping teams deal with the complexities of Customer Identity, you can usually find me working behind the scenes, acting in or directing a show at my local theatre.

Peter Fernandez

Add personalization to your iOS/SwiftUI app with user info from the ID token, a JWT (JSON Web Token) that you’ll read with the Swift JWTDecode library.

In Part 1 of this tutorial, you created a SwiftUI-based iOS app that uses Auth0 for basic login and logout functionality. In this part, you’ll enhance your app by giving it the ability to read the user’s profile to display their photo, name, and email address when they’re logged in.

<include 
    src="LinkCard" 
    title="Calling a Protected API from an iOS Swift App" 
    link="https://auth0.com/blog/calling-protected-apis-from-ios-swift/" 
    description="Looking for a step-by-step guide to leveraging OAuth 2.0 when accessing protected APIs via an iOS app built with Swift? If you're integrating with Auth0, then this is everything you need to know!"     img="https://images.ctfassets.net/23aumh6u8s0i/5PC3nu1F68m8S3BmJFv9SN/e83487c6d89d72fb6a49155722959b1d/ios_hero_2021_2.jpeg"
/>

Once again, you can follow the text in this article, or if you prefer learning by video, you can follow the steps in this article’s companion video:

<iframe width="600" height="338" src="https://www.youtube.com/embed/xOBoLegDmTw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

> Look for the 🛠 emoji if you’d like to skim through the content while focusing on the build and execution steps.
> 
> The 📺 emoji highlights links to specific points in the video.


## Examine the ID Token

📺 [The _Examine the ID Token_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2008s)
 
If you look at the `.success` case of the `switch` statement in `ContentView`’s `login()` method, you’ll see these `print()` functions:

```swift
print("Credentials: \(credentials)")
print("ID token: \(credentials.idToken)")
```

These functions’ output will appear in Xcode’s Debug area:

![Xcode screenshot highlighting the Debug area.](https://images.ctfassets.net/23aumh6u8s0i/2Odv2P2CeeMGBoKSHNl3ly/2ba5ae37dbc5afafb94e82f95f41a722/debug_area.png)

> If the Debug area isn’t visible, open the _View_ menu and select _Debug Area_ → _Show Debug Area_ or use the keyboard shortcut _command-Shift-Y_.

You’ll see the contents of the `credentials` object and its `idToken` property, which should look similar to this:

```
Credentials: Credentials(accessToken: "<REDACTED>", tokenType: "Bearer", idToken: "<REDACTED>", refreshToken: nil, expiresIn: 2022-03-20 04:38:25 +0000, scope: Optional("openid profile email"), recoveryCode: nil)
ID token: eyJhbGciOiJSUzI1NiIsInR5cC...
```

The `credentials` object is a package of information that Auth0 sends to your app after authenticating a user. This information includes:

- **ID token:** Data that proves that the user has been authenticated.
- **Access token:** Data that gives a client application permission to access a specific resource to perform specific actions on the user’s behalf.
- **Refresh token:** Applications use this to get additional access tokens when the original access token expires without requiring the user to re-authenticate.
- **Scopes:** A set of [OpenID Connect (OIDC) scopes](https://auth0.com/docs/get-started/apis/scopes/openid-connect-scopes) — authorizations for access to details about the user — that Auth0 has granted to the app. Unless you specify otherwise, *Auth0.swift* defaults to requesting the following scopes when logging in a user:
	- `openid`: Authorization to use OIDC to verify the user's identity
	- `profile`: Authorization to access the user’s name information
	- `email`:  Authorization to access the user’s email address

> Want to know more about ID tokens and access tokens? We explain all in our article, [_ID Token and Access Token: What's the Difference?_](https://auth0.com/blog/id-token-access-token-what-is-the-difference/)
> 
> Want to know more about refresh tokens? See our article, [_What Are Refresh Tokens and How to Use Them Securely_](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/).

The piece of information that we’re most interested in (for this exercise) is the ID token.

When the `print()` function is used to output the contents of `credentials`, the values of the `idToken` and `accessToken` properties are replaced with the string `<REDACTED>` as a security measure. Malicious parties can use tools to capture the output of `print()` functions from production apps; this is why `Credentials` instances redact the values of their `idToken` and `accessToken` properties when printed.

Note that when we use the `print()` function to output `credentials.idToken` — the ID token itself — the value is _not_ redacted. That’s because this value is useful for debugging, which we’ll do in the next step.

> It’s fine to print the value of the ID token to the debug console while you’re learning about the authentication process or building the app. Make sure you remove `print()` statements — especially those that print sensitive information, such as the ID token — before putting them into production!


### What’s in the ID token?

📺 [The _What’s in the ID token?_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2118s)

To see what’s in the ID token, copy its value from the Debug area, go to Auth0’s [JWT.io site](https://jwt.io/) and paste that value into the _Encoded_ text area on the left side of the page. JWT.io will decode the ID token from its JWT form and display its decoded contents in the _Decoded_ area on the page’s right side:

![JWT.io and the decoded ID token.](https://images.ctfassets.net/23aumh6u8s0i/4sg6VirydfCzVVenH6LWil/174552abed55b4fe3d8100493c1510db/jwt.io_screenshot.png)

In the _Decoded_ area’s _Payload_ section, you’ll see the decoded user information from the ID token, including the data that we want the app to display: the user’s name, email address, and picture.

In the next step, we’ll give the app the same ID token-decoding capability as JWT.io’s.

> Auth0 has plenty of information about JWTs. In addition to the main [JWT.io page](https://jwt.io/), you should visit JWT.io’s [_Introduction to JSON Web Tokens_](https://jwt.io/introduction) and download our [free JWT Handbook](https://auth0.com/resources/ebooks/jwt-handbook).


## Get the User’s Information

📺 [The _Get the User’s Information_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2223s)

The app only “knows” whether the user is logged in or logged out in its current state. It also has information about the user’s identity encoded in the ID token. Let’s extract this user information — the *user profile* — and use it to display the user’s name, email address, and picture when the user is logged in. 

🛠 In `Profile`, add the following `import` statement before the `struct Profile` line:

```Swift
// [ 📄 Profile.swift ]

import JWTDecode

// [ More code here ]
```

🛠 In the `Profile` extension, replace the `// TODO: Implement the 'from()' method.` comment with this `from()` method. It uses a couple of methods from the newly-imported `JWTDecode` library:

```swift
// [ 📄 Profile.swift ]

// [ More code here ]

  static func from(_ idToken: String) -> Self {
    guard
      let jwt = try? decode(jwt: idToken),
      let id = jwt.subject,
      let name = jwt.claim(name: "name").string,
      let email = jwt.claim(name: "email").string,
      let emailVerified = jwt.claim(name: "email_verified").boolean,
      let picture = jwt.claim(name: "picture").string,
      let updatedAt = jwt.claim(name: "updated_at").string
    else {
      return .empty
    }

    return Profile(
      id: id,
      name: name,
      email: email,
      emailVerified: String(describing: emailVerified),
      picture: picture,
      updatedAt: updatedAt
    )
  }
  
// [ More code here ]
```

Given an ID token string, the `from()` function creates a `Profile` instance. If `from()` can extract claims — values about the user’s identity, which include their name, email address, and the URL for their picture — from the ID token, it returns a `Profile` instance with that information in its properties. Otherwise, it returns a `Profile` instance with empty properties.


## Display the User’s Information

📺 [The _Display the User’s Information_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2424s)

Now that there’s a way to extract information from an ID token, let’s put it to use. 

Since `userProfile` is marked with the `@State` attribute, it defines the user interface’s state. Whenever `userProfile` or one of its properties changes, the app redraws the user interface to reflect the change.

We want to display the user’s information when they log in, so we’ll use `Profile`’s newly-created `from()` method in the `login()` method.

🛠 Open `ContentView` and update `login()` as shown below:

```swift
// [ 📄 ContentView.swift ]

// [ More code here ]

  func login() {
    Auth0 // 1
      .webAuth() // 2
      .start { result in // 3
        switch result {
          // 4
          case .failure(let error):
            print("Failed with: \(error)")
          // 5
          case .success(let credentials):
            self.isAuthenticated = true
            // 👇🏽👇🏽👇🏽 New line of code here!
            self.userProfile = Profile.from(credentials.idToken)
            // 👆🏽👆🏽👆🏽
            print("Credentials: \(credentials)")
            print("ID token: \(credentials.idToken)")
        }
      }
  }

// [ More code here ]
```

The newly-added line of code runs after the user logs in, and the app receives the ID token. It creates a new `Profile` instance from the data in the ID token and sets `ContentView`’s `userProfile` property to that instance.

When the user logs out, we should clean up the user profile just to be safe.

🛠 Update `logout()` as shown below:

```swift
// [ 📄 ContentView.swift ]

// [ More code here ]

  func logout() {
    Auth0
      .webAuth()
      .clearSession { result in
        switch result {
          case .success:
            self.isAuthenticated = false
            // 👇🏽👇🏽👇🏽 New line of code here!
            self.userProfile = Profile.empty
            // 👆🏽👆🏽👆🏽

          case .failure(let error):
            print("Failed with: \(error)")
        }
      }
  }

// [ More code here ]
```


## Run the App Again

📺 [The _Run the App Again_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2566s)

Run the app and confirm that the changes work. When you log in, you should see the user’s name, email address, and picture:

![The app’s “logged in” screen, featuring the text “Logged in” and displaying the user’s picture, name, and email address.](https://images.ctfassets.net/23aumh6u8s0i/1zYLUYAU3fdbLLde9PmhCN/90854331950e7557fbcc52db5bcb7379/logged_in_screen.png)

Congratulations, and high-fives and handshakes all around! You’ve taken a SwiftUI app and given it the ability to authenticate users with Auth0.


## Next Steps

SwiftUI is an expansive topic; we only scratched its surface in this tutorial. For your next steps in exploring it, you might want to look at these valuable resources:

- [SwiftUI by Example](https://www.hackingwithswift.com/quick-start/swiftui)
- [Your First SwiftUI App](https://www.youtube.com/watch?v=VlhcNR7Qrno)
- [Stanford University’s “Developing Applications for iOS” course for Spring 2021](https://www.youtube.com/playlist?list=PLpGHT1n4-mAsxuRxVPv7kj4-dQYoC3VVu)

📺 Last but not least, the video ends with [closing remarks and a quick accordion number](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2645s)!

Get Started with iOS Authentication using SwiftUI, Part 2: User Info, ID Tokens, and JWTs

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

500x500

I'm a software engineer, but I prefer to call myself Technology Bishop. Spreading knowledge through writing is my mission.

Software Engineer

Antonello Zanini

Learn why your site needs protection from bots and how CAPTCHAs and JS challenges can help

Bot is short for “robot,” and bots are applications that perform automated actions on the Internet. Although not all bots are bad, most have malicious purposes, from stealing sensitive information to attempting unauthorized access. Thus, bots can represent a security threat to any website. For this reason, you should consider “antibot” solutions to protect your site from bots.

An effective way to protect against these bot attacks is to adopt CAPTCHAs and JS challenges, two of the most effective and popular antibot technologies available. In this article, you will learn what CAPTCHAs and JS challenges are, how they work, and how you can use them to protect your website from bots.

## Why You Need Bot Protection

A bot is a software application that performs automated tasks on the Web. Bots are specifically designed to automate tasks that would otherwise require human intervention or interaction. According to [Statista](https://www.statista.com/statistics/1264226/human-and-bot-web-traffic-share/), bots accounted for 42.3% of worldwide Web traffic in 2021. So, we really cannot ignore them.

The term "bot" generally has a negative connotation, but not all bots are bad. For example, search engines use bots to crawl the Internet. In this regard, you might have already heard about [GoogleBot](https://developers.google.com/search/docs/crawling-indexing/googlebot). In addition, bots are used to collect data for analysis and keep track of important metrics, such as the uptime of a website.

At the same time, there are also bad bots. These perform malicious actions, such as [scraping](https://en.wikipedia.org/wiki/Web_scraping) sensitive data, spamming, and slowing down target websites with excessive requests. Unfortunately, malicious bots have become increasingly popular, and we have all come across a spam bot at least once on YouTube comments or Reddit posts. 27.7% of web traffic is due to bad bots.

For this reason, you need to protect your site from malicious bots. Bot protection involves techniques, technologies, and approaches to identify and block unwanted bots. With bot protection, you try to ensure that only human users and good bots can access your website, improving the general user experience.
On the contrary, a website without bot protection is vulnerable to spam and [DoS attacks](https://en.wikipedia.org/wiki/Denial-of-service_attack), which could damage your site's reputation and lead to reduced performance.

Bot protection can be implemented in several ways and include many techniques such as [blocking IPS](https://en.wikipedia.org/wiki/IP_address_blocking) based on their reputation, [device fingerprinting](https://en.wikipedia.org/wiki/Device_fingerprint), and [behavioral analysis](https://en.wikipedia.org/wiki/User_behavior_analytics). Specifically, two of the most effective and widely adopted antibot solutions are CAPTCHAs and JavaScript challenges.

Let’s now learn more about them.

## What Is a CAPTCHA?

CAPTCHA stands for "Completely Automated Public Turing test to tell Computers and Humans Apart" and represents a challenge-response test used to determine whether a user is human. In other terms, a CAPTCHA typically involves a simple challenge that users must solve to gain access.

CAPTCHAs block automated systems, such as bots, from performing some actions on a website. Thus, CAPTCHAs are particularly effective in limiting spam and preventing non-human users from accessing specific resources or web pages.

## How Do CAPTCHAs Work?

CAPTCHAs work by presenting users with a test that is easy for humans to pass but difficult for computers to solve. This way, they can distinguish between human users from automated bots.

There are different types of CAPTCHA based on the challenge presented to users. The most common ones are:

- **One-click CAPTCHA**: Asks the user to click a checkbox to verify that they are not a bot. It works by tracking the user's mouse movements to check whether it resembles human activity.

![An example of one-click CAPTCHA from reCAPTCHA](https://images.ctfassets.net/23aumh6u8s0i/7xC30RaTUMa0Ak5K1qHl83/b4fd55673099eabc13aa5aac3a1910cd/01-captcha.png)

- **Text-based CAPTCHA**: Shows an image of distorted text and asks the user to enter the text correctly into an input field.

![A text-based CAPTCHA from SimpleCaptcha](https://images.ctfassets.net/23aumh6u8s0i/1BhHogUF9KNhzzVmEuDden/1a66f70cfa8ae2e272d6b3843e5fb3ac/02-captcha.png)

- **Image-based CAPTCHA**: It shows several images to the user and asks them to select only those of a specified type.

![An image-based CAPTCHA from reCAPTCHA](https://images.ctfassets.net/23aumh6u8s0i/4MqWffkvau8BEVMYUZAN0b/ea0530ab70eabaa218df500199f74420/03-captcha.png)

- **Audio-based CAPTCHA**: It requests the user to listen to a sequence of numbers or letters and enter it correctly into a text field.

![An audio-based CAPTCHA from reCAPTCHA](https://images.ctfassets.net/23aumh6u8s0i/6leTUXVi0qMRv0f0irbMVT/f02523b21ca36167cb17017d8bbb90b1/04-captcha.png)

Note that most CAPTCHA examples above come from [Google reCAPTCHA](https://www.google.com/recaptcha/about/). If you are unfamiliar with it, Google reCAPTCHA is a free service that provides effective CAPTCHAs to prevent automated software from engaging in abusive activities on your website. reCAPTCHA is one of the most popular CAPTCHA providers because it is free to use, easy to implement, and highly effective. Another popular CAPTCHA provider is [hCaptcha](https://www.hcaptcha.com/).

## CAPTCHAs: Pros and Cons

Let’s now dig into the pros and cons of CAPTCHAs as an effective bot protection solution.

### Pros

- **Most online providers offer them**: Many CDNs ([Content Delivery Network](https://en.wikipedia.org/wiki/Content_delivery_network)s) and web hosting providers allow CAPTCHA integration with a few clicks as part of their bot protection offer.
- **Users are used to dealing with them**: CAPTCHAs are so popular that online users have become familiar with them. Therefore, users generally know how to deal with CAPTCHAs and are not afraid of them.
- **Users trust them**: For example, CAPTCHAs help increase the credibility of online polls and contests. So, CAPTCHAs can help a site increase its reputation.

### Cons

- **For some users, they are challenging to solve**: Due to accessibility issues, inexperience, or language reasons, CAPTCHAs may pose a challenging test for some users. 
- **They take up user time:** Solving a CAPTCHA requires user interaction and takes time. Plus, users may need several attempts to pass a CAPTCHA test. 
- **They can become annoying**: Solving online challenges to prove that you are not a bot is definitely not a fun activity, especially if you have to do it several times in the same browsing session.

Simply put, the main problem with CAPTCHAs is that they require user interaction. This interrupts the operation's flow and distracts users. For this reason, bot protection solutions that require no user action have become increasingly popular. This is exactly what JS Challenges are all about. Let's find out more about them!

## What Is a JavaScript Challenge?

A JavaScript challenge - also known as a JS challenge - is a test that browsers run automatically to determine whether the user is legitimate or a bot. The web server sends the challenge to each client as JavaScript code embedded in a web page. 

Since most popular browsers have a JavaScript stack, they will be able to understand and pass the challenge transparently. In contrast, bots typically do not have a JavaScript stack and, therefore, cannot pass the challenge.

## How Do JavaScript Challenges Work?

JS challenges are injected into the HTML code of web pages and executed automatically by the browser. Once passed, the system sends a new challenge to the user only after a few minutes or if the browsing session ends. 

Typically, a JavaScript challenge begins by verifying that the client can execute JavaScript. Then, the JavaScript code of the challenge executes. To verify that the user is legitimate, the challenge takes some browser and device characteristics into account. For example, a JS challenge may check for the presence of certain fonts.

This process may take up to a few seconds, but in most cases, JS challenges are executed without the user even realizing it. 

![Cloudflare JS Challenge's wall page](https://images.ctfassets.net/23aumh6u8s0i/2z2rN9oEZCzAxKzpGRh0sZ/65dc9f1d702ddfbda5f33b9384ffad02/05-captcha.png)

The most popular provider of JS challenges is Cloudflare, one of the leaders in the CDN market. If you enable the [Managed Challenge](https://developers.cloudflare.com/fundamentals/get-started/concepts/cloudflare-challenges/#managed-challenge-recommended) feature, Cloudflare will send the client a set of challenges. These usually start with the non-interactive challenge above, which runs a JavaScript challenge behind the scene.

Note that when it comes to detecting if the user can run JavaScript, Cloudflare relies on Google’s [Picasso fingerprinting protocol](https://research.google/pubs/pub45581/). This enables a server to verify the software and hardware stack of a client based on a few collected data.

## JS Challenges: Pros and Cons

Let’s now take a look at the pros and cons of JS challenges as a transparent bot protection technology.

### Pros

- **They are not intrusive**: JavaScript challenges are executed automatically and do not require user interaction. End users have to be patient for a few seconds while the JS challenge is executed.
- **They do not require a backend**: JS challenges can be executed without communicating with a server, making them a network-efficient antibot solution.
- **They respect privacy**: JS challenges are executed in the front end and do not require storing user data.

### Cons

- **They can be bypassed**: Assuming that bots cannot run JavaScript is not sufficient to block them. This is especially true considering that [headless browser](https://en.wikipedia.org/wiki/Headless_browser) technologies allow instructing browsers with no GUI to perform automated tasks.
- **You cannot rely solely on them**: JS challenges represent the first level of a complete bot mitigation solution, which generally involves more advanced challenges.
- **They block human users with JavaScript disabled**: Users who disable JavaScript execution in their browser for security reasons will fail JavaScript challenges. So, they will be mistaken for bots. 

## Bot Protection According to Auth0

Auth0 can help your website with bot protection. The Auth0 [bot detection](https://auth0.com/docs/secure/attack-protection/bot-detection) feature uses machine learning to identify bots and block them from performing specific attacks, such as [credential stuffing attacks](https://auth0.com/blog/what-is-credential-stuffing/) or list validation attacks. When a bot attack is detected, the Auth0 bot detection system adds a CAPTCHA step in the login or sign-up form to eliminate bot and scripted traffic.
The Auth0 [bot detection](https://auth0.com/docs/secure/attack-protection/bot-detection) feature uses machine learning to identify bots and block them from performing specific attacks, such as [credential stuffing attacks](https://auth0.com/blog/what-is-credential-stuffing/) or list validation attacks. 
When a bot attack is detected, the Auth0 bot detection system adds a CAPTCHA step in the login or sign-up form to eliminate bot and scripted traffic.

![Auth0 can introduce a CAPTCHA for security reasons in a login form](https://images.ctfassets.net/23aumh6u8s0i/1zOmIeYYMayZjuGh70KCHh/387af28906dc288f0f2a28261cc21fb4/06-captcha.png)

Note that you can configure the CAPTCHA provider directly on the [Attack Protection](https://manage.auth0.com/#/security/attack-protection) dashboard. Keep in mind that Auth0 supports [reCAPTCHA integration](https://auth0.com/docs/secure/attack-protection/bot-detection#configure-bot-detection).

Auth0 bot detection has been proven to [reduce bot attacks by 79%](https://auth0.com/blog/auth0-bot-detection-reduces-bot-attacks-by-79/) while adding very little friction to legitimate users, considering that less than 1% of CAPTCHAs are shown to human users. Also, Auth0 allows you to define an allowlist of 100 IP addresses to exempt them from bot detection measures.
 
Simply put, Auth0 offers advanced bot detection capabilities to protect its sign-in and sign-up features from bots and malicious users. With just a few clicks, you can activate the bot detection system directly in your [Auth0 dashboard](https://auth0.com/docs/get-started/auth0-overview/dashboard).

## Conclusion

In this article, you learned what a bot is, why bot protection is important, and what the most popular antibot options are. In particular, you had the opportunity to learn more about CAPTCHAs.

CAPTCHAs present users with simple challenges that require some sort of interaction to be solved. Since this can be annoying for users, you may be looking for automated antibot solutions, such as JavaScript challenges. 

You learned about the most popular JS challenges on the market and how they work. And finally, you looked at what Auth0 offers for detecting bots to protect login and registration forms. 

Thanks for reading! I hope that you found this article helpful. Feel free to reach out to me with any questions, comments, or suggestions.

Protect Your Site from Bots with CAPTCHAs and JavaScript Challenges

I stream, blog, and make youtube videos about tech stuff. I love coding, I love AI, and I love building stuff!

Staff Developer Advocate

Juan Cruz Martinez

This is a story of the odd and the strange. A story involving dimensions, monsters, and JavaScript

It is 1995, in a small US town. A group of friends is playing Dungeons & Dragons. When they see that Demogorgon enters the game, Brendan casts Fireball. He rolls the die, but it goes missing on the floor. They keep playing.

After the game ends, Brendan rides his bike through the woods, passing by the Netscape Communications Corporation. Then he sees something weird in front of him. He loses his balance, falls down a steep hill, and crashes.

The boy runs home. He's shivering as he looks back, ensuring that thing doesn't follow him. He arrives home only to find out no one is there. He tries to call his parents, but he can't get through.

Something unlocks the door. Brendan runs out to the backyard when he sees the thing. A light glows brightly and then fades, revealing no one is there anymore.

After ten days of searching, Brendan Eich reappears in the forest, but he is not alone. A yellow and mysterious creature is with him, with odd characteristics but a powerful presence.

> <img alt="JavaScript" src="https://images.ctfassets.net/23aumh6u8s0i/2QjNmyDo6LfK4HC8F1q4qw/b8baddde46d79ec9432a15f14b4a41a2/javascript" height="35" style="margin-right: 1rem" align="left" />
It is too late for the world. JavaScript is out!

## The Weirdo on Maple Street
Joey, Andrea, and Juan are wandering in the woods when they encounter JavaScript. They freeze as the programming language tries to communicate with them but can't figure out what it's trying to say.

With the help of an interpreter, they managed to capture the strange language, but what does it all mean?

In front of them lay the script

```javascript
([![]] + [][[]])[+!+[] + [+[]]] + 
([![]] + [][[]])[+!+[] + [+!+[]+!+[]]]
+ " " +
(![] + [])[+[]] +
(![] + [])[+!+[]] +
([![]] + [][[]])[+!+[] + [+[]]] +
(![] + [])[!+[] + !+[]] + 
(![] + [])[+!+[]+!+[]+!+[]]
```

After some thought, the team got to work on the problem. They split it up into smaller chunks and worked it out.

First let's take a look at `([![]] + [][[]])` which is repeated throughout the snippet.

Breaking it down, even more, we get:

`[![]]` and we know that `![]` is `false`, so we have `[false]` as a result.

Next, `[][[]]` looks confusing, but looking into more details, it follows this pattern: `array[index]` where `array = []` and index = `[]`, and accessing an empty array at any position, will return `undefined`, even if that position happens to be another array.

Putting this part of the script back together, we get:


```javascript
([![]] + [][[]]) === [false] + undefined &&
[false] + undefined === 'falseundefined'
```

And so they replaced

```javascript
'falseundefined'[+!+[] + [+[]]] + 
'falseundefined'[+!+[] + [+!+[]+!+[]]]
+ " " +
(![] + [])[+[]] +
(![] + [])[+!+[]] +
'falseundefined'[+!+[] + [+[]]] +
(![] + [])[!+[] + !+[]] + 
(![] + [])[+!+[]+!+[]+!+[]]
```

But then:

```javascript
(![] + []) === 'false'
```

and

```javascript
'falseundefined'[+!+[] + [+[]]] + 
'falseundefined'[+!+[] + [+!+[]+!+[]]]
+ " " +
'false'[+[]] +
'false'[+!+[]] +
'falseundefined'[+!+[] + [+[]]] +
'false'[!+[] + !+[]] + 
'false'[+!+[]+!+[]+!+[]]
```

Now we understand more. Using this strange language, we could decode strings. Since JavaScript allows us to access any character in a string by asking for its position, each particular line seems to be capturing a unique character on each string.

We have the strings, but we need a way to build up indexes; fortunately, there are a few tricks we can use.

For starters, thanks to Math in JavaScript, we know that `+true === 1` and that `+false === 0`, why? the `+` sign at the beginning tells JavaScript to cast the boolean value to its numeric form.

Once we have those numbers, we can make any combination. For example, `2` can be written as `+true+true`, but what if we want something in the two digits order? It will take a long of those... Or we can use a different technique.

`number1+[number2] === "numbernumber2"`, this happens because the sum now acts as a concatenate and converts each side of the `+` sign into a string. This is done by design, as JavaScript can't add an array to an integer.

Finally, we can use this little array to bool conversion table to get our numbers:

```
+[] -> +false -> 0
!+[] -> !false -> true
+!+[] -> +true -> 1
```

Now that we can form single and two-digit numbers, we can easily convert all the indexes into numbers or strings and form our final answer:

```javascript
'falseundefined'['10'] + 
'falseundefined'['12']
+ " " +
'false'[0] +
'false'[1] +
'falseundefined'['10'] +
'false'[2] + 
'false'[3]
```

Now, we have to count.

```javascript
i
e
" "
f
a
i
l
s
```

That's it! He is trying to say, "ie fails"!

## Holly, Jolly, and The Body
Carla, Brendan's mom, is sure that he is trying to communicate with her through the lights of her house. Carla is determined to find out, so she elaborates on a simple math test.

"Brendan, can you hear me?" she asks. If you can hear me, tell me, what is `1 + 1`, and the lights go on and off two times.

For the second test, `3 + 1`, the lights go on and off four times.

Is this a coincidence? She is, by now, freaking out.

`"3" - 1`, and the lights go twice.

It has to be him! One more to be sure

`"3" + 1`, but the lights start a different show this time. They go on and off for a while. When they stopped, she had counted `"31"`.

Maybe I am a mess; maybe I'm crazy, she concluded. What kind of math is that?

She doesn't know JavaScript, or she would have understood. The lights were correct, according to JavaScript, of course.

If the same happens to you, remember, in JavaScript.

```
Number + Number -> addition
Boolean + Number -> addition
Boolean + Boolean -> addition
Number + String -> concatenation
String + Boolean -> concatenation
String + String -> concatenation
```

For example:

```javascript
3 - 1 // -> 2
 3 + 1 // -> 4
'3' - 1 // -> 2
'3' + 1 // -> '31'

'' + '' // -> ''
[] + [] // -> ''
{} + [] // -> 0
[] + {} // -> '[object Object]'
{} + {} // -> '[object Object][object Object]'

'222' - -'111' // -> 333

[4] * [4] // -> 16
[] * [] // -> 0
[4, 4] * [4, 4] // NaN
```

## The Flea and the Acrobat
Tony, the local chief of police, who starts to believe in Carla's story, decides to break into the Netscape Communications Corporation, looking to learn more about JavaScript.

Juan, Andrea, and Joey, who had a conversation with Brendan, believe that JavaScript came from an alternate dimension, the "Upside Down".

In this dimension, there are special considerations, he adds. For example,

```javascript
Math.min() > Math.max(); // -> true
Math.min() < Math.max(); // -> false
```

Intuitively it is strange, but in the JavaScript dimension, it makes sense, as 

```javascript
Math.min(); // -> Infinity
Math.max(); // -> -Infinity
Infinity > -Infinity; // -> true
```

But why does `Math.min() === Infinity`? `Math.min` takes arguments, tries to convert each one to a number, and then it returns the smallest of them. If you don't provide any arguments, the result is `Infinity`.

And the opposite thing happens to `Math.max`.

Meanwhile, Tony had an encounter.

## The Monster and The Upside Down
Deep in the lab, where the shadows cover the rooms, Tony feels there's something around. He calls in for backup. On the other side, Greg and Dan are on their way.

Juan, Andrea, and Joey know that the only way to conquer JavaScript is to enter into its dimension, so they fire up a terminal and open the portal. They all jump inside.

In the lab, another portal opens. Tony, who already met with Greg and Dan, gets inside, and the portal collapses right after.

From the shadows, a strange passage appears. It contains a challenge, "solve me, and I'll let you go!"

```javascript
['1', '7', '11'].map(parseInt);
```

Intuitively, the group tries to guess the first answer, `[1, 7, 11]`, but Juan, Andrea, and Joey stop them before they can input it.

In this place, not all things are what they look like, so we must treat arguments very carefully, mentioned Juan.

Carla, who found her way to the "Upside Down", provided some more insights into the problem.

The function `parseInt` expects two parameters, a string and the radix. The latter is an integer between `2` and `36`, representing the base in mathematical numeral systems.

So the `map` function could be providing more than one argument, so more than just the string to the `parseInt` function, added Joey.

Breaking it down, the team formed the following statement:

```javascript
['1', '7', '11'].map((currentValue, index, array) => parseInt(currentValue, index, array));
```

The `index` from the `map` function is passed to the `parseInt` function as the radix, and thus, the resulting value would be different from the expected.

So the team calculates each value:

```javascript
parseInt('1', 0) // 1
parseInt('7', 1) // NaN
parseInt('11', 2) // 3
```

So the final result is `[1, NaN, 3]`.

As they type it in, the dimension starts shaking, and a new portal opens up.

They all rush out. "We are safe. We are back home", they rejoiced.

But that thing is still out there. Let's get it - Tony.

The team prepares for battle...

To be continued.

-----

I hope you enjoyed this little informative parody of Stranger Things, our treat for this Halloween.

Stranger Scripts

matthew-casperson

Technology enthusiast since my first C64. I love writing about new ideas and working with great people.

Product Manager at Octopus Deploy

Matthew Casperson

Learn how to integrate a browser client to reactive streams published by a Spring WebFlux server.

Reactive Streams with Kotlin, Webflux, and rsocket-js

dfea5c5f769cc4a6cce74d3eda20bba3?size=200 avatar

dfea5c5f769cc4a6cce74d3eda20bba3?size=200

Guest Author

Tim McLean

Which libraries are vulnerable to attacks and how to prevent them.



**TL;DR:** If you are using [node-jsonwebtoken](https://github.com/auth0/node-jsonwebtoken), [pyjwt](https://github.com/jpadilla/pyjwt/), [namshi/jose](https://github.com/namshi/jose), [php-jwt](https://github.com/firebase/php-jwt) or [jsjwt](https://github.com/kjur/jsjws) with asymmetric keys (RS256, RS384, RS512, ES256, ES384, ES512) please update to the latest version. See [jwt.io](http://jwt.io) for more information on the vulnerable libraries. *(Updated 2015-04-20)*

> This is a guest post from Tim McLean, who is a member of the [Auth0 Security Researcher Hall of Fame](https://auth0.com/whitehat#hall-of-fame). Tim normally blogs at [www.timmclean.net](https://www.timmclean.net).

Recently, while reviewing the security of various JSON Web Token implementations, I found many libraries with critical vulnerabilities allowing attackers to bypass the verification step.  The same two flaws were found across many implementations and languages, so I thought it would be helpful to write up exactly where the problems occur.  I believe that a change to the standard could help prevent future vulnerabilities.

<include src="TweetQuote" quoteText="I found many libraries with critical vulnerabilities allowing attackers to bypass the verification step."/>

For those who are unfamiliar, [JSON Web Token (JWT)](https://auth0.com/learn/json-web-tokens/) is a standard for creating tokens that assert some number of claims.  For example, a server could generate a token that has the claim "logged in as admin" and provide that to a client. The client could then use that token to prove that they are logged in as admin. The tokens are signed by the server's key, so the server is able to verify that the token is legitimate.

JWTs generally have three parts: a header, a payload, and a signature.

The header identifies which algorithm is used to generate the signature, and looks something like this:

``` javascript  
header = '{"alg":"HS256","typ":"JWT"}'
```

`HS256` indicates that this token is signed using HMAC-SHA256.

The payload contains the claims that we wish to make:

``` javascript  
payload = '{"loggedInAs":"admin","iat":1422779638}'
```

As suggested in the JWT spec, we include a timestamp called `iat`, short for "issued at".

The signature is calculated by base64url encoding the header and payload and concatenating them with a period as a separator:

``` javascript  
key = 'secretkey'
unsignedToken = encodeBase64(header) + '.' + encodeBase64(payload)
signature = HMAC-SHA256(key, unsignedToken)
```

To put it all together, we base64url encode the signature, and join together the three parts using periods:

``` javascript  
token = encodeBase64(header) + '.' + encodeBase64(payload) + '.' + encodeBase64(signature)

# token is now:
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI
```

To learn more about JSON Web Tokens, check out our free ebook below.

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

## Great. So, What's Wrong with That?

Well, let's try to verify a token.

First, we need to determine what algorithm was used to generate the signature. No problem, there's an `alg` field in the header that tells us just that.

But wait, we haven't validated this token yet, which means that we haven't validated the header.  This puts us in an awkward position: in order to validate the token, we have to allow attackers to select which method we use to verify the signature.

This has disastrous implications for some implementations.

## Meet the "None" Algorithm


The `none` algorithm is a curious addition to JWT.  It is intended to be used for situations where the integrity of the token has already been verified. Interestingly enough, it is one of only two algorithms that are mandatory to implement (the other being `HS256`).

Unfortunately, some libraries treated tokens signed with the `none` algorithm as a valid token with a verified signature.  The result?  Anyone can create their own "signed" tokens with whatever payload they want, allowing arbitrary account access on some systems.

Putting together such a token is easy. Modify the above example header to contain `"alg": "none"` instead of `HS256`.  Make any desired changes to the payload.  Use an empty signature (i.e. `signature = ""`).

Most (hopefully all?) implementations now have a basic check to prevent this attack: if a secret key was provided, then token verification will fail for tokens using the `none` algorithm.  This is a good idea, but it doesn't solve the underlying problem: attackers control the choice of algorithm.  Let's keep digging.

## RSA or HMAC?

The JWT spec also defines a number of asymmetric signing algorithms (based on RSA and ECDSA).  With these algorithms, tokens are created and signed using a private key but verified using a corresponding public key.  This is pretty neat: if you publish the public key but keep the private key to yourself, only you can sign tokens, but anyone can check if a given token is correctly signed.

Most of the JWT libraries that I've looked at have an API like this:

``` javascript  
# sometimes called "decode"
verify(string token, string verificationKey)
# returns payload if valid token, else throws an error
```

In systems using HMAC signatures, `verificationKey` will be the server's secret signing key (since HMAC uses the same key for signing and verifying):

``` javascript  
verify(clientToken, serverHMACSecretKey)
```

In systems using an asymmetric algorithm, `verificationKey` will be the public key against which the token should be verified:

``` javascript  
verify(clientToken, serverRSAPublicKey)
```

Unfortunately, an attacker can abuse this.  If a server is expecting a token signed with RSA, but actually receives a token signed with HMAC, **it will think the public key is actually an HMAC secret key**.

How is this a disaster?  HMAC secret keys are supposed to be kept private, while public keys are, well, public.  This means that your typical [ski mask-wearing attacker](https://i.imgur.com/18fM5ja.jpg) has access to the public key, and can use this to forge a token that the server will accept.

Doing so is pretty straightforward.  First, grab your favorite JWT library, and choose a payload for your token.  Then, get the public key used on the server as a verification key (most likely in the text-based PEM format). Finally, sign your token using the PEM-formatted public key as an HMAC key. Essentially:

``` javascript  
forgedToken = sign(tokenPayload, 'HS256', serverRSAPublicKey)
```

The trickiest part is making sure that `serverRSAPublicKey` is identical to the verification key used on the server.  The strings must match exactly for the attack to work -- exact same format, and no extra or missing line breaks.

End result?  Anyone with knowledge of the public key can forge tokens that will pass verification.

## Recommendations for Library Developers

I suggest that JWT libraries add an `algorithm` parameter to their verification function:

``` javascript  
verify(string token, string algorithm, string verificationKey)
```

The server should already know what algorithm it uses to sign tokens, and it's not safe to allow attackers to provide this value.

Some might argue that some servers need to support more than one algorithm for compatibility reasons.  In this case, a separate key can (and should) be used for each supported algorithm.  JWT conveniently provides a "key ID" field (`kid`) for exactly this purpose.  Since servers can use the key ID to look up the key and its corresponding algorithm, attackers are no longer able to
control the manner in which a key is used for verification.  In any case, I don't think JWT libraries should even look at the `alg` field in the header, except maybe to check that it matches what the expected algorithm was.

Anyone using a JWT implementation should make sure that tokens with a different signature type are guaranteed to be rejected.  Some libraries have an optional mechanism for whitelisting or blacklisting algorithms; take advantage of it, or you might end up at risk.  Even better: have a policy of performing security audits on any open source libraries that you use to provide mission-critical functionality.

## Improving the JWT/JWS Standard

I would like to propose deprecating the header's `alg` field.  As we've seen here, its misuse can have a devastating impact on the security of a JWT/JWS implementation.  As far as I can tell, key IDs provide an adequate alternative. This warrants a change to the spec: JWT libraries continue to be written with security flaws due to their dependence on `alg`.

JWT (and JOSE) present the opportunity to have a cross-platform suite of secure cryptography implementations.  With these fixes, hopefully, we're a little bit closer to making that a reality.

<include src="asides/Jwt" />


Critical vulnerabilities in JSON Web Token libraries

5e074956ee8ba1fea26e30d28c190495?s=300 avatar

5e074956ee8ba1fea26e30d28c190495?s=300

Full stack developer creating content at Auth0. I love taking a deep dive into hard-to-understand concepts and creating content that makes them easier to grasp. In my free time you can usually find me reading, hanging out with my dogs, or curling in the squat rack.

Former Developer Content Manager

Holly Guevara

99c4080f412ccf46b9b564db7f482907?s=200 avatar

99c4080f412ccf46b9b564db7f482907?s=200

I'm currently a Senior Developer Advocate at MongoDB. I'm also a Google Developer Expert for Web Technologies and spend most my time giving talks at conferences and meetups, mentoring developers and running workshops, and creating online content to help technology professionals.

Former Auth0 Employee

Ado Kukic

Practice Go and React by building and authenticating a RESTful API with JSON Web Tokens (JWTs).

Authentication in Golang with JWTs

sambiopic

I'm Director of Developer Relations and a Google Developer Expert for Angular and Web Technologies. I believe anyone who wants to learn to code should be able to learn code and I love teaching. When I'm not coding or writing, you'll find me outside hiking or camping in the beautiful Pacific Northwest.

Director of Developer Relations

Sam Julien

Auth0 has a new SDK for securing single page applications with industry best practices.


We are excited to announce the release of our new JavaScript SDK for Single Page Applications (SPAs) called [auth0-spa-js](https://auth0.com/docs/libraries/auth0-spa-js).

## Why a New SDK?
The [`auth0.js`](https://github.com/auth0/auth0.js) library has been our default browser-based SDK for the last few years and has been a key part of our product and success. It has over 100K+ weekly downloads and is used by almost every Auth0 customer in one way or the other.

Over this time, we have developed a large set of capabilities in the core product. As the platform has moved forward, `auth0.js` has grown in size and capabilities. While `auth0.js` is an extremely powerful SDK that can handle a large number of different scenarios, this versatility comes at a price.

We went back to the drawing board and we re-imagined how a web platform SDK should work for the most common scenarios developers will be implementing. This new SDK:

- integrates with [Universal Login](https://auth0.com/docs/universal-login), our flagship login experience
- is much easier to integrate into Single Page Apps and requires less code
- abstracts the developer from standards and protocols
- frees the developer from having to specify the grant or other protocol details, manage token expiration and renewal, or store and cache tokens
- follows industry and service best practices and protects developers from security pitfalls
- weights around 7kb minified and gzipped

We're excited about these changes and hope our customers and [developer community](https://community.auth0.com/) find this new SDK easy to use yet still powerful and secure.

<include src="TweetQuote" quoteText=".@auth0 has a new SDK to keep SPAs secure called auth0-spa-js. Check it out!"/>

## When to Use `auth0-spa-js` (and When Not to)
The new SDK is designed for use in SPAs to keep them secured using industry best practices.

The OAuth2 working group has published a new general [best current practices document](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-11) for using OAuth2 to invoke APIs from Single Page Applications. The recommendation is now to use the authorization code grant with Proof Key for Code Exchange (PKCE), as opposed to using the implicit grant as described in the original OAuth2 spec. You can find more details in [this blog post from our Principal Architect Vittorio Bertocci](https://auth0.com/blog/oauth2-implicit-grant-and-spa/).

This new JavaScript SDK implements the authorization code grant with PKCE for authentication, so by using this new library, you will be following the latest industry best practices when it comes to security in Single Page Applications.

Don't worry, we will not be discontinuing support of `auth0.js`. In fact, if you still use embedded login or need to call the [management API](https://auth0.com/docs/api/info#management-api-v2) or [authentication API](https://auth0.com/docs/api/info#authentication-api), you'll want to stick with `auth0.js`. We encourage you to switch to `auth0-spa-js` if you're using Universal Login in a SPA.

![Auth0's Lightweight Universal Login modal view](https://images.ctfassets.net/23aumh6u8s0i/54lZ5srDBAM0dqWSRkdxXk/f4260dcf2af6e7b5b4a52c62769e0745/lightweight-login)

## How to Use Auth0 SPA JS SDK
So how do you start using the new SDK? Here are some steps for vanilla JavaScript that can then be applied to the framework of your choice.

### Installation
To use the new SDK, first install it from npm:

```bash
npm install @auth0/auth0-spa-js
```

Alternatively, you can include it in your project using our CDN:

    
    <script src="https://cdn.auth0.com/js/auth0-spa-js/1.0/auth0-spa-js.production.js"></script>
     

### Create the client
Once `auth0-spa-js` is added to your project, you'll need to create an instance of the Auth0 client in your application. Ideally, you should have only one instance of the client. Do this before rendering or initializing your application.

You can do this using async/await:

```javascript
//with async/await
const auth0 = await createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  client_id: '<AUTH0_CLIENT_ID>'
});
```

Or with promises:

```javascript
//with promises
createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  client_id: '<AUTH0_CLIENT_ID>'
}).then(auth0 => {
  //...
});
```

### Logging in
Adding the ability to log in to your application is easy. Given the following button:

    
    <button id="login">Click to Log In</button>
    

You can add a click handler and then call the [`loginWithRedirect()`](https://auth0.github.io/auth0-spa-js/classes/auth0client.html#loginwithredirect) method:

```javascript
document.getElementById('login').addEventListener('click', () => {
  return auth0.loginWithRedirect();
});
```

Once the user is redirected back to the app after authenticating with Auth0, your app will need to call [`handleRedirectCallback()`](https://auth0.github.io/auth0-spa-js/classes/auth0client.html#handleredirectcallback): 

```javascript
await auth0.handleRedirectCallback();
```

This is what parses the result from Auth0, stores the tokens, and sets up the session. You'll then be able to get the user or token as needed:

```javascript
const user = await auth0.getUser();
const token = await auth0.getTokenSilently();
```

### Calling an API
You can also use the SDK to silently get a token and then use that token in a call to an API.

Given the following button:

    
    <button id="call-api">Call an API</button>
    

You'll add a click handler, call [`getTokenSilently()`](https://auth0.github.io/auth0-spa-js/classes/auth0client.html#gettokensilently), and then use the returned token in your API call.

Here it is with async/await:

```javascript
//with async/await
document.getElementById('call-api').addEventListener('click', async () => {
  const accessToken = await auth0.getTokenSilently();
  const result = await fetch('https://myapi.com', {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`
    }
  });
  const data = await result.json();
  console.log(data);
});
```

And with promises:

```javascript
//with promises
document.getElementById('call-api').addEventListener('click', () => {
  auth0
    .getTokenSilently()
    .then(accessToken =>
      fetch('https://myapi.com', {
        method: 'GET',
        headers: {
          Authorization: `Bearer ${accessToken}`
        }
      })
    )
    .then(result => result.json())
    .then(data => {
      console.log(data);
    });
});
```

If there's a valid token stored, `getTokenSilently` will return it. Otherwise, it opens an iframe with the `/authorize` URL using the parameters provided as arguments and returns the token.

### Logging out
Finally, logging out of your application is a matter of adding an event handler to your log out button and then calling Auth0's [`logout()`](https://auth0.github.io/auth0-spa-js/classes/auth0client.html#logout) method.

Here's the button:

    
    <button id="logout">Log Out</button>
    

And here is the click handler and the call to `logout()`:

```javascript
document.getElementById('logout').addEventListener('click', () => {
  auth0.logout();
});
```

## Behind the Curtain
Since many developers (myself included) are wary of black boxes, let's take a moment to look at the protocols behind the new SDK.

While our intent is to abstract away all the implementation details in this new SDK so you don't need to worry about them, identity geeks will be pleased to know that `auth0-spa-js` is compliant with OAuth 2.0 specifications:

* `loginWithRedirect` uses [authorization code with PKCE](https://tools.ietf.org/html/rfc7636)
* `loginWithPopup` uses authorization code with PKCE + [`web_message`](https://tools.ietf.org/html/draft-sakimura-oauth-wmrm-00)
* `getTokenSilently` uses authorization code with PKCE + `web_message`

Auth0 takes our commitment to security best practices seriously. Luckily, we do all the heavy lifting so you don't have to!

## Where to Go Next
To learn more about using `auth0-spa-js`, check out the Auth0 Single Page Applications [SDK introduction documentation](https://auth0.com/docs/libraries/auth0-spa-js), [repository](https://github.com/auth0/auth0-spa-js), and [the SDK's full documentation](https://auth0.github.io/auth0-spa-js/index.html). There are also [Quickstarts](https://auth0.com/docs/quickstarts) that will walk you through integration step-by-step for popular front-end frameworks like React and Angular. We hope you're as excited about this new SDK as we are, and look forward to hearing feedback from the [developer community](https://community.auth0.com/)!

<include src="asides/AboutAuth0" />



Announcing the General Availability of the Auth0 SPA JS SDK

332d7898dae6bc56031ac3507a0248ba

I'm a full-stack developer with a passion for technology and code. I love writing tutorials for developers to showcase a particular technology whilst building something useful at the same time. Right now  I can mostly be found developing for the front-end, playing around with Docker, or tinkering with Unreal Engine and electronics!

Developer Experience Engineer

Steve Hobbs

Learn about the Hasura platform and how their GraphQL APIs can be secured using JSON Web Tokens



If you're developing an API today for consumption by third-parties, you'd be more than forgiven for choosing the [REST interface](https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/) to develop the API, as it is a tried and tested standard for delivering data to consumers, as well as accepting changes to the data in a structured way. In more recent times, [GraphQL](https://graphql.org/) has become an attractive alternative for developing APIs thanks to its flexible, semantic, and performant nature.

But what if you'd like finer control over the details of the data exchange, including [integration with third-party authorization servers using JWTs](https://docs.hasura.io/1.0/graphql/manual/auth/jwt.html), and being able to quickly and easily set [role-based permissions at the field level](https://docs.hasura.io/1.0/graphql/manual/auth/basics.html#restrict-access-to-certain-columns)?

That's what Hasura have achieved with their [GraphQL platform](https://hasura.io/) that generates a GraphQL API over a [PostgreSQL](https://www.postgresql.org/) database. To highlight just a few of the features:

*   A PostgreSQL database schema can be designed and populated with data, using the built-in interface
*   The database can be queried using the GraphQL syntax, as well as the ability to view the GraphQL schema documentation from within the Hasura admin console
*   Roles can be assigned to individual tables and fields, as well as assigned different roles and permissions to individual operations such as selecting or inserting data
*   Authorization can be conducted using [JSON Web Tokens](https://jwt.io/), issued by a third-party authorization server such as [Auth0](https://auth0.com/)

<include src="TweetQuote" quoteText="The Hasura platform takes advantage of JWT and GraphQL technologies to provide a  platform for querying and manipulating data in a PostgreSQL database,  taking into account the role specified in the authorization token."/>

## <a class="toc-target" id="a-short-introduction-to-json-web-tokens"></a>A Short Introduction to JSON Web Tokens

From [jwt.io](https://jwt.io/introduction):

> _JSON Web Token (JWT) is an open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the **HMAC** algorithm) or a public/private key pair using **RSA** or **ECDSA**._

What this looks like in practice is a string that is made up of three parts separated by a period:

* The first part defines the header, containing information such as the signing algorithm used
* The second part is the main body of the token and includes all the claims. This could be things like the user name, expiry date, issue date, and email address
* The last part is the signature, which is derived by cryptographically signing the header and the body together to ensure that the data has not been tampered with

A JWT is issued as a result of a user authenticating with an authorization server. In the case of the Hasura platform, this JWT can then be used to authorize the request and as such can make queries and mutations depending on the claims present in the token. We will see how this works in the demo a little bit later in the article.

The compact nature of a JWT makes it easy to pass around in query strings, headers, and request bodies, or [store in a cookie](https://auth0.com/docs/security/store-tokens#understanding-sessions-and-cookies).

## <a class="toc-target" id="what-is-graphql-an-overview"></a>What is GraphQL? An Overview

GraphQL is essentially a query language that allows you to define your API in terms of types. It is datastore-agnostic and has [server-side support for many different platforms and languages](https://graphql.org/code/#server-libraries). Instead of defining your API in terms of status codes and semantic URLs, you define the types and then construct queries using a familiar but powerful syntax. As an example:

```js
{
  article {
    id,
    title,
    author {
      name
    }
  }
}
```

This describes a query for articles, returning the id, title, and the author's name. As you can see, it supports nested database objects (the author is another table in the schema, linked to from an article). Mutations can also be defined, which describe how to change data.

In addition, _multiple queries_ can be made in a single request, which is most useful when a client wants to retrieve lots of possibly unrelated data points from the server.

## <a class="toc-target" id="the-hasura-approach"></a>The Hasura Approach

The Hasura platform takes advantage of these technologies to provide a platform for querying and manipulating data in a PostgreSQL database, taking into account the role specified in the authorization token.

The Hasura console allows the user to create a database, define its schema, and populate it with data. Hasura will then generate a GraphQL API on top of this database, automatically generating the appropriate types, queries, and mutations that allow the client to completely query for and manipulate the underlying data.

Hasura takes a role-based approach to authorization, and as such an individual role's access can be narrowed down to only a subset of the overall schema (even down to the field level). As each role is mapped to certain authorization rules, it can even be prevented from running certain mutations if so desired. Furthermore, queries can be delegated to an upstream service based on the claims present in the authorization token.

[Custom claims](https://auth0.com/docs/scopes/current/custom-claims) inside the JWT are used to tell Hasura about the role of the caller, so that Hasura may enforce the necessary authorization rules to decide what the caller can and cannot do.

![Hasura GraphQL engine authorization flow chart](https://images.ctfassets.net/23aumh6u8s0i/3hUYnCpHRwjnTU6LRLl2Oc/eaf8a50276dcb8fde4eb80adf451ced9/hasura-01_arch)

[[Source](https://docs.hasura.io/1.0/graphql/manual/auth/jwt.html)]

An example of the claims used by Hasura may look like the following:

```js
{
  "https://hasura.io/jwt/claims": {
    "x-hasura-default-role": "anonymous",
    "x-hasura-allowed-roles": [
      "user",
      "anonymous"
    ]
}
```

These two keys define the possible roles as well as the default role in the absence of the ["X-Hasura-Role" header](https://docs.hasura.io/1.0/graphql/manual/auth/basics.html#add-a-simple-access-control-rule-for-a-logged-in-user). In the case of Auth0, these custom claims can be put in place using [Rules](https://auth0.com/docs/rules), a platform feature that can be used to dynamically enhance tokens as users are authenticated.

## <a class="toc-target" id="demo-querying-data"></a>Demo: Querying Data

Let's have a look at how authorization with Hasura and JWTs works in practice. A demo has been set up that will allow you to construct queries and see the role-based permissions system in action.

This demo has been pre-configured with a database that has authors, articles, tags, and a relationship table that joins many articles to many tags. Let's see how we can query for some of this data.

### Executing anonymous queries

Browse to [https://auth0-hasura-demo.herokuapp.com](https://auth0-hasura-demo.herokuapp.com/console/api-explorer), and use "hasurademo" as the access key.

![Hasura console login screen deployed with Heroku](https://images.ctfassets.net/23aumh6u8s0i/4enFGmDUiStr0A9RQ5TfnI/aeee19ffd1dd1c727a1abbb938a6f22a/hasura-01_login)

Next, you will be presented with the Hasura console:

![The Hasura console and GraphQL explorer](https://images.ctfassets.net/23aumh6u8s0i/3LlFxGsCpDUBzi78yRV1V7/1df5659f6e04290a13609f7f43e4d071/hasura-01_console-1)

The interface gives you the opportunity to specify some request headers that will be used when querying the GraphQL interface. To demonstrate how the user's role affects their ability to query and modify data, remove the `X-Hasura-Access-Key` header by clicking on the cross on the right-hand side, and enter a new header `X-Hasura-Role` with a value of "anonymous":

![Setting the X-Hasura-Role header to anonymous in the Hasura console](https://images.ctfassets.net/23aumh6u8s0i/7gltFstbQEnUuMDX3sHmLS/644c0ff9f3ca7528c8571dd3c4d437ec/hasura-01_console-2)

Now, let's make a query. Use the following query inside the Graphiql query entry area in the lower half of the screen:

```
{
  article {
    id,
    title
  }
}
```

To run the query, press Ctrl+Enter (Cmd+Enter if you're on a Mac), or click on the large 'play' button above the query panel. You will see the results of the query on the right-hand side of the screen; you have successfully managed to retrieve the results for two articles that are currently in the database!

![Hasura GraphQL API query explorer - viewing query results](https://images.ctfassets.net/23aumh6u8s0i/5LQrzHTNJ4gGvYYp0B6z5B/1d0ffbcd5f01bc76d23ab04f28d64f3a/hasura-01_console-3)

Now let's try a mutation. Alter the query so that it executes the following mutation:

```
mutation {
  insert_tag(objects:[{name:"<YOUR TAG NAME HERE>"}]) {
    returning {
      name
    }
  }
}
```

This is a mutation that inserts a new tag with your specified tag name into the database. You should replace the value `<YOUR TAG NAME HERE>` with a value of your choosing.

Running this mutation right now will return an error, letting you know that the mutation does not exist.

![Showing a failed mutation error in the Hasura console](https://images.ctfassets.net/23aumh6u8s0i/3GysSZ0xtaGnlQevp0hLgF/3394f4a20b210e1271fb8615a0433a7e/hasura-01_console-4)

This is correct since the permissions have effectively been set up so that the anonymous role cannot make changes to the database. This is also indicated by the GraphQL API docs, as it does not show any mutations that can be called by this role. To see this, click the "< Docs" button on the right-hand side of the query window to open the API documentation.

![Viewing the GraphQL API documentation explorer in the Hasura console](https://images.ctfassets.net/23aumh6u8s0i/5DNNzhAp4eAUwjhLqMga9s/091a706d83350562be740ba9b54b1f71/hasura-01_console-5)

Only queries and subscriptions are available as root types here, but no mutations.

Let's have a closer look at how permissions are set within the Hasura interface.

### Validating query permissions

To view the permissions matrix for the "tag" table:

1.  Click the "data" tab at the top of the screen
2.  Click the "tag" table on the left-hand side
3.  Click the "permissions" tab in the main part of the interface

![Viewing the permissions and roles explorer in Hasura](https://images.ctfassets.net/23aumh6u8s0i/uO6od521er4QdJvxtLmC6/ee59f070bf583ea843cfa86b701643b2/hasura-01_console-6)

You will arrive at a matrix that describes all the role permissions for the "tag" table. On this screen we can see a number of things:

*   The "anonymous" role can select data (denoted by the tick icon in the "select" column), but it can't insert, update, or delete (indicated by the cross icon in the relevant columns)
*   The "user" and "admin" roles can do everything

You can see here that, since the "anonymous" user cannot modify or insert any data, it makes sense that there are no mutations available.

Let's now switch to the "user" role and see how we can make this mutation work.

## <a class="toc-target" id="executing-authorized-queries"></a>Executing Authorized Queries

Click the "Graphiql" heading at the top of the screen to return to the query interface. Now, change the "X-Hasura-Role" request header so that its value is "user".

If you try to run the mutation again now, you will notice that it will fail for the same reason as before. This is because the "user" role needs to also provide a valid JWT in order to be properly authorized to run this mutation.

<include src="TweetQuote" quoteText="Learn how to create a GraphQL API and secure it using JSON Web Tokens using the @HasuraHQ platform"/>

### Generating a valid JWT

For the purposes of this demo, a tool has been provided to make it easy for you to generate a JWT and run this mutation.

Browse to [https://auth0-hasura-demo.now.sh/](https://auth0-hasura-demo.now.sh/) and log in with your Auth0 account. If you do not currently have one, you can <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">register for a free account</a>.

> **Note:** In a real-world application, you would retrieve an access token directly from the authorization server when the user logs in, and use that in your requests to the GraphQL engine. This tool has been provided only as a convenience for the purposes of this demo.

![Generating a valid JWT for demonstration purposes](https://images.ctfassets.net/23aumh6u8s0i/6lI7QMcEz5nB3EbLGYsYii/112f674d24644fda68df1f7e471666ef/hasura-01_console-7)

Once logged in, you will be able to see your token. Select the entire token string and press Ctrl+C (or Cmd+C on a Mac) to copy it into your clipboard.

Before we head back to the Hasura console, let's inspect the token to see if it contains the claims that we inspect. Head to [http://jwt.io](http://jwt.io), scroll down and paste the token into the left-hand side of the screen. The right-hand side will automatically update to show you the data contained within the token, and you should be able to see that the correct Hasura claims have been included:

![Testing the JWT token at jwt.io](https://images.ctfassets.net/23aumh6u8s0i/3UghmdynnrceKJlxCu9XQ8/e066af2a85423a3f80312ab87b33dd1a/hasura-01_jwt-io)

With the token still in your clipboard, head back to the Hasura console. The way we attach this token to the request is through the standard "Authorization" request header.

Add a new header into the "headers" section, specifying the Authorization header and the JWT that you have in your clipboard as the bearer token:

![Adding the JWT to authorization request header in Hasura](https://images.ctfassets.net/23aumh6u8s0i/4wv6EC1ul56yPyI7icp2RQ/385c6bf02446601e5f1cb71dbbf12cf5/hasura-01_console-8)

Next, try running the mutation again. You should find that the query now works and that the name of the tag is being played back to you in the response:

![Authorized and successful run of previously failing mutation](https://images.ctfassets.net/23aumh6u8s0i/58rXtEu8Xe83VAv4dh8nqQ/574614e0324061ab0c7d3e6d1ace3f6f/hasura-01_console-9)

> **Note**: The "tag" database uses the tag name as its primary key. Since this demo is a cloud deployment that could potentially be used by many people, you should use your own made-up name for a tag as you cannot enter duplicate primary keys. If you have used a tag name that already exists, you will receive an error result in the query results window. Try running the mutation again with a different tag name.

Before we head away from this screen, let's expand the API docs again to show that the "mutations" root now appears and that you can browse through all the available mutations given that you are now authorized to do so:

![GraphQL API documentation explorer in Hasura showing mutations](https://images.ctfassets.net/23aumh6u8s0i/4lohzmsY0Hgy4MYWgNEuQ5/73012dbceb3010874feb695060db4738/hasura-01_console-10)

Finally, to prove that the mutation has worked we can explore the raw data in the database. Once again, click the "Data" heading at the top of the screen and then click on the "tags" table on the left.

![Raw data in Hasura after the mutation has been executed](https://images.ctfassets.net/23aumh6u8s0i/5ZVbWL8bJxXeASO1KsyRLs/85935085b9dec9ec08ff5ae29ae065c1/hasura-01_console-11)

The resulting screen will show you the data that is present in the table, and you can see that the "example-tag" entry that was created by the mutation is there.

## <a class="toc-target" id="wrapping-up"></a>Wrapping Up

In this post, you learned a bit about GraphQL and the main differences from a traditional REST API. You also had an introduction to JSON Web Tokens, how they are made up, and how easy they are to pass around.

Next, you discovered how Hasura tackles the idea of a role-based architecture when it comes to securing GraphQL APIs, and how it uses JWTs to authorize incoming requests and grant permissions to specific areas of the schema, even down to the field level.

Finally, you had a practical look at the Hasura platform, learning how to perform anonymous queries, and how to perform authorized mutations using a JWT that was issued to you by Auth0.

### Further reading

*   [Hasura.io](https://hasura.io/)
*   [Hasura GraphQL Engine Documentation](https://docs.hasura.io/1.0/graphql/manual/index.html)
*   [jwt.io](https://jwt.io)
*   [Introduction to GraphQL](https://graphql.github.io/learn/)

<include src="asides/AboutAuth0" />

## <a class="toc-target" id="about-hasura"></a>About Hasura

Based out of Bangalore and San Francisco, Hasura makes developer tools that simplify and accelerate product development.

The Hasura GraphQL engine is an open-source service that gives you instant, realtime, high-performance GraphQL for any Postgres app (including on existing databases).

Read more at [Hasura.io](https://hasura.io).


Using JWTs for GraphQL Authorization with Hasura

idee

Software Engineer building with Kotlin and Flutter.

Software Engineer at Busha

Idorenyin Obong

Learn how to use MobX to manage the state of your React apps with ease.

Managing the State of React Apps with MobX

A practical tutorial showing how to use JSON Web Tokens in ASP.NET Core 2 applications.

Securing ASP.NET Core 2.0 Applications with JWTs

685342d5e7f42c3ab8d251d7d4a53308?s=100&d=mm&r=g avatar

685342d5e7f42c3ab8d251d7d4a53308?s=100&d=mm&r=g

Robin Percy

Continuing on from my Introduction to Crystal article, this time we're going to build our first Crystal web app and authenticate users via JSON Web Tokens.

Building Your First Crystal Web App & Authenticating with JWTs

bruno-krebs

I am passionate about developing highly scalable, resilient applications. I love everything from the database, to microservices (Kubernetes, Docker, etc), to the frontend. I find amazing to think about how all pieces work together to provide a fast and pleasurable experience to end users, mainly because they have no clue how complex that "simple" app is.

R&D Content Architect

Bruno Krebs

JSF heavily depends on HTTP sessions, which is usually easier to scale vertically. Today we will see how to scale JSF horizontally with Spring Session.

[Spring](https://spring.io/) is one of the most popular and reliable frameworks available for Java developers. Upon its core, many modules were implemented, like [Spring MVC](https://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html), [Spring Security](https://docs.spring.io/spring-security/site/docs/current/reference/html/), [Spring Data](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/), and so on. In this article we will see how to use [Spring Session](http://projects.spring.io/spring-session/) (one of these Spring modules) to scale [JavaServer Faces (JSF)](https://javaserverfaces.java.net/) applications horizontally.

## Horizontal vs Vertical Scaling

Before diving into how we use Spring Session to scale JavaServer Faces (JSF) applications, let's do a quick review on the differences between scaling applications vertically and horizontally.

Scaling an application vertically means adding more power to the machine that hosts the application. For example, let's say that we have an application running on a [`t2.medium` instance on AWS (which has 2 virtual cores and 4GiBs of RAM)](https://aws.amazon.com/ec2/instance-types/) that is having a hard time to process all requests. To scale this application vertically would mean choosing a more powerful instance, with more resources, to host it (e.g. using a `t2.xlarge` instance that has 4 virtual cores and 16GiBs of RAM).

This approach has one good advantage but three extremely important disadvantages. The upside is that it is *very* easy to scale it. It's just a matter of deploying the application to the new instance and we are good to go. The downside list is:

1. The host that supports our application is a single point of failure. This means that if it goes down our users won't have access to our application.
2. It is quite expensive to keep upgrading the instance type, no matter where we are hosting it.
3. There is a limit on how much power we can get from a single host.

Horizontal scalability, on the other hand, means adding more hosts to support an application. In the example above, instead of choosing a new instance type, we could create a second `t2.medium` instance and [load balance requests](https://en.wikipedia.org/wiki/Load_balancing_(computing)) between them.

The biggest disadvantage of this approach is that the complexity of scaling an application is higher, when compared to deploying an application on a more powerful machine. But, the advantages are:

1. We can scale it infinitely.
2. It is cheaper to add a second machine rather than replacing for one with twice the power.
3. We have no single point of failure.

As we can see, although scaling applications vertically mighty be easier, scaling them horizontally is much more interesting and improves the reliability of our system. That's why in this article we will see how we can use Spring Session to scale JSF applications horizontally.

## What is Spring Session

Spring Session is a module of the Spring Framework that aims on providing a common infrastructure for managing clustered sessions. This means that Spring Session abstracts the complexity of clustering HTTP sessions, making it easy to host applications scaled horizontally. Basically, what this modules does is to offload the storage of the session state into  external session stores (e.g. Redis or a regular database such as PostgreSQL).

## Scaling JSF with Spring Session

To see Spring Session in action, we are going to run two dockerized instances of a specific JSF application—i.e. we are going to use [Docker](https://www.docker.com/) to host our application instances. Each dockerized instance will run on a different port: instance *number one* will run on port `8081`; and instance *number two* will run on port `8082`.

The JSF application in this repository is not configured with Spring Session. After building the application and running it on Docker, we are going to make the adjustments needed to tie these two instances together with Spring Session. To seamlessly integrate these instances, making them look like a single application, we are going to use a dockerized NGINX instance configured as a load balancer.

To summarize, we are going to:

1. clone a GitHub repo that gives us a good start point
2. compile and package the JSF application in this repo
3. launch two dockerized instances of this application
4. check their behavior running as independent applications
5. refactor the application to use Spring Session
6. run Redis in a Docker container
7. and configure NGINX and launch everything to have a horizontally scaled JSF application

## JSF Application

To start, let's [clone this repository](https://github.com/auth0-blog/spring-boot-session). The JSF application inside this repository contains only a data table that lists products and that accepts drag & drop commands to reorder the items.

The list of products is instantiated in memory when a user access the application for the first time. When the user drags & drop an item, the new order is kept for the whole duration of the session. Different users can have different orders, as the reordering occurs inside an HTTP session. But, for the same user, no matter how many tabs of the application are opened on a web browser, the order will be always the same.

Every time a user reorders the data table, JSF shows a message distinguishing which instance of the application handled the request. Before using Spring Session and tying the two instances together, this message won't have that much value. But, when we have every piece in place, we will be able to see that different instances will act in the same HTTP session.

Enough talking, let's get our hands dirty. To clone the application and to run it in two different dockerized instances, let's issue the following commands:

> **Note** that you will have to have Docker properly installed in your development environment. To install it, [follow the instructions here](https://docs.docker.com/engine/installation/). Besides that you will need a [JDK (1.7 or higher)](http://www.oracle.com/technetwork/java/javase/downloads/index.html) and [Maven](https://maven.apache.org/install.html). Please, be sure to have everything properly installed before proceeding.

```bash
# clone repo
git clone https://github.com/auth0-blog/spring-boot-session.git

# access its main directory
cd spring-boot-session

# compile and package the application
mvn clean package
```

After issuing the three commands above, we will have our JSF application ready to run. You might want to run it in your own machine before dockerizing it. This step is not needed, but it is good to see the application before putting it inside a Docker instance. To do that issue `java -jar target/spring-session-0.1-SNAPSHOT.jar` and open `http://localhost:8080/index.jsf` in your web browser. Note that if you do run the application now and try to reorder the data table, you will see a message saying *Request handled by: default title*. When we dockerize this application, we will give different titles to both instances.

## Dockerizing the JSF Application

Now that we have our application compiled and packaged, we can proceed with the dockerizing step. The process of dockerizing a [Spring Boot](https://projects.spring.io/spring-boot/) application (the JSF application in this repo is based on Spring Boot) is quite simple. We just need to generate a Docker image with a JDK, add the packaged application to this image and then run it. You will find the `Dockerfile` with all these commands in the root directory of our application, but I show its contents below as well:

```dockerfile
FROM frolvlad/alpine-oraclejdk8:slim
VOLUME /tmp
ADD target/spring-session-0.1-SNAPSHOT.jar /app.jar
RUN sh -c 'touch /app.jar'
ENV JAVA_OPTS=""
ENTRYPOINT [ "sh", "-c", "java $JAVA_OPTS -Djava.security.egd=file:/dev/./urandom -jar /app.jar" ]
```

The first line defines that the image will be generated from an image that contains JDK 1.8. After that we define a volume and add the packaged application to the image. The last command in this `Dockerfile` executes the JSF application.

To build and run the two dockerized instances of the JSF application, let's issue the following command from the root directory:

```bash
# build the dockerized application image
docker build -t without-spring-session .

# running instance number one
docker run -d -p 8081:8080 --name without-spring-session-1 -e "APPLICATION_TITLE=First instance" without-spring-session
# running instance number two
docker run -d -p 8082:8080 --name without-spring-session-2 -e "APPLICATION_TITLE=Second instance" without-spring-session
```

The first command builds the image naming it as `without-spring-session` to easily identify that it is an image with no Spring Session configured. After that we run two instances of this image. We define that the first instance being run will have its port `8080` tied to port `8081` in our development machine. And the second instance will have port `8080` tied to port `8082`. Note that we also define distinct values to the environment variable named `APPLICATION_TITLE`. This is the title that the JSF application shows in the *Request handled by* message when reordering the data table.

By opening `http://localhost:8081/index.jsf` on a tab of our web browser and `http://localhost:8082/index.jsf` on another tab, we can see that we have two distinct applications running apart. They do not share a common state (i.e. an HTTP session). This means that if we reorder the data table on instance *number one*, nothing will happen with instance *number two*. We can refresh the page an check that the second tab will have the data table unaltered.

## Integrating Spring Boot with Spring Session

Integrating Spring Boot with Spring Session is very easy. We have to take only four small steps. The first one is to add two dependencies to our project: Spring Session and a external session store (we will use [Redis](https://redis.io/) in this article). To add these dependencies, let's open the `pom.xml` file and add the following elements to the `<dependencies/>` element:

```xml
<dependencies>
  
  <dependency>
    <groupId>org.springframework.session</groupId>
    <artifactId>spring-session</artifactId>
    <version>1.3.1.RELEASE</version>
  </dependency>
  <dependency>
    <groupId>org.springframework.session</groupId>
    <artifactId>spring-session-data-redis</artifactId>
    <version>1.3.1.RELEASE</version>
    <type>pom</type>
  </dependency>
</dependencies>
```

After that we need to tell our `Application` that we are going to use Spring Session with Redis to manage HTTP sessions. We do this by adding the `@EnableRedisHttpSession` annotation to the `Application` class.

```java
// ...
import org.springframework.session.data.redis.config.annotation.web.http.EnableRedisHttpSession;

@SpringBootApplication
@EnableRedisHttpSession
public class Application {
  // ...
}
```

Since HTTP session will be handled by an external session store (Redis), we will need to add the `Serializable` interface to everything that gets added to users' sessions— this interface tells the JVM that the classes that use it are subject to serialization over the network, to disk, etc. In this case, we have to update only the `Product` class.

```java
//...
import java.io.Serializable;

public class Product implements Serializable {
  // ...
}
```

Last step is to configure the Spring Session connection to Redis. This is done by adding the following properties to the `application.properties` file:

```bash
# ... other properties
spring.redis.host=172.17.0.1
spring.redis.password=secret
spring.redis.port=6379
```

The properties above point to a Redis instance running on `localhost:6379`, which doesn't exist yet. We will tackle that now.

## Dockerized Redis Instance

As we don't want to install Redis on our development machine, we are going to use Docker to run it. To do that we are going to create a `Dockerfile` in a new directory called `./redis`. The contents of this file will be:

```bash
FROM redis
ENV REDIS_PASSWORD secret
CMD ["sh", "-c", "exec redis-server --requirepass \"$REDIS_PASSWORD\""]
```

The file above starts by defining the [official Redis image](https://hub.docker.com/_/redis/) as the base for our own image, and then define `secret` as the password for connecting to Redis. To build and run this image, we can issue the following commands:

```bash
# create redis image
docker build -t spring-session-redis redis

# run redis
docker run -p 6379:6379 -d --name spring-session-redis spring-session-redis
```

Redis is now available to the Spring Session module that we've just configured in our JSF application. Therefore, we are ready to rebuild our JSF application, build the new Docker image (now with Spring Session), and then run both instances based on this new image.

> **Note** that the first command below removes the two instances created before. This is needed to release ports `8081` and `8082` on our development machine.

```bash
# remove previous instances
docker rm -f without-spring-session-1 without-spring-session-2

# compile and package the application
mvn clean package

# build the dockerized application image
docker build -t spring-session .

# running instance number one
docker run -d -p 8081:8080 --name spring-session-1 -e "APPLICATION_TITLE=First instance" spring-session
# running instance number two
docker run -d -p 8082:8080 --name spring-session-2 -e "APPLICATION_TITLE=Second instance" spring-session
```

After executing these commands, the last step that we will need to perform to tie everything together is to create an NGINX instance that behaves as a load balancer.

## Load Balancing with NGINX

To load balance requests between the two instances we will use the `Dockerfile` and the `nginx.conf` file that exist in the `./nginx` folder of the repository. The `Dockerfile` (contents below), simply enables the creation of an image based in the [official NGINX image](https://hub.docker.com/_/nginx/) with a configuration defined in the `nginx.conf` file.

```bash
FROM nginx
RUN rm /etc/nginx/conf.d/default.conf
COPY nginx.conf /etc/nginx/conf.d/default.conf
```

The `nginx.conf` file configures NGINX to act as a load balancer that uses the round-robin algorithm to distribute HTTP requests between instances. As we can see through the contents below, this file defines an `upstream` that contains both instances, and then defines that any request should be redirected to one of these instances. By not explicitly defining any strategy in the `upstream` property, NGINX uses the default one (round-robin).

```bash
upstream my-app {
    server 172.17.0.1:8081 weight=1;
    server 172.17.0.1:8082 weight=1;
}

server {
    location / {
        proxy_pass http://my-app;
    }
}
```

To build and run the NGINX load balancer image, we can issue the following commands:

```bash
# build the dockerized NGINX load balancer
docker build -t spring-session-nginx nginx

# run load balancer
docker run -p 8080:80 -d --name spring-session-nginx spring-session-nginx
```

And Voila! We got our JSF application horizontally scaled with Spring Session handling HTTP sessions with the help of Redis. Now, whenever we issue an HTTP request to `http://localhost:8080`, we may get an answer from one instance or another. Just load this URL in your web browser and reorder the data table a few times. You will see that sometimes one instance of our application will respond to the reordering event, sometimes the other instance will.

## Aside: Securing Spring Boot Applications with Auth0

One of the most complex features to implement in an application is [user authentication and identity management](https://auth0.com/user-management). [Security for authentication and identity](https://auth0.com/docs/security) is [an entire glossary](https://auth0.com/identity-glossary) unto itself.

![Auth0 hosted login screen](https://images.ctfassets.net/23aumh6u8s0i/4ve30M1qt7GmE2nAYNKOhs/358e1f9aab4405b66fbeb5ca4cfa1eae/angular-aside-login)

If you need to implement a robust, highly customizable [identity and access management](https://auth0.com/user-management) system quickly and easily for your Spring Boot application, Auth0 can help. Take a look at [Securing Spring Boot with JWTs](https://auth0.com/blog/securing-spring-boot-with-jwts/) to properly secure your application.

> 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. [A generous **free tier**](https://auth0.com/pricing) is offered so you can get started with modern authentication.

## Conclusion

Using Spring Session to handle HTTP sessions is an easy task. Spring Boot makes it even easier, requiring just a few small steps to configure everything in an application. The problem is that this kind of architecture is not frequently used and that there are few resources that teach us how to integrate all the moving pieces together. I hope that, by making this article available, Java developers that use Spring and mainly those that use JSF (which heavily depends on HTTP session) will be able to scale their application without struggling so much.

Horizontal Scaling JSF Applications with Spring Session

Spring Boot can leverage any type of applications, not only microservices. Let's build a JSF application with Spring Boot.

Developing JSF applications with Spring Boot

eHk3ciM

I am the Group Manager, Developer Content at Okta, and a Google Developer Expert in Web Technologies and Angular. I'm passionate about identity, authentication, constant learning, and developer communities. As a developer advocate, engineer, mentor, and international speaker, I love learning from and sharing with other inhabitants of the tech space.

Group Manager, Developer Content

Kim Maida

Learn about scope, closures, data flow, and concepts commonly utilized in modern JS frameworks & applications.

Glossary of Modern JavaScript Concepts: Part 2

Many developers are overwhelmed by the rapidly expanding ecosystem of modern JavaScript. Learn how to manage and mitigate JS fatigue.


**TL;DR:** Most JavaScript developers have heard of or experienced JavaScript fatigue. JS fatigue is the overwhelming sense that we need to learn most of the hottest emerging technologies in order to do our jobs well. This is unattainable and the stress we feel to achieve it is unjustified; so how do we manage and combat JavaScript fatigue?

---

![JavaScript fatigue comic](https://images.ctfassets.net/23aumh6u8s0i/4NFPPvHmFXs1H0bRHVjuHv/0ffdc8fb11a7e58f586f0b3a92e2f0bb/comic)
_[View larger](https://cdn.auth0.com/blog/js-fatigue/comic.png)_

## What is JavaScript Fatigue?

Putting satire aside, _JavaScript fatigue_ is on a lot of developers' tongues and blogs recently, and with valid reason. But what does it mean to have JS fatigue? It's often mentioned when someone hears about a new library, framework, dependency manager, build tool, etc. Let's do a quick breakdown of what JS fatigue means.

### JS Fatigue vs. Analysis Paralysis

JS fatigue is often linked with [analysis paralysis](https://en.wikipedia.org/wiki/Analysis_paralysis) (also called _choice paralysis_). JS analysis paralysis can occur because of the huge range of options when selecting a framework, tooling, testing suites, and more for a new application. Choosing the right framework or library can be challenging and occasionally even paralyzing, but having a wealth of tools at our disposal allows us to be more selective about what's best for the job at hand. In some cases, options help us to _avoid_ fatigue by supplying an ideal solution for a specific project.

### What it Means to Have JS Fatigue

We get JS fatigue when the requirements (either actual or self-imposed) for learning something are so daunting that a developer becomes exhausted and overwhelmed.

JS fatigue can refer to:

* the fear that we'll fall behind or become obsolete if we don't know and use the newest, hottest tools;
* the sense that we never become experts in anything because everything changes too quickly and the tools we're trying to learn are already being replaced;
* picking up a new framework and then becoming overwhelmed thinking we need to master everything in the toolchain in order to use it;
* the fear that we'll pick a tool that will get displaced, resulting in a lack of support and obsolete resources;
* frustration with a lack of user empathy when consulting documentation or resources while trying to learn a new framework or toolchain.

## JavaScript's Astonishing Growth Rate

In a nutshell, JS fatigue has become a phenomenon because the JS landscape is ever-changing. Various build tools, transpilers, and syntax additions are considered par for the course. There are even [dozens of _entire languages_ that compile to JS](https://github.com/jashkenas/coffeescript/wiki/list-of-languages-that-compile-to-js).

The exponential and unslowed growth of JS has opened the doors for great tools, languages, and frameworks. However, this also promotes change so rapid it can make any developer's head spin. [The Deep Roots of Javascript Fatigue](https://segment.com/blog/the-deep-roots-of-js-fatigue/) delves into the history of JS and its swift evolution over a short amount of time. It's a great read and highly recommended.

Only a few years ago, most programmers considered _front-end development_ to consist primarily of HTML, CSS, and UI-enhancing JavaScript (such as jQuery). Since then, JS alone has proliferated into [isomorphic JS](http://isomorphic.net/javascript), [functional reactive programming](https://auth0.com/blog/glossary-of-modern-javascript-concepts/#functional-reactive-programming) [in](https://www.sitepoint.com/functional-reactive-programming-rxjs/) [JS](https://www.infoq.com/articles/virtual-panel-reactive-javascript-and-elm-in-2016), [frameworks, libraries, build](https://medium.com/javascript-scene/top-javascript-frameworks-topics-to-learn-in-2017-700a397b711#.fuxwtb909) [tools, package managers, and much more](http://stackoverflow.com/questions/35062852/npm-vs-bower-vs-browserify-vs-gulp-vs-grunt-vs-webpack). We used to refer to "front-end" wholistically as all client-side development, but JS has evolved to support a specialization: _JavaScript developers_.

## How to Manage JS Fatigue

At this time, JS proliferation is _not_ showing signs of slowing. JS fatigue doesn't have a magic bullet cure, but there are things we can do to manage and also mitigate it. **The following tips are useful for overwhelmed new developers as well as experienced, fatigued JS engineers.**

### Pick Your Battles

The first thing to focus on is picking your battles. We get easily overwhelmed trying to follow every hot new thing that emerges. **It's good to be _aware_ of the sea of new technologies, but not to drown in it.** If something starts to come up a lot, read a little about it. You'll want to know just enough to answer the following:

1. What is its primary purpose?
2. Is it popular enough to have a stable, growing community and easily accessible support? (Who is behind it? Who is using it?)
3. Does it _solve_ a problem I frequently run into with my current tools?

If #1 isn't practical for your use case and the answers to #2 and #3 are not both _yes_, don't expend precious time and effort learning this if you're already fatigued. **It can be best to wait and see, or to take a pass on tools that don't serve your goals.** [Make peace with your focus](https://medium.com/javascript-scene/why-im-thankful-for-js-fatigue-i-know-you-re-sick-of-those-words-but-this-is-different-296fae0c888f#.h81mamgiv) and remember that _no_ JS developer is an expert in every new tool that lands.

<include src="TweetQuote" quoteText="Pick your battles: It can be best to wait and see, or to take a pass on tools that don't serve your goals."/>

In fact, it can make us _better developers_ to know when to be okay with _not_ learning some new tool. You may have heard the expression "[Jack of all trades, master of none](https://en.wikipedia.org/wiki/Jack_of_all_trades,_master_of_none)", which implies superficial knowledge in many things but expertise in none of them. Remember that **you're _not_ obligated to learn everything** and you can excel at your craft without jumping on every bandwagon that rolls up to the curb.

On the other hand, **if a tool has gained critical mass _and_ will help you solve a problem you're having, it's worth further exploration**. Don't feel like you have to commit to learning it right away, but it might help to find out a little more and keep an eye on it.

<include src="TweetQuote" quoteText="Pick your battles: if a tool has gained critical mass and helps you solve a problem, it's worth exploration."/>

### Make Something Interesting / Useful

For many developers, there are two primary ways we learn something new in a short amount of time:

1. We need to learn it in order to complete a project with predefined requirements and a deadline, or:
2. We build something on our own that we're interested in.

Learning anything can be arduous and tedious if we don't have a clear view of the end result or real-world practicality. On the same token, **learning is much more gratifying when we're building something interesting or useful**.

One good way to learn new tools and frameworks is to make the same thing (something useful that you like) using different tools.  This [shouldn't be the ubiquitious and tiresome TODO app](https://hackernoon.com/cure-for-js-fatigue-build-something-more-interesting-afaf74b95682#.bi5mnqt96). It should be something that covers many common features of modern applications, such as:

* Routing
* Global header and footer
* CSS framework integration
* Responsive UI and custom styles
* Global application data
* External API
* Services and utilities

This has several advantages for learning.

* **Familiarity**: knowing what you're trying to achieve and not making it up as you go along makes development more straightfoward.
* **Comparison**: rebuilding something reveals similarities and differences as well as highlights strengths and weaknesses between frameworks.
* **Iteration**: you may find that each time you go through this exercise, you see things you can refine and improve.

It's important to maintain a high level of interest and/or usefulness with your learning app. Creating a robust starter project can help you quickly learn the ins and outs of setup and common features while providing a practical beginning point for future apps you build.

### Be Aware of Common Concepts

Even as JS grows and changes, there are always [concepts shared amongst many new frameworks and libraries](https://auth0.com/blog/glossary-of-modern-javascript-concepts). It's useful to keep an eye out for these tools and topics. For example, [ES6](https://auth0.com/blog/a-rundown-of-es6-features) and [TypeScript](https://www.typescriptlang.org/) are becoming more heavily used, as well as [Webpack](https://webpack.github.io/), [functional reactive programming](https://vincenttunru.com/Javascript-reactive-programming/), and [web components](https://auth0.com/blog/web-components-how-to-craft-your-own-custom-components/). **Knowing about common dependencies makes different frameworks feel more similar.**

When you take the plunge with a new framework and toolchain, you'll learn some of the common topics. You'll be pleased to find that other modern frameworks leverage many of the same tools and concepts and are now much easier to pick up.

### Learn Iteratively

Many developers are fatigued by the fact that new frameworks have so many complex dependencies that it takes weeks to set up a new app. Don't be afraid to use tools if they help. If a CLI is available or the community offers starter projects, take advantage of them. **Getting off the ground quickly allows you to focus on learning the core features and avoid getting discouraged by difficult setup.**

It's ideal to know how and why something works so it's less magical, but [that _doesn't_ mean you need to frontload that knowledge before getting started](https://medium.com/building-kwoosh/you-dont-need-more-knowledge-83c5247e8f60#.yvz0arns4). Don't worry if you find yourself picking it up along the way. When you hit a roadblock, work through it. Remember to take breaks if you get frustrated. **"Learn as you go" is a legitimate, effective method for absorbing lots of new information over time.** Once you've done the basics, the _how_ and _why_ reveal themselves, either in "Ah-ha!" moments or gradually with repeated use.

<include src="TweetQuote" quoteText="'Learn as you go' is a legitimate, effective way to absorb lots of new information over time."/>

## Aside: Use Auth0 For Authentication in JS Apps

Taking advantage of knowledge, tools, and solutions from others is extremely valuable when combating JS fatigue. Authentication can be one of the most complex, time-consuming features to build for _any_ application. Developers who are already learning a new toolchain, library, or framework can become even more overwhelmed building secure, complicated features like authentication.

If you have a JS app that needs authentication, Auth0 can bear the load for any framework. Auth0's [Single Page Application QuickStart guides](https://auth0.com/docs/quickstart/spa) and [Auth0 SDK for Web](https://auth0.com/docs/libraries/auth0js) provide indepth documentation for robust identity and user management in JS apps. Auth0 makes authentication straightforward, greatly reducing fatigue and cognitive burden for busy developers.

Don't be hesitant to utilize the proper tools and services that will help you do your job and do it well. We're much less fatigued by new things when we have help completing difficult tasks. If authentication is one of your primary needs, you can learn more in the [Auth0 docs](https://auth0.com/docs) or [sign up for a free account here](https://auth0.com/signup).

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

## Conclusion

We'll finish with an analogy. If JS is the world around you, there are a few ways to view and take it in.

If you look at the JS world through a **telescope**, you can see _one thing very clearly_. However, you're essentially blind to everything _else_ around you. It's important to be comfortable with your focus, but not to the point that you shut out awareness of any other possibilities.

If you view the world as a panorama through a **wide-angle lens**, you get a vast, comprehensive picture but it's hard to know where to look. Everything in the scene competes for your attention and you can get easily distracted when trying to focus if something else catches your eye. This can be exhausting.

Now consider a normal **pair of glasses**. You can see everything more clearly, but still focus your attention on one (or a few) things without losing sight of what's in your periphery.

When viewing the modern JavaScript landscape, glasses are a good approach. Don't feel like you have to take in all your surroundings at once, but don't blind yourself to the larger world either. Focus your time and effort on what's in front of you while surveying occasionally for potential improvements. Hopefully you'll find yourself feeling more refreshed and enthusiastic about the great things JavaScript has in store for the future.

> 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.


How to Manage JavaScript Fatigue

56227bdd539c480cc054eaa72eb1885d?s=200 avatar

56227bdd539c480cc054eaa72eb1885d?s=200

Antonio Sanso

JSON Web Encryption is vulnerable to a classic Invalid Curve Attack. Learn how this may affect you and what to do about it.



---

**TL;DR** If you are using [go-jose](https://github.com/square/go-jose), [node-jose](https://github.com/cisco/node-jose), [jose2go](https://github.com/dvsekhvalnov/jose2go), [Nimbus JOSE+JWT](https://bitbucket.org/connect2id/nimbus-jose-jwt/wiki/Home) or [jose4](https://bitbucket.org/b_c/jose4j/wiki/Home) with [ECDH-ES](https://tools.ietf.org/html/rfc7518) please update to the latest version. [RFC 7516 aka JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) and software libraries implementing this specification used to suffer from a classic [Invalid Curve Attack](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.107.3920&rep=rep1&type=pdf). This can allow an attacker to recover the secret key of a party using JWE with [Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES)](https://tools.ietf.org/html/rfc7518), where the sender could extract receiver’s private key.

---

## Premise

In this blog post I assume you are already knowledgeable about elliptic curves and their use in cryptography. If not [Nick Sullivan](https://twitter.com/grittygrease)'s  [A (Relatively Easy To Understand) Primer on Elliptic Curve Cryptography](https://blog.cloudflare.com/a-relatively-easy-to-understand-primer-on-elliptic-curve-cryptography/) or Andrea Corbellini's series [Elliptic Curve Cryptography: finite fields and discrete logarithms](https://andrea.corbellini.name/2015/05/23/elliptic-curve-cryptography-finite-fields-and-discrete-logarithms/) are great starting points. Then if you further want to [climb the elliptic learning curve](https://moderncrypto.org/mail-archive/curves/2016/000784.html) including the related attacks you might also want to visit [https://safecurves.cr.yp.to/](https://safecurves.cr.yp.to/). Also the [DJB and Tanja talk at 31c3](https://www.youtube.com/watch?v=y_YxRUTI-xU) comes with an explanation of this very attack (see minute 43) or  [Juraj Somorovsky et al's research](https://web-in-security.blogspot.com/2015/09/practical-invalid-curve-attacks.html) can become handy for learners.

Note that this research was started and inspired by [Quan Nguyen from Google](https://research.google.com/pubs/pub45790.html) and then refined by [Antonio Sanso from Adobe](https://twitter.com/asanso).

## Introduction

JSON Web Token (JWT) is a JSON-based open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) defined in the [OAuth specification family](https://tools.ietf.org/wg/oauth/) used for creating access tokens. The [Javascript Object Signing and Encryption (JOSE) IETF expert group](https://tools.ietf.org/wg/jose/) was then formed to formalize a set of signing and encryption methods for JWT that led to the release of  [RFC 7515 aka JSON Web Signature (JWS)](https://tools.ietf.org/html/rfc7515) and [RFC 7516 aka JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516). In this post we are going to focus on JWE.

A typical JWE is dot separated string that contains five parts:

* The JWE Protected Header
* The JWE Encrypted Key
* The JWE Initialization Vector
* The JWE Ciphertext
* The JWE Authentication Tag

An example of a JWE taken from the [specification](https://tools.ietf.org/html/rfc7516) would look like:

```
eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGeipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDbSv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaVmqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je81860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi6UklfCpIMfIjf7iGdXKHzg.
48V1_ALb6US04U3b.5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji      SdiwkIr3ajwQzaBtQD_A.XFBoMYUZodetZdvTiFvSkQ
```

This JWE employs RSA-OAEP for key encryption and A256GCM for content encryption :

![JWE Token](https://images.ctfassets.net/23aumh6u8s0i/1dyW4IOQJ2ho2Awh683SGM/88808f9284793e4f0d2f553793149e88/header0)

This is only one of the many possibilities JWE provides. A separate specification called [RFC 7518 aka JSON Web Algorithms (JWA)](https://tools.ietf.org/html/rfc7518) lists all the possible available algorithms that can be used. The one we are discussing today is the [Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES)](https://tools.ietf.org/html/rfc7518).  This algorithm allows deriving an ephemeral shared secret ([this blog post from Neil Madden](https://neilmadden.wordpress.com/2016/05/20/ephemeral-elliptic-curve-diffie-hellman-key-agreement-in-java/) shows a concrete example on how to do ephemeral key agreement).

In this case the *JWE Protected Header* lists as well the used elliptic curve used for  the key agreement:

![JWE Decoded](https://images.ctfassets.net/23aumh6u8s0i/5noTU8YY54mWlpUKyi2Ozq/88c9228b62e82608553b669cde0197b2/header)

Once the shared secret is calculated the key agreement result can be used in one of two ways:

1. Directly as the Content Encryption Key (CEK) for the "enc" algorithm, in the Direct Key Agreement mode, or

2. As a symmetric key used to wrap the CEK with the A128KW, A192KW, or A256KW algorithms, in the Key Agreement with Key Wrapping mode.

This is out of scope for this post but as for the other algorithms the [JOSE Cookbook](https://tools.ietf.org/html/rfc7520) contains example of usage for ECDH-ES in combination with AES-GCM or AES-CBC plus HMAC.

## Observation

As highlighted by Quan during his talk at [RWC 2017](https://www.realworldcrypto.com/rwc2017):

>Decryption/Signature verification input is always under attacker’s control

As we will see thorough this post this simple observation will be enough to recover the receiver’s private key. But first we need to dig a bit into elliptic curve bits and pieces.

## Elliptic Curves

An elliptic curve is the set of solutions defined by an equation of the form:

**y^2 = x^3 + ax + b**

Equations of this type are called *Weierstrass equations*. An elliptic curve would look like:

![Elliptic Curve](https://images.ctfassets.net/23aumh6u8s0i/3JMVwOaOP8hav8C2MS8N74/e52a69e348548f4b51730cfd23defc2b/EC)

**y^2 = x^3 + 4x + 20**

In order to apply the theory of elliptic curves to cryptography we need to look at elliptic curves whose points have coordinates in a finite field Fq. The same curve will then look like below over Finite Field of size 191:

![Field Size](https://images.ctfassets.net/23aumh6u8s0i/2HBFINrYLGCVLAu5XTPzY1/829e76c4db6c3e059cdbcaad63b369ac/ECFP)

**y^2 = x^3 + 4x + 20 over Finite Field of size 191**

For JWE the elliptic curves in scope are the one defined in [Suite B](https://www.nsa.gov/ia/programs/suiteb_cryptography/index.shtml) and ([only recently](https://www.rfc-editor.org/rfc/rfc8037.txt)) [DJB](https://cr.yp.to/djb.html)'s curve.
Between those, the curve that so far has reached the higher amount of usage is the famous P-256.

Time to open [Sage](https://www.sagemath.org/). Let's define P-256:

![P-256](https://images.ctfassets.net/23aumh6u8s0i/1w5nccSNZHZy9uMtZiscOi/1b644b3c53c2740ab5e0364630ebef38/p256)

The order of the curve is a really huge number hence there isn't much an attacker can do with this curve (if the software implements ECDH correctly) in order to guess the private key used in the agreement. This brings us to the next section:

## The Attack

The attack described here is really the classical [Invalid Curve Attack](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.107.3920&rep=rep1&type=pdf). The attack is simple and powerful and takes advantage from the mere fact that Weierstrass's formula for scalar multiplication does not take in consideration the coefficient b of the curve equation:

**y^2 = ax^3 + ax + b**.

The original's P-256 equation is:

![P-256](https://images.ctfassets.net/23aumh6u8s0i/1w5nccSNZHZy9uMtZiscOi/1b644b3c53c2740ab5e0364630ebef38/p256)

As we mention above, the order of this curve is really big. So we need now to find a more convenient curve for the attacker. Easy peasy with Sage:

![Sage](https://images.ctfassets.net/23aumh6u8s0i/7wF06Ez5NZQpbcDNVqTzDL/c86e6f9a18d6954588b623f181859b61/lift)

As you can see from the image above we just found a nicer curve (from the attacker point of view) that has an order with many small factors. Then we found a point P on the curve that has a really small order (2447 in this example).

Now we can build malicious JWEs (see the **Demo Time section** below) and extract the value of the secret key modulo 2447 with complexity in constant time.

A crucial part for the attack to succeed is to have the victim to repeat his own contribution to the resulting shared key. In other words this means that the victim should have his private key to be the same for each key agreement. Conveniently enough this is how the [Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES)](https://tools.ietf.org/html/rfc7518) works. Indeed ES stands for Ephemeral-Static were Static is the contribution of the victim!

At this stage we can repeat these operations (find a new curve, craft malicious JWEs, recover the secret key modulo the small order) many many times and collecting information about the secret key modulo many many small orders.

And finally [Chinese Remainder Theorem](https://en.wikipedia.org/wiki/Chinese_remainder_theorem) for the win!

At the end of the day the issue here is that the specification and consequently all the libraries I checked missed validating that the received public key (contained in the JWE Protected Header is on the curve), You can see the Vulnerable Libraries section below to check how the various libraries fixed the issue.

Again you can find details of the attack in the [original paper](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.107.3920&rep=rep1&type=pdf).

## Demo Time

**[INSTANT DEMO CLICK HERE](https://afternoon-fortress-81941.herokuapp.com/)**

![Demo](https://images.ctfassets.net/23aumh6u8s0i/5X3r9P3BfAM4MJr0pLjxW6/ad911b7bc91929f77e4919d7a542f1e7/attacker)

### Explanation

In order to show how the attack would work in practice I set up a live demo in Heroku. In [https://obscure-everglades-31759.herokuapp.com/](https://obscure-everglades-31759.herokuapp.com/) is up and running one Node.js server app that will act as a victim in this case. The assumption is this: in order to communicate with this web application you need to encrypt a token using the [Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES)](https://tools.ietf.org/html/rfc7518). The static public key from the server needed for the key agreement is in [https://obscure-everglades-31759.herokuapp.com/ecdh-es-public.json](https://obscure-everglades-31759.herokuapp.com/ecdh-es-public.json):

![Demo explanation](https://images.ctfassets.net/23aumh6u8s0i/6hUUsH3W5njnGY5NTNKkl1/852801c26b71b9cbf87db67f8fdaf027/ecdh)

An application that wants to POST data to this server needs first to do a key agreement using the server's public key above and then encrypt the payload using the derived shared key using the JWE format. Once the JWE is in place this can be posted to [https://obscure-everglades-31759.herokuapp.com/secret](https://obscure-everglades-31759.herokuapp.com/secret). The web app will respond with a response status 200 if all went well (namely if it can decrypt the payload content) and with a response status 400 if for some reason the received token is missing or invalid. This will act as an oracle for any potential attacker in the way shown in the previous The Attack section.

I set up an attacker application in [https://afternoon-fortress-81941.herokuapp.com/](https://afternoon-fortress-81941.herokuapp.com/).

You can visit it and click the 'Recover Key' button and observe how the attacker is able to recover the secret key from the server piece by piece. Note that this is only a demo application so the recovered secret key is really small in order to reduce the waiting time. In practice the secret key will be significantly larger (hence it will take a bit more to recover the key).

In case you experience problem with the live demo, or simply if  want to see the code under the hood, you can find the demo code in Github:

* [https://github.com/asanso/jwe-receiver](https://github.com/asanso/jwe-receiver) contains the code of the vulnerable server.
* [https://github.com/asanso/jwe-sender](https://github.com/asanso/jwe-sender) contains the code of the attacker.

## Vulnerable Libraries

Here you can find a list of libraries that were vulnerable to this particular attack so far:

* [node-jose](https://github.com/cisco/node-jose) v0.9.3 include the fixes necessary, which was [published few weeks ago](https://github.com/cisco/node-jose/blob/master/CHANGELOG.md). Here the [Gist](https://gist.github.com/asanso/fa25685348051ef6a28d49aa0f27a4ae) of the original proof of concept.*
* [jose2go](https://github.com/dvsekhvalnov/jose2go)'s fix landed in [version 1.3](https://groups.google.com/forum/).
* [Nimbus JOSE+JWT](https://bitbucket.org/connect2id/nimbus-jose-jwt/wiki/Home) pushed out a fixed artifact to Maven central as v4.34.2. Here the [Gist](https://gist.github.com/asanso/5b8cabb862e6f730e00a97d8565dc325) of the original proof of concept.**
* [jose4](https://bitbucket.org/b_c/jose4j/wiki/Home) now comes with a [fix](https://bitbucket.org/b_c/jose4j/commits/0517896170af8d5c057407c70a7b08dae454829e) for this problem since v0.5.5. Here the [Gist](https://gist.github.com/asanso/350e3ce993e44d0509c6023aa77fc6af) of the original proof of concept.**
* [go-jose](https://github.com/square/go-jose) (this is the original library found vulnerable by [Quan Nguyen](https://research.google.com/pubs/pub45790.html))

Some of the libraries were implemented in a programming language that already protects against this attack checking that the result of the scalar multiplication is on the curve:

\* Latest version of Node.js appears to be immune to this attack. It was still possible to be vulnerable when using browsers without web crypto support.

** Affected was the default Java SUN JCA provider that comes with Java prior to version 1.8.0_51. Later Java versions and the BouncyCastle JCA provider do not seem to be affected.  

## Improving the JWE Standard

I reported this issue to the JOSE working group via [mail to the appropriate mailing list](https://www.ietf.org/mail-archive/web/jose/current/msg05612.html). We all seem to agree that an errata where the problem is listed is at least welcomed. This post is a direct attempt to raise awareness about this specific problem.

## Aside: Securing Applications with Auth0

Are you building a [B2C](https://auth0.com/b2c-customer-identity-management), [B2B](https://auth0.com/b2b-enterprise-identity-management), or [B2E](https://auth0.com/b2e-identity-management-for-employees) tool? Auth0, can help you focus on what matters the most to you, the special features of your product. [Auth0](https://auth0.com/) can help you make your product secure with state-of-the-art features like [passwordless](https://auth0.com/passwordless), [breached password surveillance](https://auth0.com/breached-passwords), and [multifactor authentication](https://auth0.com/multifactor-authentication).

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

## Acknowledgement

The author would like to thanks the maintainers of [go-jose](https://github.com/square/go-jose), [node-jose](https://github.com/cisco/node-jose),[jose2go](https://github.com/dvsekhvalnov/jose2go), [Nimbus JOSE+JWT](https://bitbucket.org/connect2id/nimbus-jose-jwt/wiki/Home) and [jose4](https://bitbucket.org/b_c/jose4j/wiki/Home) for the responsiveness on fixing the issue. [Francesco Mari](https://twitter.com/francescomari) for helping out with the development of the demo application. Tommaso Teofili and Simone Tripodi for troubleshooting. Finally as mentioned above I would like to thank [Quan Nguyen from Google](https://research.google.com/pubs/pub45790.html), indeed this research could not be possible without his initial incipit.

That's all folks. For more crypto goodies, follow me on [Twitter](https://twitter.com/asanso/).

<div class="alert alert-info">
<strong>About Antonio Sanso:</strong><br />
Antonio works as Senior Software Engineer at Adobe Research Switzerland where he is part of the Adobe Experience Manager security team. Antonio is co-author of "OAuth 2 in Action" book. He found vulnerabilities in popular software such as OpenSSL, Google Chrome, Apple Safari and is included in the Google, Facebook, Microsoft, Paypal and Github security hall of fame. He is an avid open source contributor, being the Vice President (chair) for Apache Oltu and PMC member for Apache Sling. His working interests span from web application security to cryptography. Antonio is also the author of more than a dozen computer security patents and applied cryptography academic papers. He holds an MSc in Computer Science.
</div>


Critical Vulnerability in JSON Web Encryption

Protobuf, the binary format crafted by Google, surpasses JSON performance even on JavaScript environments like Node.js/V8 and web browsers.

Beating JSON performance with Protobuf

Inferno is a fast, small, React-like JavaScript UI library.

Learn About Inferno JS: Build and Authenticate an App

bc94ff6211e645a2bdb4fdc60e23ad85

Kassandra Perch

This is transcript and recording of a JSON Web Tokens 101 Webinar we ran a few weeks ago.


<include src="Vidyard" id="t5gytBAKhZPbiHHzhGYLw1" />

## Transcript

Good afternoon. This is Kassandra with Auth0. This webinar is about JWTs. So what I'm going to do is go over what JWTs are used for and then I'm actually going to write a small note application that generates JWTs and show you how they're used in the debugger so that you can write and debug your own JWTs. I have a questions panel open and I will check it from time to time. So if you have a question, feel free to put it in there. Let's get started. I'm going to start by sharing my screen and going over here. 

This rather dry looking document is the RFC for JSON web tokens. It hasn't been changed since 2015. However, I like to bring this up because it's actually one of the easier documents I've found to read. The reason I pull it up is to start talking about what a JWT is. A JWT is a series of JSON objects that are base 64 encoded and then signed with a key. So the reason you would use these, the two most common are used as authentication tokens because you can verify the sender using the key, which is usually signed with a secret, or passing data between two parties, knowing that the party that sent the data is who they say they are, again, because the key is signed with a secret. 

So when we talk about the JSON objects that make up a JWT we're going to start talking about claims. Claims is really just a fancy word for JSON key value pairs, but there are three types of claims, and I'm going to go over them. On my screen now is a list of what are called the reserved or registered claims. These are claims that are held by the JWT standard itself in order to make sure that JWTs can be globally used. These claims are three letters long. That is so you basically have a more compact JSON object. One of the reasons we use JWTs is because they're compact. Registered ones include issuer, expiration time, issued at, which we'll use in our application, and you'll definitely want to look up some of these because they are used on a regular basis, especially GTI, which is an ID or a globally used ID for that particular JSON web token. We'll check the questions. Nope, nothing yet. 

As for public claims, these are claims that are registered in this particular document, and they are again to make JWTs more global. It's just this way with public claims you don't have to modify the RFC every time you want to add a new global claim. As you can see, a lot of the public claims that are available are due to Open ID. Open ID Connect, which is the standard that gives identity to...it's an identity wrapper around the 0Auth authentication specification, is where a lot of our public claims come from, including things like name, email, picture, phone number, things that you would use in an Open ID Connect identity. 

So the last website I'm going to show you before we start working on our JWT generator is the JWT debugger. This is located at JWT.io, and you click on Debugger. What we've got here is, on this left side we've got our JSON web token or JWT. It puts the header in red, the body magenta, and the key in this light blue color. As you can see on the right, it's decoded the header and payload, and it's verifying the signature. Now, you can see the secret is changeable, and this is where the validity of your JSON web tokens comes into play. If I put a different secret than the one that it's expecting, it will say "Invalid signature." So we'll know that it was not sent with the correct secret. We'll talk a little bit more about secrets as we generate our JSON web tokens. No questions in the bin, so I'll keep going. 

What I'm going to start with is I have my terminal open and I'm going to run Node Mon, which is a process that will run my little node scripts. Every time I save it it will refresh it. What I've got in that node file right now is just a bunch of comments. Those are mostly so I don't forget anything. First, some basic house tidying. I'm going to bring in the colors module, which I'm going to use so that our console output is colored in a way that we can see what's going on, and the crypto-module. We're bringing this in for use with the key. When we sign the key we'll use that. I'm also going to set strict mode. It would help if I get...there we go. I'm going to go back to my terminal. Okay, cool. Nothing's gone wrong.

Like I said, the JSON web token consists of a header, a payload, and a key. What we're going to do is welcome the user to our little application here. The reason I used colors is, like I said, it makes it easier to see what's going on in the terminal. So now you can see this, "Welcome to our JWT generator." I'll make this a little bigger. So I've got our JWT generator. Now I'm going to say step one is creating our header. Checking it, and it works. 

So our header usually only consists of two registered claims. These claims are TYP, which stands for type, and it's JWT because it's a JSON web token, and ALG, which stands for algorithm. We're going to use HST56. Now, you can sign JSON web tokens symmetrically, which is what we're doing here. What you use is a secret. That's usually in the form of a string which is shared with the server and the client. However, you can also sign JWTs asymmetrically with a public and private key pair using RSA256. So keep that in mind if you're interested in an asymmetrical way to check that the party is valid. You can use a public/private key pair.

So now that we have our header, let's show our user what our header looks like. Actually, before I do that I'm going to say that our header is JSON.stringify. That's so our header is already in a string. Then I go over here, and as you can see, you can now see what our header looks like as a string. So in order to get our header from that to in the debugger, what we're going to do is base 64 encode it. In order to do that, what we're going to do is say the header is a new buffer with the contents of the original string header, and then call two string on it with base 64 as the argument. That will create our base 64 encoded string.

Then we're going to show our users what that base 64 encoded header looks like. Then we're going to tell the user the header is complete. I'm going to make my header that's encoded red to make it a little easier to see. So when I go over to my terminal you can now see again that same JSON object, and then you can see it base 64 encoded. So our header is complete. Now I'm going to set up our JSON payload.

First I'm going to tell the user that that is step two. Then I'm going to actually create my payload object. Now, I'm going to use a few different claims to go over, again, the difference between registered claims, public claims, and private claims. So I went over registered and public, but I didn't go over private. Private is any claim that you wish to use yourself that's not preregistered either with the specification or with the database. I'm going to check the questions. I just realized it's been a bit. Okay, cool. 

I'm going to use one of each in this payload. First I'm going to use IAT, which is a registered claim. That stands for issued at. So I'm going to use date.now. That will be our issued at time. I'm going to use the public claim of name because, like I showed you over here, in our public claim database, you can see name, full name, and that's registered by the Open ID Connect. So it's actually my full given name. So I'm going to put that there instead. Then finally a private claim. I'm just going to call it My Claim. Again, this is any claim that is not registered either with the specification or the public database. I'm just going to call that True. 

So now I'm going to show the user what my payload looks like. I almost forgot, JSON.stringify. Then payload.green. Let's check the output. As you can see, I've got my time stamp for IAT and then my name, and the private claim My Claim. So now just like before I'm going to base 64 encode this. I'm going to say Payload = New Buffer with the original payload.twostring with the argument base 64. Then I'm going to show this to the user.

Now you can see our payload right there. So now that we have our header and our payload, it's time to construct the key. Now, there are two steps to constructing the key, assembly and then signing it. I'm going to tell the users that the payload is complete. Now I'm going to assemble the key. The key is the header concatenated with the period concatenated with the payload all base 64 encoded. So I'm going to say, "Let key equal header plus a period plus the payload." Then I'm going to show this to the user. Also, notice that step 3A is assembling the key. 

Our key looks like this. Now when I look at the terminal, as you can see I've got my key here and it looks like the header and then a dot and then the payload, just like I said. Now that we've assembled our key, it's time to sign it. This is where the secret comes in. I'm going to tell the user that step 3B is signing the key. So I'm going to create a secret. My secret is going to be a string. Remember, you can use a string with the HST56 or you can use a public/private key pair. However, public/private key pair isn't regularly used. So that's why we're using symmetric today. 

So we've got our secret and we're going to say our secret is 'nyancat'. I'm going to tell our user the secret is...it would help if I put Secret instead of 'nyancat', because otherwise there would be a bit of a problem. So we've got our secret, and I go here, and you can see our secret is 'nyancat'. Now we've got our secret and our unsigned key. We're going to sign our key. This is why we required it in the crypto-library earlier. Notice my Const HMAC is a crypto.create HMAC. I want to use the SHA256 encryption and I'm going to pass out my secret. Then I'm going to update the HMAC with my key. Then finally I'm going to say, "Key = HMAC.digest base 64." So it's base 64 encoded after signing, just like everything else. I'll make sure I did all that right. I did. 

So now we can show the user . . . Key.red. So you can see our key here. All right. Now that we have the key and it's signed, the last step is putting it all together. I'm going to tell the user, and the key is complete.

To put it all together, it will look remarkably like when we put together the key. A finished JWT is the header concatenated with a period, concatenated with the payload, concatenated with a period, concatenated with a signed key. So now I'm going to show the user. 

So when I go over here, as you can see, our JWT is here. Now, I mentioned the debugger earlier and I'm going to show it to you again. First I'm going to check the questions bin. Okay, I don't see anything. Now that we have our finished JWT I'm going to show you how the debugger works with our JWT as opposed to the pre-populated one. So when we go back to JWT.io I'm going to paste our brand new key in there. Just like before I highlighted the header, payload, and the key for us. Now you'll note when I leave it alone and it says Secret, this is an invalid signature. However, everything else is there. That's because we didn't encrypt any of the header or the payload. We just base 64 encoded it. So getting all of that data back out was just base 64 unencoding it, but this invalid signature means we don't have the same secret as our server. So we can't trust that it came from the right source. 

So what I'm going to do is type the secret that we used in our application, 'nyancat', and as you can see the signature is now verified. That's where the security of JWTs comes in. If that signature isn't verified, you cannot trust that the JWT came from the source that it claims to be coming from. Otherwise they would have either that shared secret or a public/private key match.

I'm Kassandra with Auth0, and that's our webinar on JWTs. Thanks for listening!


JWT 101 Webinar Video-- learn more about JSON Web Tokens

d5365965372e0c5843d836f660b51a84?size=200 avatar

d5365965372e0c5843d836f660b51a84?size=200

Jeff Smith

Using JWTs to authenticate your React Native app will help it to be both secure and easy to integrate with a variety of services.

Adding Authentication to Your React Native App Using JSON Web Tokens

6c0654e56c8c73ffee8f76fe03d18ccf?s=80 avatar

6c0654e56c8c73ffee8f76fe03d18ccf?s=80

Alex Sears

JSON Web Tokens (JWT) provide an easy way to add authentication to Ruby apps. Learn all about how to secure your Rack API!



Early on in my career, when I was a wee little junior dev, learning Ruby on Rails and looking to impress, I came across an issue that is all too common these days. How do I authenticate a request with an API when the consuming client is a browser? This is a problem that will need to be solved if you are building a single page application.  At the time, I thought a single numeric "API token" that was returned to the user when they logged in was enough. Looking back, I realize how dumb of a move this was. It's extremely insecure!

Recently, I have been reading that [JSON Web Tokens](https://auth0.com/learn/json-web-tokens/) (also written as JWTs and pronounced "jots") are the way to go when authenticating with an API. If you haven't heard of JWTs, check out [the website](https://jwt.io/) and [read this blog post on using them with APIs](https://auth0.com/blog/2014/12/02/using-json-web-tokens-as-api-keys/). They make authenticating a user securely very easy.

Today, we are going to explore using JWTs in a Ruby environment, specifically with Rack apps. This includes Rails and Sinatra applications. Let's get to it! Create a new directory for this project and move into it.

```
mkdir ruby-jwt-api
cd ruby-jwt-api
```

First, let's setup the basic API itself. Create a `Gemfile` with the following in it.

```
source "https://rubygems.org"

gem 'sinatra'
gem 'jwt'
gem 'json'
```

Then, run `bundle`. If you don't already have bundler installed, run `gem install bundler`. This will install the dependencies we need. Next we need to create our `config.ru` file to run our Sinatra application.  Put the following in a file called `config.ru`.

```
require File.expand_path '../main.rb', __FILE__

run Rack::URLMap.new({
  '/' => Public,
  '/api' => Api
})
```

Here we are loading a file called `main.rb` and then setting up a new Rack application and running it. We create the application this way so we can put our JWT protection on only the API routes and not the public routes. We are loading the file, but we haven't created it yet! Let's do that. Create a file called `main.rb` and put the following in it.

```
require 'json'
require 'jwt'
require 'sinatra/base'

class Api < Sinatra::Base

  def initialize
    super

    @accounts = {
      tomdelonge: 10000,
      markhoppus: 50000,
      travisbarker: 1000000000
    }
  end

  get '/money' do
    content_type :json
    { message: "Hello, World!" }.to_json
  end
end

class Public < Sinatra::Base

  def initialize
    super

    @logins = {
      tomdelonge: 'allthesmallthings',
      markhoppus: 'therockshow',
      travisbarker: 'whatsmyageagain'
    }
  end

  post '/login' do
    username = params[:username]
    password = params[:password]

    if @logins[username.to_sym] == password
      content_type :json
      { message: "You logged in. Yay you!" }.to_json
    else
      halt 401
    end
  end

end
```

This code sets up our two application routes. The only public route we have right now is `/login`. It authenticates a user based on a username and password. Currently, it just returns a confirmation message. This is where we will eventually return a JWT the user can use to authenticate with the API. The API only has one route for now also called `/money`. It returns a simple message now too. Notice, we have hardcoded the values for our users. Normally this would come from a database of some sort.

Run `rackup` on the command line to start the server. Here are what our responses look like if we hit each of these endpoints. We hit the login route and get a success...

![First successful hit to the server endpoint](https://images.ctfassets.net/23aumh6u8s0i/37oTdL3zyegFb024TeBDxY/9104f52d64e6fdf6f46e1a05f75a075e/first_successful_hit)

...hit the login route and get an error...

![First unsuccessful hit to the server endpoint](https://images.ctfassets.net/23aumh6u8s0i/7E72SbsOBfnwiv74PxQNWo/74cc17454812ac79cfbb64ee310dea60/first_unsuccessful_hit)

...and hit the `/api/money` route to make sure our routing works correctly.

![First Successful API Hit](https://images.ctfassets.net/23aumh6u8s0i/5mSTx6nuOTca2kOHhVY1EF/a0f1d9f115419ea560f24dadc16d322b/first_successful_api_hit)

Now that we know our endpoints are working, let's add authentication and authorization using JWTs. We need to make sure that when we log our user in, we return a JWT so the user can use it to authenticate in the future.

```
post '/login' do
  username = params[:username]
  password = params[:password]

  if @logins[username.to_sym] == password
    content_type :json
    { token: token(username) }.to_json
  else
    halt 401
  end
end

def token username
  JWT.encode payload(username), ENV['JWT_SECRET'], 'HS256'
end

def payload username
  {
    exp: Time.now.to_i + 60 * 60,
    iat: Time.now.to_i,
    iss: ENV['JWT_ISSUER'],
    scopes: ['add_money', 'remove_money', 'view_money'],
    user: {
      username: username
    }
  }
end
```

Let's analyze this. We have changed what happens on a successful login. We set the content type to JSON and then return a Hash that has the token in it.

The token is generated by calling the `token` method and passing it the username. `token` uses [the jwt gem](https://github.com/jwt/ruby-jwt) to create an encoded JWT. It takes the payload, the secret, and the algorithm we want to use to sign the token. Our `token` method calls another method we created called `payload` which simply returns a Hash that contains all the data we want in our token payload.

Some things to note about the payload. It has an expiration date, which will be verified later. We also give it an issuer that we can verify later, a set of scopes that this token allows a user to do, and some data about our user. A sample response would look like this.

Restart your server. Make sure to pass the environment variables to it when you run it like so.

```
JWT_SECRET=someawesomesecret JWT_ISSUER=moneyapi.com rackup
```

![Retrieving a Successful JSON Web Token](https://images.ctfassets.net/23aumh6u8s0i/53TJSyy6aNrVQ0HE46bSZI/14262f5c738be70af3d1b76438bdd223/successful_token)

We have our first token! Yay! Notice how I have passed two environment variables on the command line. It's a good practice to pass these sorts of values in environment variables to avoid hardcoding them in our source code. These variables are used when creating (and later validating) our tokens.

Now we need to create a piece of middleware that will validate our token and then add the scopes and user data from the token to the request environment. This will allow us to access this information in our API routes. Add the following to our `main.rb` file.

```
class JwtAuth

  def initialize app
    @app = app
  end

  def call env
    begin
      options = { algorithm: 'HS256', iss: ENV['JWT_ISSUER'] }
      bearer = env.fetch('HTTP_AUTHORIZATION', '').slice(7..-1)
      payload, header = JWT.decode bearer, ENV['JWT_SECRET'], true, options

      env[:scopes] = payload['scopes']
      env[:user] = payload['user']

      @app.call env
    rescue JWT::DecodeError
      [401, { 'Content-Type' => 'text/plain' }, ['A token must be passed.']]
    rescue JWT::ExpiredSignature
      [403, { 'Content-Type' => 'text/plain' }, ['The token has expired.']]
    rescue JWT::InvalidIssuerError
      [403, { 'Content-Type' => 'text/plain' }, ['The token does not have a valid issuer.']]
    rescue JWT::InvalidIatError
      [403, { 'Content-Type' => 'text/plain' }, ['The token does not have a valid "issued at" time.']]
    end
  end

end
```

This is a simple Rack middleware setup. In the `call` method, we get the `HTTP_AUTHORIZATION` value out of the environment hash, which represents the `Authorization` header in the request.  We use `fetch` so we get a string if `HTTP_AUTHORIZATION` doesn't exist and then use `slice` to prevent throwing an error if the string indexes we want don't exist. This will strip off the "Bearer: " part of the `Authorization` header. We then decode the JWT and add the scopes and user data to the environment hash. Lastly, we call the next part in our middleware stack and pass it our modified environment.

We have wrapped this code in a `begin, rescue`. This is because the `jwt` gem will throw different exceptions for each thing that may be wrong with it, such as the validation not passing. We catch each one and return a good error message for it.

Now that we have the data available on our request environment, let's use it in our API route.

```
class Api < Sinatra::Base

  use JwtAuth

  def initialize
    super

    @accounts = {
      tomdelonge: 10000,
      markhoppus: 50000,
      travisbarker: 1000000000
    }
  end

  get '/money' do
    scopes, user = request.env.values_at :scopes, :user
    username = user['username'].to_sym

    if scopes.include?('view_money') && @accounts.has_key?(username)
      content_type :json
      { money: @accounts[username] }.to_json
    else
      halt 403
    end
  end

end
```

Here, we initialize the class with some data, like we did with the `Public` class. Notice we `use JwtAuth` in this class. This is our way of including our token authentication middleware. This causes it to be run before the routes on this class are run. We then setup a `/money` route. This route grabs the scopes and user out of the environment. It then gets the username out of the user data. It checks to make sure this token has the `view_money` scope and that the username is a valid one in the data we have. If all this checks out, it returns the amount of money in the account. That's all there is to it.

![Hiting the Get Money route](https://images.ctfassets.net/23aumh6u8s0i/2hmmyaWekQu2TTSqsagON2/0ca839945394450177cb232ffa92bb9b/get_money)

We can use this same setup to add and remove money from these accounts.

```
post '/money' do
  scopes, user = request.env.values_at :scopes, :user
  username = user['username'].to_sym

  if scopes.include?('add_money') && @accounts.has_key?(username)
    amount = request[:amount]
    @accounts[username] += amount.to_i

    content_type :json
    { money: @accounts[username] }.to_json
  else
    halt 403
  end
end

delete '/money' do
  scopes, user = request.env.values_at :scopes, :user
  username = user['username'].to_sym

  if scopes.include?('remove_money') && @accounts.has_key?(username)
    amount = request[:amount]

    @accounts[username] -= amount.to_i
    if @accounts[username] < 0
      @accounts[username] = 0
    end

    content_type :json
    { money: @accounts[username] }.to_json
  else
    halt 403
  end
end
```

Here we are doing similar work as the previous route except we are sending `POST` and `DELETE` requests to add and remove money.  Our output would look like this when adding money...

![Adding Money using the API endpoint](https://images.ctfassets.net/23aumh6u8s0i/6cREs0pHtL5ghb0aT9QHMc/5c45ddd136e86614f197c0427bc3f501/add_money)

...and when removing money.

![Deleting Money using the API endpoint](https://images.ctfassets.net/23aumh6u8s0i/4AGDt3bC0dQJGI3PyRpD5F/94877eba401879712cac3e1765c5d579/delete_money)

As you can see, we can now use JWTs to add and remove money also. You may have noticed that we have some duplicated code here though. That's not good when we can prevent it! Luckily, we can. We can refactor our code like so.

```
get '/money' do
  process_request request, 'view_money' do |req, username|
    content_type :json
    { money: @accounts[username] }.to_json
  end
end

post '/money' do
  process_request request, 'add_money' do |req, username|
    amount = req[:amount]
    @accounts[username] += amount.to_i

    content_type :json
    { money: @accounts[username] }.to_json
  end
end

delete '/money' do
  process_request request, 'remove_money' do |req, username|
    amount = request[:amount]

    @accounts[username] -= amount.to_i
    if @accounts[username] < 0
      @accounts[username] = 0
    end

    content_type :json
    { money: @accounts[username] }.to_json
  end
end

def process_request req, scope
  scopes, user = req.env.values_at :scopes, :user
  username = user['username'].to_sym

  if scopes.include?(scope) && @accounts.has_key?(username)
    yield req, username
  else
    halt 403
  end
end
```

We have extracted the common code out into its own method and pass in the functionality for each route into the `process_request` method as a block.

That's all there is to it. We can now use our `JwtAuth` middleware anywhere we want to protect routes with JSON web tokens.

![Drop the mic](https://images.ctfassets.net/23aumh6u8s0i/71PTFQvHyCb4tSTO4bUwr8/611c9310a6b1713a01992f3eb6a2a142/giphy)

## What about Auth0?

[Auth0](https://auth0.com/) handles all this business of authenticating your users and creating JWTs so you can concentrate on building your application. There's even [a gem](https://github.com/auth0/ruby-auth0) that makes interacting with the Auth0 API so much easier. Let them handle the boring authentication while you build the next MyFaceTwiSterGram.

Wanna integrate Auth0 with RoR? Simple. The excellent writers over at Auth0 have you covered. They have written [extensive documentation](https://auth0.com/docs/quickstart/webapp/rails/) on how to do just that. It goes a little something like this.

### Add Omniauth and Auth0's strategy

Add the following to your `Gemfile` and run `bundle install`.

```
gem 'omniauth', '~> 1.3'
gem 'omniauth-auth0', '~> 1.4'
```

### Initialize Omniauth

Put the following in a file at `config/initializers/auth0.rb`, replacing the ALL_CAPS values with their actual values received when creating an application on the Auth0 dashboard.

```
Rails.application.config.middleware.use OmniAuth::Builder do
  provider(
    :auth0,
    'YOUR_CLIENT_ID',
    'YOUR_CLIENT_SECRET',
    'YOUR_NAMESPACE',
    callback_path: "/auth/auth0/callback"
  )
end
```

### Add the callback handler for Auth0

Use this command to create a controller to handle the Auth0 callback.

```
rails generate controller auth0 callback failure --skip-template-engine --skip-assets
```

In this newly-created file, add the logic to handle the success and failure of the callback.

```
class Auth0Controller < ApplicationController
  def callback
    # This stores all the user information that came from Auth0
    # and the IdP
    session[:userinfo] = request.env['omniauth.auth']

    # Redirect to the URL you want after successfull auth
    redirect_to '/dashboard'
  end

  def failure
    # show a failure page or redirect to an error page
    @error_msg = request.params['message']
  end
end
```

Also, replace the routes we created earlier with the following ones instead.

```
get "/auth/auth0/callback" => "auth0#callback"
get "/auth/failure" => "auth0#failure"
```

### Add the callback to Auth0's dashboard

You need to make sure you add the callback URL to the [Application Settings](https://manage.auth0.com/#/applications) in the Auth0 dashboard area.

For example, the callbacks we have created will be reached at `http://yourUrl/auth/auth0/callback`.

### Pick a method of triggering the login

There are multiple ways you can trigger the login flow in your application. For example, you could use the Auth0 Lock widget, Passwordless, or some custom UI. Here is what the code would look like to use the Lock widget in modal form.

```html
  <script src=“https://cdn.auth0.com/js/lock/10.0/lock.min.js"></script>
  <script type="text/javascript">

    var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_NAMESPACE');


    function signin() {
      lock.show({
        callbackURL: '',
        responseType: 'code',
        authParams: {
          scope: 'openid email'  // Learn about scopes: https://auth0.com/docs/scopes
        }
      });
    }
  </script>
  <button onclick="window.signin();">Login</button>
```

### Accessing User Info

Once all this is setup, you can access user information like you normally would when using the Omniauth gem and its provider gems.

```ruby
class DashboardController < SecuredController
  def show
    @user = session[:userinfo]
  end
end
```

```html
  <div>
    <img class="avatar" src="<%= @user[:info][:image] %/>"/>
    <h2>Welcome <%= @user[:info][:name] %></h2>
  </div>
```

This is only a portion of the information you can get from their docs. [Head over there](https://auth0.com/docs/quickstart/webapp/rails) to get more information on integrating with Rails.

## Authentication is hard

Authentication in a web application can be difficult. However, whether you use Auth0 or roll your own solution, the `jwt` ruby gem offers a simple way to use JWTs in your ruby application. This allows stateless authentication that can be used in a traditional application or a decentralized API.

<include src="TweetQuote" quoteText="Authentication in a web application can be difficult. However, Auth0 simplifies it with JWTs."/>


Ruby Authentication: Secure Your Rack Application with JWT

Secure your internet-connected NodeBots projects with JSON Web Tokens.

# Securing your NodeBots with JSON Web Tokens

NodeBots are amazing! One of the best things about them is that you can connect them to the internet in new and amazing ways. This can include controlling NodeBots via your own Node.JS API!

However, this can lead to some interesting scenarios regarding security-- especially if you choose to control a system like a door lock via NodeBots. Without a cloud service like Particle's Cloud or Electric Imp's agent/client system, security can be tricky! Even with third-party cloud solutions providing basic security, this security mainly covers your API's communication with your NodeBot-- not the internet's communication with your API!

Luckily for us, NodeBots means Node, and Node has several easy-to-use security systems. One way is to use JSON Web Tokens as a bolstered authentication system for your NodeBots server.

## What are NodeBots?

Just in case you've never heard of them, NodeBots refers to any project that runs hardware with Node.JS or javascript in some form or another. One of the most popular frameworks for this is [johnny-five](http://johnny-five.io). An example of a NodeBot is this Rose Pin, which allows people to change the color of the lights inside the rose via a web interface:

![The NodeBots Rose Pin](https://images.ctfassets.net/23aumh6u8s0i/3l1EppfHNEPrnft7fbzSfL/d6ced699d8f901c9d739fe3b9ce9aa07/nodebots)

## JSON Web Tokens

If you've never used JSON Web Tokens, there is some great introductory material [at jwt.io](https://auth0.com/learn/json-web-tokens/).

When using your own Node server for robotics control and code, JSON Web Tokens can provide an extra level of security-- especially when you're stuck on HTTP. JSON Web Tokens use a payload, encryption, and either a secret or private/public key pair in order to provide a signed token that allows you to verify that your NodeBots APIs are only being used by you (or other NodeBots and users that you approve)!

<include src="TweetQuote" quoteText="When using your own Node server for robotics control, JSON Web Tokens can provide an extra level of security"/>

In order to use JSON Web Tokens with NodeBots, you'll want to look into [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken). This library allows you to create JSON Web Tokens:

```javascript
var jwt = require('jsonwebtoken');
var myToken = jwt.sign({ user: 'username' }, 'my secret');
```

the `.sign()` method takes a payload (which is a javascript object that will be converted to JSON), and a secret-- JWT, unlike other token types, allows for not only the use of secrets, but the use of public/private key pairs:

```javascript
var cert = fs.readFileSync('private.key');  // get private key
var token = jwt.sign({ sensorData: 1024 }, cert, { algorithm: 'RS256'});
```

Once you have your token, it's safe to pass as an authentication header:

```
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoidGVzdCIsImlhdCI6MTQ0NjUyNDM5NH0.NDlWo8qunNFJvU9GGTeniAfUxwV0z38LhgkN57m-hvI
```

Want to learn even more about JWT tokens before getting started? Check out Auth0's [extensive documentation on the subject at JWT.io](http://jwt.io). You can also read about the different ways to sign JWT's in [this blog post.](https://auth0.com/blog/2015/12/17/json-web-token-signing-algorithms-overview/)

## Using JWT for request authentication

But how do we check for a valid token on our API requests? You can check headers manually using your own methods, but a very easy way is to use [express-jwt](https://www.npmjs.com/package/express-jwt), an npm module and express middleware. All you have to do is set up this middleware:

```javascript
var express = require('express');
var jwt = require('express-jwt');

var app = express();

app.use(jwt({ secret: 'my secret'});

app.get('/protected', function(req, res){
	res.send('This route requires a JWT to be reached-- this message means you are authenticated!');
});
```

Now all of your requests to this API will require the authentication header to contain a valid JWT token signed with your secret in order to complete-- otherwise they will return with a 401.

## When is this useful for NodeBots?

This technique is mainly useful for Johnny-Five, and other NodeBots projects, that are accessible via the internet. This can include thin clients (e.g. [Particle Photons](http://particle.io) using the [Javascript SDK](https://www.npmjs.com/package/spark)), or [Johnny-Five](http://johnny-five.io) bots that have been made available via local wireless.

This is also useful in situations where you use an external client (be it a client-side app, a different API server, or even a third-party service) to work with your NodeBot. For instance, if you have a GET route that moves a servo, and you don't want someone hacking together a script in a few minutes that takes over movement using that GET request, you can use JWT to lock down that route so only scripts that you've written, containing tokens signed with your secret, can move that servo.

## Aside: User Management with Auth0

If you want to provide a user login for your NodeBots project, you can use Auth0 to manage your users and easily create a login dialog! Check out [Lock](https://auth0.com/lock) for more information. You can implement Lock easily on your front-end and your Node.JS server [with just a few lines of javascript](https://auth0.com/docs/quickstart/spa/vanillajs/nodejs).

For instance, in your web interface's index.html, add

```html
  

  ...

  
  <script src="//cdn.auth0.com/js/lock-7.11.1.min.js"></script>

  ...
```

To call in the Auth0 Lock script. Then, add a login button:

```html
	

	...

	
	<input id="btn-login" class="btn-login" type="submit" />

	...
```

To wrap-up the front-end, add a call to Lock from the login button:

```javascript
document.getElementById('btn-login').addEventListener('click', function() {
  lock.show(function(err, profile, token) {
    if (err) {
      // Error callback
      console.error("Something went wrong: ", err);
      alert("Something went wrong, check the Console errors");
    } else {
      // Success calback  

      // Save the JWT token.
      localStorage.setItem('userToken', token);

      // Save the profile
      userProfile = profile;

      document.getElementById('nick').textContent = profile.nickname;
    }
  });
});
```

Then, on your server, we're going to modify our use of express-jwt to work with the JWTs that Auth0 creates to authenticate users:

```javascript
var express = require('express');
var app = express();
var jwt = require('express-jwt');

var jwtCheck = jwt({
  secret: new Buffer('YOUR_CLIENT_SECRET', 'base64'),
  audience: 'YOUR_CLIENT_ID'
});
```

**Important API Security Note:** If you want to use Auth0 authentication to authorize _API requests_, note that you'll need to use [a different flow depending on your use case](https://auth0.com/docs/api-auth/which-oauth-flow-to-use). Auth0 `idToken` should only be used on the client-side. [Access tokens should be used to authorize APIs](https://auth0.com/blog/why-should-use-accesstokens-to-secure-an-api/). You can read more about [making API calls with Auth0 here](https://auth0.com/docs/apis).

This way, you can easily allow users to log into your NodeBots interface, with just a few lines of JavaScript!

## Other tips

Some things to keep in mind when using this method to protect your robotics APIs:

* **You can revoke access in multiple ways, quickly:** the `jsonwebtoken` API gives you ways to revoke specific tokens, but you can quickly invalidate all tokens by changing your secret.
* **You can provide a login, but you don't have to!:** as long as you can use the API to generate tokens using your secret, you don't need to provide a login interface to the rest of the world.
* **Be sure to set expirations on your tokens:** security is a "better safe than sorry" topic, so be sure to set a lifetime on your tokens to prevent an old token coming back to haunt you!

Hopefully now you're on your way to taking the first steps to secure communications with your NodeBots APIs! I'd really like to see what you build-- let me know [on Twitter](https://twitter.com/nodebotanist).

<include src="asides/Jwt" />

Securing your NodeBots with JSON Web Tokens

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

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 (JWT) Signing Algorithms Overview

ryan-chenkie

Ryan is a full-stack JavaScript developer and trainer who mainly works with React, Angular, Node, and GraphQL. He runs a consultancy where he builds apps for companies and also helps established dev teams with their modern JavaScript challenges.<br /><br />Ryan is a Google Developer Expert, the host of the Entrepreneurial Coder Podcast, the author of Securing Angular Applications, and an all-around fanatic about application security.

Developer

Ryan Chenkie

Conventional authentication is challenging for today's web applications. Learn about the reasons and how to use JSON Web Tokens (JWT) for modern authentication.



---

**TL;DR:** Traditional session-based authentication with cookies presents difficulties, especially for modern web applications. We can instead use JSON Web Tokens (JWT), which make our apps stateless. Migrating a legacy app over to JWT authentication can be done piece by piece, and if we need to, we can use cookies to handle JWTs. To see how this is done, take a look at the [repo](https://github.com/auth0/cookie-jwt-auth) for this tutorial.

---
Authentication for web applications has historically been fairly straightforward and followed a common pattern, but this has been changing significantly in recent years. There are several reasons for these changes, and the prominent ones are related to the way in which modern applications are built and distributed.  In this article, we'll see how things have changed and also some ways we can adapt legacy applications to modern day practices.

## Traditional Web Applications

In a general sense, traditional websites and applications typically implement user authentication using **sessions** and **cookies**. When users log in to a site, their username and password are matched against database entries. If the login is successful, the server saves the user's authentication state in memory and sends a cookie back in the response that contains some data, which in most cases includes the user's ID. Browsers will save the cookie for the domain from which it came and then automatically send it back when subsequent requests are made. For example, if a cookie is saved with a domain of auth0.com, it will be sent back on any future request to auth0.com as long as it is valid. This works great for traditional web apps.

![modern authentication jwt](https://images.ctfassets.net/23aumh6u8s0i/2E0gj0N91SqR18iJcYX0pS/2843825e62cc48a85c287ffad235efc9/legacy-app-auth-1)

Even though we've labeled the process described above as being "traditional", it should be noted that *most* of the web still operates this way. While this approach is still perfectly valid for a lot of use cases, we're going to explore some of the reasons why relying on it has become challenging for modern web applications.

## Authentication Challenges for Modern Web Apps

Modern web applications present a few challenges for authentication that are difficult to solve using conventional methods. The reasons for this have to do with how applications are crafted and the environment in which applications reside.

### 1. Apps are distributed across many servers

Many of today's applications aren't deployed the same way they were in the past. It is now very common--and often necessary--for apps to be distributed across many servers so that up-time is increased and latency issues are mitigated. With this comes the side effect that, when a user accesses an application, it is no longer guaranteed that they are always accessing the same server.

Since traditional authentication relies on the server to keep the user's authentication state in memory, things break down when the app is accessed from different servers. The user might be logged in on one server but not on the others that the application is distributed across.

We can get around this by using methods like [**sticky sessions**](http://stackoverflow.com/questions/10494431/sticky-and-non-sticky-sessions). A sticky session will essentially route the user to the server instance from which they logged in so that the authentication state can be presevered. This type of workaround will do the job, but as we'll see, stateful servers in general don't play that well with modern applications.

### 2. Apps use APIs for data

A common pattern for modern applications, especially single-page apps, is to retrieve and consume JSON data from a [RESTful API](http://www.restapitutorial.com/). Serving data from an API has several distinct advantages, one of them being the ability for data to be used in more than just one application. For example, an organization might start with the intent to build an internally facing application, but may soon realize that some of its functionality could be used in a public-facing app. Down the road, the organization might also decide that some of its data should be accessible by other application developers to build third-party apps with. This can all be made possible with an API.

Using APIs in this fashion is great, but things can become challenging when it comes to authentication. The traditional approach of using sessions and cookies for the user's identity doesn't work so well in these cases because their use introduces **state** to the application. One of the tenets of a RESTful API is that it should be **stateless**, meaning that, when a request is made, a response within certain parameters can always be anticipated without side effects. A user's authentication state introduces such a side effect, which breaks this principle. Keeping the API stateless and therefore without side effect means that maintainability and debugging are made much easier.

<include src="TweetQuote" quoteText="Keeping the API stateless means that maintainability and debugging are made much easier."/>

Another challenge here is that it is quite common for an API to be served from one server and for the actual application to consume it from another. To make this happen, we need to enable [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS). Since cookies can only be used for the domain from which they originated, they aren't much help for APIs on different domains than the application.

### 3. Apps rely on downstream services

Another common pattern seen with modern web applications is that they often rely on downstream services. For example, a call to the main application server might make a request to a downstream server before the original request is resolved. The issue here is that cookies don't "flow" easily to the downstream servers and can't tell those servers about the user's authentication state. Since each server has its own scheme for cookies, there is a lot of resistance to flow, and connecting to them is difficult.

## A Modern Alternative: The JSON Web Token (JWT)

To combat the issues detailed above, we can take a token-based approach by using JSON Web Tokens (JWTs) for authentication. A JWT contains three parts:

**1. Header**

The header tells us about the algorithm and token type. It is Base64URL encoded.

**2. Payload**

The payload contains any arbitrary information in the form of claims that we as developers find useful for our applications. The user's ID must be sent as a `sub` claim, but we can also send other useful information, such as the username, email, and more. The payload is also Base64URL encoded.

**3. Signature**

The signature is used to verify the authenticity of the JWT. There are several different algorithms that can be used for the signature. Some algorithms implement a shared secret (HMAC), and others use public-private key secrets (RSA).

![modern authentication jwt](https://images.ctfassets.net/23aumh6u8s0i/1sS3oSviChEPzlXMAYHHLQ/b58c9c25c3ecb38505a5e77e5965e981/legacy-app-auth-5)

From the user's perspective, logging in to an application that uses JWTs looks much like traditional authentication. Users enter their credentials as usual, but instead of the server creating a session and returning a cookie, it will respond with a JSON object that contains a JWT. The JWT then needs to be saved locally, which is normally done with local storage. However, as we'll see in the next section, it is possible to save the JWT in a cookie.

The JWT must be sent to the server to access protected routes, and it is typically sent as an `Authorization` header. The scheme used for this header is `Bearer`, so the full header looks like this:

```js
Authorization: Bearer <token>
```

Middleware on the protected API routes will check for a valid JWT, and if there is one, it will let the request through and return the data being requested. Since the user's information is contained within the JWT itself, there is no need to look the user up in a database, so there is less latency in the application.

It should be reiterated that the user's state is never saved in memory on the server, meaning that the user isn't "logged in" in the conventional sense. However, a valid JWT gives the user the keys to access data each time a request is made, and in this way, a stateless authentication mechanism is in place.

![](https://images.ctfassets.net/23aumh6u8s0i/1f37fJAPR7UgfFW8oYYeKs/5f00a4413b04510ad6bd6801f04a2fed/legacy-app-auth-2)

Using a JWT for authentication helps to solve the challenges noted above. We can fully rely on data APIs that are stateless and even make requests to downstream services. Since JWT is a specification [implemented nearly everywhere](http://jwt.io), connecting to downstream services built on a stack other than our own is easy. It also doesn't matter which domain is serving our API, nor does it matter which specific server a request goes to if the app is deployed across many.


## Bridging the Gap: Using JWTs in Cookies

Modernizing legacy applications by implementing token-based authentication can lead to many gains. If it isn't feasible for an organization to totally throw away cookies, there are still ways to make token authentication viable. Let's take a look at how this can be done with NodeJS and the **express-jwt** package.

### Step 1: Set Up a Back End

To follow along, you can download Auth0's NodeJS seed project from the [NodeJS Quickstart](https://auth0.com/docs/quickstart/backend/nodejs/). Even though we're using an Auth0 seed project here, doing cookie-based authentication in this way will work with any service.

### Step 2: Install Cookie Parser

Once the dependencies for the seed project are installed by following the [installation steps](https://github.com/auth0/node-auth0/tree/master/examples/nodejs-api), we'll need to add one more package: **cookie-parser**. This package will allow us to read JWTs from cookies that are sent to the server.

```bash
npm install cookie-parser --save
```

With **cookie-parser** installed, we now need to require and use it in `server.js`.

```js
// server.js

...

var cookieParser = require('cookie-parser');

...

app.configure(function() {

  app.use(cookieParser());

  ...

});
```

### Step 3: Save the JWT as a Cookie

We'll need to retrieve a JWT for a user and save it locally as a cookie. If you're using Auth0 for this tutorial, you can find out more about retrieving JWTs for users in your Auth0 account by reading the [API documentation](https://auth0.com/docs/api/v2). We'll use jQuery in this example to make the AJAX calls easy.

Lets make a call to Auth0 to get a JWT.

```js
// app.js

$('.btn-login').click(function() {
  $.ajax({
    type: 'POST',
    url: 'https://{your-auth0-account}.auth0.com/oauth/ro',
    data: {
      client_id: '{your-client-id}',
      username: document.querySelector('#username').value,
      password: document.querySelector('#password').value,
      grant_type: 'password',
      scope: 'openid',
      connection:'Username-Password-Authentication'
    },
    success: function(data) {
      getJwtCookie(data.id_token);
    },
    error: function(error) {
      console.log('There was an error: ' + error)
    }

  });
});
```

In the success handler, we're calling a function called `getJwtCookie` and passing in the token that was received from Auth0. We need to create an endpoint on our application server that can validate the JWT that was received from Auth0 and send it back to us as a cookie, and we can do that in the `getJwtCookie` function.

```js
// app.js

function getJwtCookie(token) {
  $.ajax({
    type: 'POST',
    url: 'http://localhost:3001/secured/authorize-cookie',
    data: {
      token: token
    },
    headers: {
      'Authorization' : 'Bearer ' + token
    },
    success: function() {
      console.log('Cookie received!');
    },
    error: function() {
      console.log('Problem with cookie');
    }
  });
}

```
Next, lets set up the `authorize-cookie` endpoint to handle this call.

```js
// server.js

app.post('/secured/authorize-cookie', authenticate, function(req, res) {
  res.cookie('id_token', req.body.token, {
    expires: new Date(Date.now() + 36000),
    httpOnly: true
  });
  res.send(200, { message: 'Cookie set!' });
});
```

In the next step, we'll set up our **express-jwt** middleware, but we're making use of it already in the `authorize-cookie` route by passing it in as the second argument, `authenticate`. The middleware secures the endpoint and a valid JWT will be needed to access it. If the JWT is valid, we simply reflect it back as a cookie and set the `httpOnly` flag to `true` so that the cookie can only be accessed by the server. This route accomplishes the steps of validating the JWT that was received from Auth0, as well as the step of setting a cookie with the JWT.

**Note:** We are using an `Authorization` header to accomplish our cookie JWT in this example. This is the only place we would need to make a request using this header--the rest of the application will handle JWTs with cookies.

### Step 4: Set Up Middleware to Check for the Cookie
Normally, the **express-jwt** middleware will look for the presence of a header and retrieve the JWT from there. However, we can also create a custom function to define how the token should be retrieved.

```js
// server.js

...

var authenticate = jwt({
  secret: new Buffer(process.env.AUTH0_CLIENT_SECRET, 'base64'),
  audience: process.env.AUTH0_CLIENT_ID,
  // Custom function to retrieve the JWT
  // We first look for the JWT in a header and if it isn't there,
  // we look for it in a cookie
  getToken: function fromHeaderOrCookie(req) {
    if(req.headers.authorization && req.headers.authorization.split(' ')[0] === 'Bearer') {
      return req.headers.authorization.split(' ')[1];
    } else if(req.cookies && req.cookies.id_token) {
      return req.cookies.id_token;
    }
    return null;
  }
});

...
```

We've added the `getToken` function as an option on the object that is passed into `jwt`. Our implementation here says that we want to first look for the presence of a JWT as an `Authorization` header, and if there isn't anything there, we want to check whether there is a cookie with the name `id_token`.

### Step 5: Test the Secured Route

With the `id_token` cookie in place, we can see that requests to the `secured/ping` endpoint go through just fine.

![modern authentication jwt](https://images.ctfassets.net/23aumh6u8s0i/4j5ZnQitsiwgVbLtwupT71/104a61fb2584f11a192c1fb36e476f92/legacy-app-auth-3)

<include src="asides/Jwt" />

## Wrapping Up

As we've seen, modern web applications are crafted and deployed in ways that make conventional user authentication challenging. JWT authentication is an excellent way to get around these challenges and allows us to keep our application server stateless. If we need to lean on old practices, such as using cookies, we can do so and still support JWT authentication with a little tweaking on the server.


5 Steps to Add Modern Authentication to Legacy Apps Using JWTs

Learn the essentials of Falcor--the newly open-sourced library from Netflix that lets you represent your data as a single virtual JSON object.

Getting Started With Falcor

0cd73f2f2f39709bd03646e9225cc3d3?s=200 avatar

0cd73f2f2f39709bd03646e9225cc3d3?s=200

I’m an engineer with a passion for building frictionless products. I’ve built effective teams and have grown them into successful engineering organizations. I like to forge a culture.

CTO and Co-founder

Matias Woloski

Json Web Tokens (JWT) gets a logo, new website and more

In 2013 when we started building Auth0 we had to decide which standard we wanted our platform to be built on. Back then there was [WS-Fed](https://en.wikipedia.org/wiki/WS-Federation) and [SAML2](http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf). I was very familiar with both, having worked on many projects with Microsoft technologies. My main issue with these standards was that they were too complex: too many knobs and levers, interop issues and above all, a lack of libraries.



On the other extreme we had OAuth2 which was rapidly being adopted because of its simplicity. It was also being used by Facebook, Google and many others. There were already libraries written in many languages, making it even more appealing.

However, [OAuth2](https://tools.ietf.org/html/rfc6749) was/is an __authorization__ protocol, not one specific for __authentication__ [[1](http://www.thread-safe.com/2012/01/problem-with-oauth-for-authentication.html)] [[2](http://homakov.blogspot.com.ar/2012/08/oauth2-one-accesstoken-to-rule-them-all.html)].

[OpenID Connect](http://openid.net/specs/openid-connect-core-1_0.html) was being drafted as a very thin layer on top of OAuth2 to overcome exactly that issue. With the introduction of [JSON Web Tokens](https://tools.ietf.org/html/rfc7519) there was now a simple way of verifying user identity and audience (the consumer of these tokens).

Back then it was on [draft-06](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-06), and I decided to join the Working Group.

## Why is JWT so popular?

![](https://images.ctfassets.net/23aumh6u8s0i/6eRP0BpQt8Hf1qY6WHNRGk/34336bf2f0d2af90d7d920b9c0ed84c7/jwt-google-trend)

I think there are many reasons why JWT is being widely adopted:

* It embraces JSON which is already heavily adopted across many stacks.
* It is simple to use and simple to implement (hence more libraries and fewer interop issues).
* It supports symmetric and asymmetric crypto which solves the majority of use cases.

## Numbers speak for themselves

About 2 years since the first draft this simple, yet useful standard expanded:

![](https://images.ctfassets.net/23aumh6u8s0i/1PUSHZTPdUqD2jvVlkN47L/9f2f1b3696ac54aae970f444e9751a0d/banner-jwt)

* [972 GitHub repos](https://github.com/search?q=jwt) related to JWT.
* [2600+ StackOverflow](http://stackoverflow.com/search?q=jwt) threads.
* 400K page views on [jwt.io](http://jwt.io).
* [50K Google](https://www.google.com.ar/search?q="json+web+token") results.

If you use Android, AWS, Microsoft Azure, Salesforce, or Google then chances are that you are already using JWT.

<include src="TweetQuote" quoteText="If you use AWS, Microsoft Azure, Salesforce, or Google then chances are that you are already using JWT."/>

We very much believe in this standard so we wanted to keep making contributions to foster its adoption. We are happy to share the **new logo**, the **new website**, **badges**, and other things. :)


## New Logo

The central component of the branding is a logo symbol representing an individual JSON Web Token. The circular icon was designed to suggest a coin while avoiding being mistaken for a digital currency symbol.

Here are some initial sketches and colors:

![](https://images.ctfassets.net/23aumh6u8s0i/4XQlyCKEVRjmXqvPOwSj5q/3af5e76fc7292dfd4e7b437d282a9eaf/jwt_02)
![](https://images.ctfassets.net/23aumh6u8s0i/2idVA183X17v3CfGC0uOmB/35b22395ff6ee0bbd090f81a57cd08c1/jwt_04)

We decided to use the starburst shape representing the crypto protection of a JSON Web Token. Multicolored spokes radiate from the centralized hub representing the various claims within a payload.
Here is the final symbol:

![](https://images.ctfassets.net/23aumh6u8s0i/6sw33rq7EM8nCi5Gov3RCD/6b1d1cf37d688b3e81d2445da694e938/jwt_01)

JSON Web Token has been abbreviated to the initials JWT and custom lettering was developed.

![](https://images.ctfassets.net/23aumh6u8s0i/6w5TnOcVKczBfjTvk5zpWU/96dd7ee784a2171e263bc71a15f9b343/jwt_03)
![](https://images.ctfassets.net/23aumh6u8s0i/16VIM0ExdiVtMpEVamzZzG/a0b6699a966257d51fa001ab55ddf5b4/jwt_05)

## New Site

We redesigned [jwt.io](http://jwt.io), incorporating the new branding. The debugger is still the central piece. We added support for RS256 in addition to HS256.

<img src="https://images.ctfassets.net/23aumh6u8s0i/5ng8giWbaI8NDj6ze9gLje/912d6a18286b995b182592eafda32760/jwt-1" class="expand"/>

In the libraries section, we improved the readability by color coding each library and using the proper logos for each. In addition to that, we added the number of stars from the GitHub repository.

<img src="https://images.ctfassets.net/23aumh6u8s0i/58Jbwy39S0YKyg9rDsICdv/d619bf661636457130fa4a31c948d68b/jwt-2" class="expand"/>

## Badges and Others

If your API supports JSON Web Tokens, feel free to add this badge

![](https://images.ctfassets.net/23aumh6u8s0i/jZkOsCfAXX0zSbq0Ae82v/77da371796a706d6b96b7cda06c6cde5/jwt-compatible)

If there is some functionality on your site that uses and exposes JSON Web Tokens, you can use the following button to open the JWT on jwt.io.

[![](https://images.ctfassets.net/23aumh6u8s0i/38tcsWr8NpjrGjCwMWQLZ7/b786abbaf88c090d025319eb3a91a087/jwt-view)](http://jwt.io/#id_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ)

The token is sent through the hash like this: `http://jwt.io/#id_token=eyJhbGciOi....`

Finally, we designed some cool JWT t-shirts that you can order from [swag.auth0.com](http://swag.auth0.com).


## Acknowledgements

Special thanks to [Ty Wilkins](http://tywilkins.com/) for crafting the logo and lettering, [Ricky Rauch](http://twitter.com/rickyrauch) and [team](http://dribbble.com/auth0) for the awesome looking website, [Alberto Pose](http://twitter.com/thepose) who created the initial jwt.io version and curates the community contributions, [Guillermo Rauch](http://twitter.com/rauchg) for his constant advice, [Mike Jones](http://self-issued.info) for introducing me into the working group and all of you who [contributed to jwt.io](https://github.com/jsonwebtoken/jsonwebtoken.github.io/graphs/contributors) through GitHub.

**JWT all the things!**

<include src="asides/Jwt" />

JWT: 2 years later

Damian Schenkelman

Damian was one of Auth0's earliest employees. He loves building products for developers and taking things from 0 to 1.
<br><br>
He played key roles in implementing product features and growing the engineering organization in the early stages, and later on defining Auth0's architecture for scale and creating new products. Today he helps shape Auth0's long term strategy and leads Auth0Lab, a small and amazing team doing research and development of forward-looking products.
<br><br>
He spends his spare time with family, and friends, exercising, and catching up on all things NBA.

VP R&D (Auth0Lab)

Learn how to add JWT API keys to a DenyList so they are no longer valid.

**tl;dr**: If you understand why and how to support blacklisting JWTs, then skip to the [code](#impl).

In a [previous post](https://auth0.com/blog/2014/12/02/using-json-web-tokens-as-api-keys/), we proposed an approach to using [JSON Web Tokens](https://auth0.com/learn/json-web-tokens/) as API Keys, going over some of the benefits of doing so and also providing some examples based on our [API v2 scenarios](https://auth0.com/docs/apiv2). This post follows up by explaining an aspect that was not covered before: how to add JWT API keys to a DenyList so they are no longer valid.

If you need an in-depth introduction to **JSON Web Tokens**, check out the **free** ebook below.

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

## A Real World Example
Let's for a second assume that GitHub used JSON Web Tokens as API Keys and one of them was accidentally published on the web. You would want to make sure an app can no longer access your information by revoking that token:

<a href="https://images.ctfassets.net/23aumh6u8s0i/3FcfGQTrWrTXz2L7aOrTQJ/4b7e1f65761e5d45e6613534b5cd953b/blacklist_token.png" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/3FcfGQTrWrTXz2L7aOrTQJ/4b7e1f65761e5d45e6613534b5cd953b/blacklist_token.png"/></a>

## Framing the Problem
Providing support for blacklisting JWTs poses the following questions:

1. How are JWTs individually identified?
2. Who should be able to revoke JWTs?
3. How are tokens revoked?
4. How do we avoid adding overhead?

This blog post aims to answer the previous questions by leveraging our experience from implementing this feature in our [API v2](https://docs.auth0.com/apiv2).



### 1. How are JWTs individually identified?

To revoke a JWT we need to be able to tell one token apart from another one. The JWT spec proposes the [`jti`](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#jtiDef) (JWT ID) as a means to identify a token. From the specification:
> The jti (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well.

As a quick reminder, this is how the claims section of one of our JWT API tokens looks like:
<a href="https://images.ctfassets.net/23aumh6u8s0i/42R0pKeDgBxWfnogCtEQnZ/75b06ae9b03c6121e8a0b9b39c21251f/jwt_blacklist_01.png" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/42R0pKeDgBxWfnogCtEQnZ/75b06ae9b03c6121e8a0b9b39c21251f/jwt_blacklist_01.png"/></a>

The tokens accepted by our API use the `aud` claim to determine the tenant for which the JWT is valid. If we use the `(aud, jti)` pair as the token's identifier then each tenant is in charge of guaranteeing that there's no duplication among their tokens.

Similarly, if a token does not include the `jti` claim we do not allow it to be revoked.

### 2. Who should be able to revoke JWTs?

If anyone could revoke our API keys then unfortunately they wouldn't be of much use. We need a way of restricting who can revoke a JWT.

<include src="TweetQuote" quoteText="If anyone could revoke our API keys then unfortunately they wouldn't be of much use."/>

The way we solved it in our API is by defining a specific scope (permission) that allows blacklisting tokens. If you generate a JWT like the one shown in the next figure you will be able to revoke JWTs:
<a href="https://images.ctfassets.net/23aumh6u8s0i/2tovQjfBsagwVFQAchw6JV/790bee0566e203e69fd071955369a456/jwt_blacklist_02.png" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/2tovQjfBsagwVFQAchw6JV/790bee0566e203e69fd071955369a456/jwt_blacklist_02.png"/></a>

> Notice the `blacklist` action nested inside the `scopes` object.

### 3. How are tokens revoked?

To blacklist/revoke a token, you need a JWT API key (referred to as `JWT_API_KEY`) like the one described in #2. With it you can issue a `POST` request to `/api/v2/blacklists/tokens` as shown below (new lines added for clarity):

```
curl -H "Authorization: Bearer {JWT_API_KEY}"
-X POST
-H "Content-Type: application/json"
-d '{"aud":"u6nnAxGVjbBd8etXjj554YKGAG5HuVrp","jti":"test-token"}'
https://login.auth0.com/api/v2/blacklists/tokens
```

The complete documentation for the endpoint is [here](https://auth0.com/docs/apiv2#!/blacklists/post_tokens) but basically you need to:

* Send the `aud` and `jti` claims of the JWT to revoke.
* Send the JWT with the permissions necessary to blacklist tokens in the **Authorization** header.

To get the revoked tokens you can issue a `GET` to `/api/v2/blacklists/tokens`. You can use the [docs](https://auth0.com/docs/apiv2#!/blacklists/get_tokens) to figure out the how.

### 4. How do we avoid adding overhead?
You might be thinking:

> Wasn't the whole point of using JWTs avoiding a DB query?

Well, that is a benefit, though hardly the _whole point_. There is a caveat though: that question only applies if you have an application with a single issuer, not a multi-tenant system.

If there is more than one tenant, you don't want all of them to share the same secret. You still have to perform a database query to map the `aud` claim to the required `secret`.

With that in mind, these are some of the optimizations that you can implement:

* **Optimization 1**: The aforementioned operation involves I/O so it can be performed in parallel with our query to verify if a token has been revoked.

  > Of course, you can also add a caching layer with a reasonable expiration time to avoid the DB trips altogether.

* **Optimization 2**: Skip the expiration check if the `jti` claim is not part of the JWT.

* **Optimization 3**: To reduce the size of the revoked tokens store you could automatically remove JWTs from it once their [`exp`](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#expDef) is reached (assuming there is one).

<a name="impl"></a>
## Implementation
We have shipped version 1.3.0 of the open source [express-jwt](https://github.com/auth0/express-jwt) with support for [multi-tenancy](https://github.com/auth0/express-jwt#multi-tenancy) and [blacklisted tokens](https://github.com/auth0/express-jwt#revoked-tokens). We also put together a [sample](https://github.com/auth0/multitenant-jwt-auth) that shows everything working together. The sample is based on our [API v2](https://docs.auth0.com/apiv2) implementation.

The following code snippets use show the core sample parts:

### Securing the endpoint
The first thing we have is an API that we would like to protect. The `express-jwt` middleware is configured by providing:

* `secret` - A function in charge of retrieving the secret.
* `isRevoked` - A function in charge of checking if a JWT is revoked.

```javascript
var expressJwt = require('express-jwt');
// to protect /api routes with JWTs
app.use('/api', expressJwt({
  secret: secretCallback,
  isRevoked: isRevokedCallback
}));
```

### Handling multi-tenancy
The implementation for the `secretCallback` function reads the backing data store to retrieve the secret for a tenant.  It caches the secrets using the tenant identifier as the cache key.

If the data layer provides an encrypted tenant secret, it needs to be decrypted before calling `done`.

```javascript
var LRU = require('lru-cache');

var secretsCache = LRU({ /* options */ });

var secretCallback = function(req, payload, done){
  var audience = payload.aud;
  var cachedSecret = secretsCache.get(audience);

  if (cachedSecret) { return done(null, cachedSecret); }

  data.getTenantByIdentifier(audience, function(err, tenant){
    if (err) { return done(err); }
    if (!tenant) { return done(new Error('missing_secret')); }

    var secret = utilities.decrypt(tenant.secret);
    secretsCache.set(audience, secret);
    done(null, secret);
  });
};
```

### Supporting revoked JWTs
Similarly, the `isRevokedCallback` implementation caches whether a token is revoked or not using the `(aud, jti)` pair as the cache key. It also skips the check in case the `jti` claim is not present.

```javascript
var jtiCache = LRU({ /* options */ });

var isRevokedCallback = function(req, payload, done){
  var tokenId = payload.jti;
  if (!tokenId){
    // if it does not have jti it cannot be revoked
    return done(null, false);
  }

  var tokenIdentifier = payload.aud + ':' + payload.jti;
  var blacklisted = jtiCache.get(tokenIdentifier);
  if (typeof blacklisted !== 'undefined') { return done(null, blacklisted); }

  data.getRevokedTokenByIdentifier(tokenIdentifier, function(err, token){
    if (err) { return done(err); }
    blacklisted = !!token;
    jtiCache.set(tokenIdentifier,blacklisted)
    return done(null, blacklisted);
  });
};
```

## Conclusion
Most of the aforementioned content applies to blacklisting JWTs in general, not just JWT API keys.

Hopefully this blog post has provided some useful ideas on how to tackle this problem.

If you have any comments or questions don't hesitate to post them!

You an also get involved in [express-jwt](https://github.com/auth0/express-jwt)!
<iframe src="https://ghbtns.com/github-btn.html?user=auth0&amp;repo=express-jwt&amp;type=star&amp;count=true" frameborder="0" scrolling="0" width="170px" height="20px"></iframe>

<include src="asides/Jwt" />

Adding JSON Web Token API Keys to a DenyList

Most APIs today use an API Key to authenticate legitimate clients. API Keys are very simple to use from the consumer perspective:  You get an API key from the

Most APIs today use an **API Key** to authenticate legitimate clients. **API Keys** are very simple to use from the consumer perspective:

1. You get an **API key** from the service (in essence a shared secret).
2. Add the key to an `Authorization` header.
3. Call the API.

It can't get simpler than that, but this approach has some limitations.

The last couple of months, we've been working on our [API v2](https://docs.auth0.com/apiv2). We wanted to share what we've learnt implementing a more powerful security model using [JSON Web Tokens](http://jwt.io).



Using a JSON Web Token offers many advantages:

* **Granular Security**: API Keys provide an all-or-nothing access. JSON Web Tokens can provide much finer grained control.
* **Homogenous Auth Architecture**: Today we use cookies, API keys, home grown SSO solutions, OAuth etc. Standardizing on JSON Web Tokens gives you an homogenous token format across the board.
* **Decentralized Issuance**: API keys depend on a central storage and a service to issue them. JSON Web Tokens can be "self-issued" or be completely externalized, opening interesting scenarios as we will see below.
* **OAuth2 Compliance**: OAuth2 uses an opaque token that relies on a central storage. You can return a stateless JWT instead, with the allowed scopes and expiration.
* **Debuggability**: API keys are opaque random strings. JSON Web Tokens can be inspected.
* **Expiration Control**: API keys usually don't expire unless you revoke them. JSON Web Tokens can (and often do) have an expiration.
* **Devices**: You can't put an API key that has full access on a device, because what is on a phone or tablet can easily be stolen. But you can put a JWT with the right set of permissions.

If you'd like an in-depth introduction to **JSON Web Tokens**, check out our **free** ebook below.

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

## Granular Security

One of the most interesting benefits of using JWTs is the first one listed above. Back in the old days, when databases were at the center of our client-server applications, we could create users with specific permissions on the database:

<a href="https://images.ctfassets.net/23aumh6u8s0i/2paJRM6vdAq4RO2k6ypich/b960d3ab0c364b327b2d4a2f1afc66c4/permissions-sql" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/s9tyvnrUrUjg7i39zWBOn/db84bd0b3a904e879c3484841d34cd1a/permissions-sql.png"/></a>

_Remember this?_

APIs are becoming central pieces of our distributed systems architecture. They are now the "gatekeepers" of our data. But in contrast with what was available in databases, virtually all API keys provide all-or-nothing access. Readers will likely be familiar with the `scope` parameter of OAuth2 based systems that offers this finer grained consent to access.

There are many situations in which you want to keep the simplicity of an **API Key** but only for a subset of all possible API operations.

[GitHub acknowledged this requirement](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) and now provides a way of creating a token with the scopes you need (mimicking the OAuth2 consent):

![](https://images.ctfassets.net/23aumh6u8s0i/6fdGKpvxjgD7seKbyvjb9O/4d82a5cb332aa836d93cb7e3044b5707/token_scopes)

In the next section, we will go through the details of how this can be implemented.

### How to implement it?

We don't know how GitHub implemented it (they probably used Ruby), but we will use it as an example. Let's say we want to implement an endpoint in the API to **create new repos**. You could model this with the following **JSON Web Token** payload. If you provide any of those scopes, then you can create repos:

```
{
  iat: 1416929109, // when the token was issued (seconds since epoch)
  jti: "aa7f8d0a95c", // a unique id for this token (for revocation purposes)
  scopes: ["repo", "public_repo"]  // what capabilities this token has
}
```
_Look at this token in <a href="http://jwt.io?value=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0MTY5MjkxMDksImp0aSI6ImFhN2Y4ZDBhOTVjIiwic2NvcGVzIjpbInJlcG8iLCJwdWJsaWNfcmVwbyJdfQ.XCEwpBGvOLma4TCoh36FU7XhUbcskygS81HE1uHLf0E" target="_blank">jwt.io</a>_

The API endpoint would simply check for the presence of the right **scope** atribute (this example is written in node.js but any language would work):

```
// intercept all calls to API and validae the token
app.use('/api', express_jwt({secret: SECRET, userProperty: 'token_payload'}));

// for POST /user/repo validate that there is a scope `repo` or `public_repo`
app.post('/api/user/repo',
        check_scopes(['repo', 'public_repo']),
        function(req, res, next) {
    // create a repo
    ....
});

```

Notice the `check_scopes` middleware on the `/api/user/repo` route. This is how the `check_scopes` function is implemented:

```
function check_scopes(scopes) {
  return function(req, res, next) {
    //
    // check if any of the scopes defined in the token,
    // is one of the scopes declared on check_scopes
    //
    var token = req.token_payload;
    for (var i =0; i<token.scopes.length; i++){
      for (var j=0; j<scopes.length; j++){
          if(scopes[j] === token.scopes[i]) return next();
      }
    }

    return res.send(401, 'insufficient scopes')
  }
}

```

> Notice that no one can change the scopes variables. JWTs are digitally signed, so its content cannot be tampered with.  

Documenting an API is equally important. What would be a good way for surfacing this on an API explorer?

For Auth0, we decided to build our own documentation using [swagger](http://swagger.io/). Since we are a multi-tenant system, each tenant has an API Key and Secret that is used to sign the token. As a developer, you mark which scopes you need and a token will be auto-generated. You can copy and paste it to [jwt.io](http://jwt.io) to see the structure (this is the __debuggable__ piece, by the way).

<a href="https://images.ctfassets.net/23aumh6u8s0i/33kBdPt5Hlzt2UEt0yoRQp/e7227bdb1d82dc16fed9a145dc64896b/api-explorer3" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/7uKm8Sq6OiHUEs5v9AoKT7/3550cf71dfa93c43bbd0eb2b2b2c2191/api-explorer3.gif"/></a>

Scopes required by each operation are clearly identified:

<a href="https://images.ctfassets.net/23aumh6u8s0i/4FDPqZmzwJWGdg9YGSUcEf/5f6ecef62c9d7f3ae0f64edad904a3a1/api-scopes2" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/4FDPqZmzwJWGdg9YGSUcEf/5f6ecef62c9d7f3ae0f64edad904a3a1/api-scopes2"/></a>

Our token format is a bit different from the one in the example we showed for GitHub. The good thing about JWTs is that they can contain _any_ data structure:

```
{
  iat: 1416929061,
  jti: "802057ff9b5b4eb7fbb8856b6eb2cc5b",
  scopes: {
    users: {
      actions: ['read', 'create']
    },
    users_app_metadata: {
      actions: ['read', 'create']
    }
  }
}
```

The string representation of the scope is `read:users` but in the JSON Web Token, we are using a more structured representation (note the hierarchy), this allows us to be more consistent. It also allows us to have an easy way to extend it for other scenarios.

## Conclusion & Resources

We have shown a new way of securing APIs based on JSON Web Tokens. This approach has some interesting benefits, in particular around _granular security_. In future posts we will go over other aspects, starting with how to revoke tokens.

Below are some of the resources that we used in our node.js backend implementation:

* The [hapi.js](http://hapijs.com) framework to create the API.
* A [fork](https://github.com/auth0/hapi-auth-jwt) of [hapi-auth-jwt](https://github.com/ryanfitz/hapi-auth-jwt) with [support for multitenant apps](https://github.com/ryanfitz/hapi-auth-jwt/pull/10) to handle authentication with JWTs.
* The awesome [ratify](https://github.com/mac-/ratify) library to both validate API input using [JSON schemas](http://json-schema.org) and automatically generate [swagger](http://swagger.io/) from said schemas for our docs.
* Swagger's support for arbitrary [authorizations objects](https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#514-authorizations-object) and a slightly [customized swagger-ui template](https://github.com/swagger-api/swagger-ui#customize) to render the scopes per operation.

If you want to see an example of this working, you can check out our API v2: <https://docs.auth0.com/apiv2>

We would love to hear your thoughts about this approach!

[Discuss here](https://ask.auth0.com/t/using-json-web-tokens-as-api-keys/357)

<include src="asides/Jwt" />

"js"