How to use https://jwt.ms/ to decode JSON Web Tokens

tl;dr The site https://jwt.ms allows you to decode tokens and the tokens never leave your browser.

Once I got a handle on what access tokens are used for, the next step became how do I know what is inside an access token? For example, is the app telling me that the user is unauthorized because they are not signed in? Or is it because a scope is missing or contains a typo in the access token?

What’s a JSON Web Token?

From the Azure AD B2C documentation

Many of the tokens that Azure AD B2C issues are implemented as JSON web tokens (JWTs). A JWT is a compact, URL-safe means of transferring information between two parties. JWTs contain information known as claims. These are assertions of information about the bearer and the subject of the token. The claims in JWTs are JSON objects that are encoded and serialized for transmission. Because the JWTs issued by Azure AD B2C are signed but not encrypted, you can easily inspect the contents of a JWT to debug it. Several tools are available that can do this, including jwt.ms. For more information about JWTs, refer to JWT specifications.

> A JWT is a compact, URL-safe means of transferring information between two parties. 

First, a JSON Web Token is a token (i.e. a string of numbers and letters) that when decoded will present data in JSON format.

> JWTs contain information known as claims.

The content that we’re interested in right now is called “claims”. This is terminology that will make sense once you see a JWT decoded.

> The claims in JWTs are JSON objects that are encoded and serialized for transmission. 

Yep, what I said earlier.

> Because the JWTs issued by Azure AD B2C are signed but not encrypted

You’ll see in a bit where the JWT is signed.

What does a JSON Web Token look like in jwt.ms?

Fortunately the documentation contains a couple of different sample JWTs: an id token and an access token. Both are JWTs, but have different “claims” and different purposes.

The differences between an id token and an access token start to make a lot more sense once you see them decoded and compare them.

Let’s start with an id token. Cut and pasting the sample id token from the docs into jwt.ms shows the following:

Color coded JWT token text

Note the text at the bottom of the image “This is an Azure AD B2C token.” The jwt.ms site also figures out if you’ve supplied an Azure AD v1 token or Azure AD v2 token. In the future, this will be important to verify in case your token isn’t being accepted somewhere.

Also the token is color-coded. These colors are represented in the lower half of the screen.

token broken down into color coded JSON sections

The items in blue are the claims. If you click on the Claims tab, you’ll see the descriptions of these claims.

claims descriptions shown

The last item in the list is idp​ meaning the token “claims” to have come from the identity provider facebook.com.

It is common for an id tokens to contain something like a “name” claim which is used to show your Display name after you log in, e.g. “Hi Sara!” The app is getting the Display name from the id token claims.

How does an access token differ from the id token in jwt.ms?

The best way to see the differences is to use the access token generated from my previous blog post.

For example, if I view the access token from my previous blog post, I can see the scopes I specified for access to the API. These scopes are claims for the token.

scp claim showing HelloRead and Hl

This is important because the next time I get an unauthorized access error trying to call an API, I can check whether the access token contains the right scopes.

Remember those “application claims” you checked on your Sign In Or Sign Up policy, e.g. Display Name and Postal Code?

Postal Code checked for Application claims

well, here you go! they are shown as claims.

Display name claim Smo Jo and postalCode claim 98052

There are other claims that are important to know as well. From  https://aka.ms/b2caccesstokens

  1. aud – Audience – The application ID of the single resource that the token grants access to.
  2. azp – Authorized Party – The application ID of the client application that initiated the request.

BTW: SmoJo was my high school nickname, like FloJo, but not as fast =)

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s