Json Web Tokens ¶

Structure¶

JWTs consist of three parts separated by dots (.), which are:

Header
Payload
Signature

Therefore, a JWT typically looks like the following.

JWT structure

encoded_Header.encoded_Payload.encoded_Signature

Structure is shown in the below example from jwt.io

The header typically consists of two parts: the type of the token, which is JWT, and the hashing algorithm such as HMAC SHA256 or RSA.

JWT Header example

{
  'alg': 'HS256',
  'typ': 'JWT'
}

Payload¶

The second part of the token is the payload, which contains the claims. Claims are statements about an entity (typically, the user) and additional metadata.

JWT Payload example (claims + metadata)

{
  'sub': '1234567890',
  'name': 'Amarjit Singh',
  'admin': true
}

There are three types of claims:

Reserved claim
Public claim
Private claim

Reserved claims¶

These are a set of predefined claims, which are not mandatory but recommended, thought to provide a set of useful, interoperable claims. Some of them are: iss (issuer), exp (expiration time), sub (subject), aud (audience)

Notice that the claim names are only three characters long as JWT is meant to be compact.

Public claims¶

These can be defined at will by those using JWTs. But to avoid collisions they should be defined in the IANA JSON Web Token Registry or be defined as a URI that contains a collision resistant namespace.

Private claims¶

These are the custom claims created to share information between parties that agree on using them.

Signature¶

To create the signature part you have to take the encoded header (base64), the encoded payload (base64), a secret, the algorithm specified in the header, and sign that.

For example if you want to use the HMAC SHA256 algorithm, the signature will be created in the following way.

JWT Signature example

HMACSHA256(
  base64UrlEncode(header) + '.' +
  base64UrlEncode(payload),
  secret)

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message was’t changed in the way.

JWT vs SAML¶

Size: As JSON is less verbose than XML, when it is encoded its size is also smaller; making JWT more compact than SAML. This makes JWT a good choice to be passed in HTML and HTTP environments.

Security: While JWT and SAML tokens can also use a public/private key pair in the form of a X.509 certificate to sign them. However, signing XML with XML Digital Signature without introducing obscure security holes is very difficult compared to the simplicity of signing JSON.

Parsing: JSON parsers are common in most programming languages, because they map directly to objects, conversely XML doesn’t have a natural document-to-object mapping. This makes it easier to work with JWT than SAML assertions.

Bearer Schema/Format¶

The Authorization: <type> <credentials> pattern was introduced by the W3C in HTTP 1.0, and has been reused in many places since. Many web servers support multiple methods of authorization. In those cases sending just the token isn't sufficient.

Sites that use the Authorization : Bearer xxxxxx format are most likely implementing OAuth 2.0 bearer tokens.

Sending GET Request with Bearer Token Authorization Header

To send a GET request with a Bearer Token authorization header, you need to make an HTTP GET request and provide your Bearer Token with the Authorization: Bearer {token} HTTP header. Bearer Authentication (also called token authentication) is an HTTP authentication scheme created as part of OAuth 2.0 but is now used on its own. For security reasons, bearer tokens are only sent over HTTPS (SSL).

GET /echo/get/json HTTP/1.1
Host: amarjitdhillon.com
Accept: application/json
Authorization: Bearer {token}