JWT Tokens


In this blog post, I’m going to introduce the JWT (pronounced “jot”) token concept.  I’m going to use the code presented in this article (click here) to demonstrate how a token is created and then I’ll discuss the parts of the token and how it is used.

Sample Token

Using the article code, I created a dumb and dirty console app to generate a token with this final code:

var token = new JwtTokenBuilder()
  .AddSubject("james bond")
  .AddClaim("MembershipId", "111")

For a real system, you’ll need to store your secret key and you’ll need to make it much larger.  The other variables will differ according to your use of the token.  Before I go into any details on how you would generate and consume the token, I’m going to discuss what the token looks like and how it works.  First, I generated a token from the above code and obtained this result:


If you go to the wiki page on the JWT Token (JSON Web Token), you’ll see a description of the three parts of the token.  If you look closely you can see that there are two dots “.” and they separate the three parts of the token.  Each part is a base 64 encoded string so it is safe to transmit over the web.  The first part is the header.  If you cut the first part you’ll get this:


Paste that code into a decoder (click here for an on-line base 64 string decoder), you’ll get this result:

If you dig into the JWT token build method, you’ll see a section where HS256 hashing is used for the signature and this token is a JWT type token.

Take the next block of text (which is long) and copy it (without the dots).  Then put it in the decoder and click on “Decode”.  You should see this:

This is the payload section and you can see all the information that was placed into C# the code earlier.

If you’ve ever used tokens for accessing APIs, you’re probably thinking to yourself: What prevents someone from getting a copy of this token and just changing the information to something else and stealing admin rights or unauthorized data from the API?  That’s where the signature comes in.  The signature is the last part of the token.  The signature represents everything that is in the header and payload, encoded with a secret key and formed into a hash.  The receiver of this token must know the secret key in order to verify the signature.  If anything in the header or payload is altered, the recalculation of the hash will result in a different signature value.

Keep in mind, that the JWT token should not be used to store anything you want to keep secret.  So don’t put your password into the token payload and then expect it to be safe.  Technically, it will be safe from packet sniffers because you should be accessing an API using SSL, but don’t assume that the payload section is encrypted.

If you were to generate another token after the expire time (in my example the expire was set to 1 minute), then the signature will be different.  That’s because the token is time sensitive.  This improves the security, in case the token is intercepted by a third party.  It also prevents a user from reusing the token forever, instead of re-authenticating.  Finally, it prevents a valid token from being altered to obtain data not specified by the original token.

Re-authenticating?  Oh yes.  There needs to be some sort of authentication scheme that allows the user to obtain a token by logging in someplace.  This is up to the system designer to decide how it is accomplished.  There may be a login id and password that the user uses to get a temporary key and access an API by hand (usually using an interface like Swashbuckle/Swagger).  For machine-to-machine communications other protocols can be used.  A token can also be issued for a longer time period for client use.

The token use can be narrowed using the issuer and audience.  If your company has many APIs that are used for different purposes, you might issue a token that is restricted for use on one API.  You can setup your API to reject any token that is not issued by your security API and you can reject tokens where the audience in the token is not serviced by the API.

Let’s say that you want to communicate from one API to another, how would you use the JWT token?

To use the token, you need to put it in the authorization header of the API call:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

When you generate your token, you should set the expire time to something like one to four hours.  Once you obtain a token from your source (either you generate the token or you get it from a security API), then you save the token in a cache.  Many articles talk about using a cookie, but an API will typically not use cookies.  If you have only one API instance, you can get away with using a singleton class to save your token.  If you plan to load-balance two or more instances of your API (plan ahead, assume you’ll need to scale up in the future), then you’ll want to store the token in a cache system (such as Redis or Memcached).

When you grab the token from your cache, check the expire and replace the token if it only has a couple of minutes left.  There could be network delays when sending your token to the remote API, even if it’s in the same data center.  If you wait until the last second to renew the token, you’ll run into issues where the consuming API will reject your token.  This problem will increase when your network is experiencing an unexpected latency.

For your consuming API, you must check the signature first.  There is no need to accept a JWT token that has a bad signature.  That just indicates that someone changed the payload data manually.  Once that has been verified, then check the expire date/time and make sure the token is still valid.  Next, you’ll want to check any other restrictions placed on the token (audience and issuer).

What Else is in the Token?

You can store data inside the token.  There is no limit, but you should keep the token as small as possible.  Don’t pass around a 10 megabyte token and expect a fast network.  You should pass some authorization information of the person or machine that authenticated (i.e. user id, claims).  By doing this, you can form a state-less website.  Your front-end might keep the token in a cookie after the user logs in.  That token is then used in the bearer authorization header for every call to your website back-end.  This eliminates the need for a website session (i.e. session-less or state-less).  For this use case, you can have the authenticated user’s id or some sort of temporary key contained in the payload (i.e. generate a new temporary key when the user logs in and store it in the user table, then throw it away when the user logs out).

The data that you store in the payload should be something that is used repeatedly by the APIs or website you are accessing.  Otherwise, if you try to store something like the current page number in the JWT token, then a new token will have to be issued every time you click the “next” button to get a page of data.  If you’re looking for a place to store temporary state variables, I would recommend putting them in a cache and keying the cache to the user id.  Once the token has been authenticated, the user id can be used to grab the data from your cache and you can continue as though you had a session.

Why Use a Token?

When I create a new API, I have a check-list of what goes into the shell of the API:

  1. JWT Token authentication management for all calls
  2. Logger
  3. Help screen (swashbuckle/swagger)
  4. IOC container

