Do you trust the data you receive over the internet? If you do, you are very naive and really shouldn’t. Especially when it comes to data relating to authentication and authorization you must tread very carefully and only trust parties that you truly now who are and expect to provide extra care for your data. You have to make sure that the data that you’re trusting has not been tampered with and verify that the data is coming from who you expect it to come from. The interwebs is a dangerous place my friend...
The need to transfer data securely over the internet has never been bigger. JSON Web Tokens (JWT, prenounced like jaw with a t at the end, jawt) fits perfectly into this landscap. It provides a secure and easy way of transferring data between two parties.
JWT is an open standard which defines how the format can be used for transmitting information between two parties, in a secure, compact and self-contained way. A JWT can always be verified by the recipient, because it is digitally signed using either the HMAC algorithm using a secret or by using RSA or ECDSA, with a public/private key set. This does not mean that the data cannot be read by others during the network transport, but the recipient can verify that the JWT was actually sent by the expected party in the other end. If the data contained is sensitive, the content can be encrypted, providing data privacy for the parties involved.
Use cases for JWT’s
The most common scenario for using JWT’s, is to handle authorization. The JWT can contain information regarding the users identity, which resources can be accessed and which operations are permitted by the user. Many implementations of OAUTH2, which is the most popular protocol for providing authorization, rely heavily on JTW’s. Another use case is simple data transfer. In scenarios where it is essential that the data in question, has not been tampered with and the sender is who they say they are, JWT provides an easy way to secure the data.
JWT format
A JWT consists of three parts, separated by dots:
[theHeader].[thePayload].[theSignature]
The header
The header consists of two parts: the type of token, which in the case of JWT is “typ”:”JWT” and the algorithm used for signing the token. The normal algorithms are HMAC SHA256 or RSA. The header could look like this: { “alt”:”HS256”, “typ”:”JWT” } When the JWT is being built, the header JSON is Base64Url encoded and is put in the as the first part of the JWT payload.
[theHeader].[thePayload].[theSignature]
The payload
The payload part of the JWT are called “claims”. A claim is some information regarding the user (or entity if it is not a user authorization scenario, but a data transfer).
Registered claims
There is a set of claims that is a part of the standard. These claims are called the registered claims. They are almost always a part of the payload, in order for the recipient to know which user the other claims in the payload are related to.
The registered claims are:
- iss - Issuer, identifying the sender of the JWT
- exp - Expiry, when does the token expire
- sub - Subject, user identifier
- aud - Audience, identifying who the token is meant for
- nbf - Not Before, when the token is valid from
- iat - Issued at, the time when the JWT was issued
- jti - JWT Id, unique identifier of the JWT
It is not mandatory that all registered claims are a part of a JWT, but it is recommended. Please note that all the claim names are only three characters long. This is to keep the total payload size as small as possible. It is recommended that you try to mimic this and keep all your claim names as short as possible, in order to keep the total size small.
Public claims
The next type of claims are public claims. Public claims are registered in the IANA JSON Web Token Registry. IANA makes sure that there are no name collisions. Before adding your own custom claim names, please check if IANA already have a name for the data you are trying to save in the JWT or that the name that you want to use is not occupied by some other data type already.
Private claims
The last claim type are private claims. A public claim is a custom claim name that is neither a registed claim or a public claim. It could be some data, that is specific to you application and is not already registered with IANA. An example of a JSON payload could be:
{
“iss”:”someIssuer”,
“exp”:”2019-10-10 22:00:00”,
“sub”:”someSubjectId”,
“aud”:”someAudience”,
“nbf”:”1900-01-01 00:00:00”,
“iat”:”2019-04-10 22:00:00”,
“jti”:”someJwtId”,
“name”:”Foo Barson”,
“xyz”:”MyPrivateClaimValue”
}
Just like the header, the payload is Base64Url encoded and added as the middle part of the JWT.
[theHeader].[thePayload].[theSignature]
The last part of the JWT is the signature. The signature is an encoding of the two preceeding parts of the JWT (the base64Url encoded header and the base64Url encoded payload separated by a dot).
For instance:
[SomeBase64UrlEncodedHeader].[SomeBase64UrlEncodedPayload]
This string will be encoded with the encoding algorithm stated in the header and added as the last part of the JWT.
[theHeader].[thePayload].[theSignature]
The resulting string is a very compact and secure representation of the data. Especially when comparing it to the “old” SAML standard, which produces much larger payloads. Since bandwith is always an issue - especially for mobile devices - the smaller the data is the better.
If you want to play around with how a JWT looks like and how it all works, https://jwt.io is a great resource with a lot of background information. The site also has a JWT debugger, where you can paste in a JWT and see the content or add content to the clear text payload and see the encoded JWT change live. They also have a long list of libraries, which can be used when working with JWT’s in different programming languages and environments.