No Web API should be without these items.  My use of the help screen allows me to document my API and gives me a method of testing the API directly.  The logger will be necessary to troubleshoot problems and track exceptions once the API is deployed to an environment in the data center.  The IOC container is the framework that allows developers to use unit tests with ease.  Last, but not least, never deploy an API without some sort of security.  Unless you want the entire world to be able to access it.  Install and test your JWT token security first, then you can add controllers and business logic without worrying about a hacker accessing your data before your API goes live (I’m assuming that you might deploy an API for a feature that is turned off).

You might be thinking that your data is open to the public anyway.  Why secure your API?  You might want to limit access to your data via your website or mobile device interface.  If your API is open to the world, some entity, could tap into your API without your knowledge and put a load on your system that you don’t expect.  Don’t assume anything.  A random Facebook developer could create an application that accesses your API and then a half-million Facebook users unwittingly hit your API when they use that app.  Yikes!

If you want the world to have access to your API, then you better be prepared to scale.


Website Security


In this post I’m going to talk about website security.  This is just a top-of-the-waves blog post.  Consider it a jumping off point for you to dive deeper into specific security subjects.  As a software developer, everyone should understand what precautions should be taken to ensure that your company’s website will not appear on the evening news.

Website Security

I’m not a security expert.  I’m also not an expert in the field of encryption.  My experience stems from the fact that I’ve been through a few “incidents” in my career involving a user or employee who has broken into the software that I maintain.  When your company gets hacked, it humbles you.  All your assumptions about how good you are at securing your software go right out the window.  The basic problem with security is that you must be conscious of all the tiny details.  The potential hacker only needs to find a very small opening.

Here’s is a video (on YouTube) that every developer should watch.  It’s very entertaining, but also informative.  This video shows a group of white hat hackers who were hired to hack into the U.S. power grid.  Their job is to perform the act and then report back to the company on what they need to do to secure their systems:

Watch Hackers Break into the US Power Grid

Notice how these guys obtained a tiny bit of information using a technique called social engineering.  This is normally the starting point. Their next step is to install some trojan horses (in their case they installed physical devices on the network of the main office as well as software on some of the laptops).

Most hackers are current or former employees.  These are people who already have inside knowledge to get them started.  The infamous hacker Edward Snowden was a contractor that worked for the NSA.  He was an IT person with enough privileges to get information out of the system, in bulk.  He also used social engineering to convince fellow co-workers to give him access to their data.

Other hacked sites involved really dumb programming mistakes.  Citi was hacked by a user who realized that the account number was a parameter in the website url.  They changed the number and refreshed their browser, allowing them access to over 200,000 accounts (How Hackers Stole 200,000+ Citi Accounts Just By Changing Numbers In The URL).

SQL injection is a very common mistake.  Here’s a rather long list of sites that contained injection vulnerabilities: The Code Curmudgeon SQLI Hall-of-Shame.

Hard-coded passwords… sigh.  So many devices, so many hacked systems: Hard-coded password exposes up to 46,000 video surveillance DVRs to hacking.  Here’s an article about the Internet of Things:These 60 dumb passwords can hijack over 500,000 IoT devices into the Mirai botnet.  If you read down the article you’ll stumble onto this quote: “To make matters even worse, the default credentials cannot be changed as they are hardcoded in the firmware and there are no options for disabling them. The telnet service is also difficult to disable.”  Never hard-code a password.  Always allow a method to change the user id’s and passwords.  There should also be a setup that forces the purchaser to change the admin password right away.

Custom encryption or hashing.  Don’t do it.  Use an existing algorithm and make sure you understand which hash algorithms are appropriate for saving passwords into your database.  Use a salt to prevent someone from using a lookup website to reverse a hash.  A salt is not optional.  There are many unsalted MD5 hash lookup websites.  Every developer should read this information on hashing passwords: Salted Password Hashing – Doing it Right.

Don’t Assume Anything

Building a secure piece of software requires the developer to be a bit paranoid.  I roll my eyes when a developer begins to spit out an excuse for taking the easy route.  Usually the excuse is along the lines of “nobody knows what the name of that database is..” or “how likely is it that someone will…”.  Hackers are very smart.  Don’t let cheesy Hollywood movies fool you into thinking that hackers are just clever 8-year old kids with some scripts they downloaded from the internet.  Hackers can be former developers with a copy of your database.  They may have run a bruite-force algorithm on your password hashes and have admin passwords to enter your system.  This is the reason for a password policy that forces users to change their passwords on a regular basis.  Here’s a really good system for finding all 8-character passwords: 25-GPU cluster cracks every standard Windows password in <6 hours.

Protect your backup files.  A backup file can be copied to a thumb drive and then restored to another machine.  A potential hacker can run a brute force attack on such a restored system until the cows come home.  Once a user-id and password has been found, then the hacker has what they need to enter the real system.

Keep tight firewall controls.  It’s sometimes easy to just open up a bunch of ports to make something work.  This is OK for testing purposes, but your production system should be as closed to the outside as possible.  Here’s an example of a vulnerability for Active Directory from the internet: Researchers show how to steal Windows Active Directory credentials from the Internet.

Finally, here’s a list of common programmer mistakes that can let a hacker into your system: Coding Horror – Top 25 Most Dangerous Programming Mistakes.

Security through Obscurity

There are two basic meanings for this saying.  In one instance, instead of securing something, just obscure the name of it (like an admin account with no password, or a linked server with elevated privileges).  Don’t fall for this trap.  This just means that only external hackers with no knowledge knows about this.  It doesn’t mean that they can’t figure it out or that a disgruntled employee won’t use it.  Using an obscure user name as the admin user name (instead of “admin”), and using a strong password is OK.  Obscuring the admin user name makes it more difficult for a brute force attacker to attack a site.  It isn’t going to slow down a laid-off software developer with a copy of your database.


Just for fun, here’s a list of the Worlds Biggest Data Breaches.  This list is arranged by year with relative sized circles based on the size of the breach.