JSON Web Token (JWT)

JWT is a JSON based open standard (RFC 7519) that allows information to be provided between parties using a trusted signing model.

The information in the JWT can be verified and trusted because it is digitally signed using a secret key or a public&private key pair.

When the sender creates the JWT, the sender will have:

  1. written the information using a defined structure/ encoding method;
  2. signed the JWT.

When the receiver gets the JWT, the receiver should:

  1. verify the JWT by verifying the signature;
  2. decode the information in the JWT.

JWT structure

The JWT generally has three parts separated with dots, e.g.:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJKb2huIERvZSIsImlhdCI6bnVsbCwiZXhwIjoxNTEzMTcxMzcwLCJhdWQiOiIiLCJzdWIiOiIifQ.Bxp8_MNg_kzFYat4n8OGOXpdP2zPM9PWBTREp1W4Imo

The three parts of the JWT are:

  1. Header;
  2. Payload;
  3. Signature.

The header and the payload of the JWT are Base64URL1 encoded (note: not encrypted!). That means that any kind of information in these parts could be easily decoded using a specific application. The purpose of encoding the information is to allow arbitrary values (e.g. the whole of the Unicode character set) to be transmitted within the JWT element.

If the JWT specified in the example is pasted in to a Base64URL/JWT decoder, the original information encoded can be retrieved as illustrated in the figure below:

 

 

Figure 1 – Example of encoded and decoded JWT

Header is a JSON object that usually consists of two keys:

  • "typ" or type, is hardcoded and set as “JWT” that represents JSON Web Token;
  • "alg" or algorithm, is the hashing algorithm the sender uses to sign (note: again, not encrypt!) the JWT.

Payload is a JSON object that consists of attributes (or claims) that have been provided by the Identity Gateway about the user, in other words, all the associated data that need to be sent across from the Mobile Network Operator to the application or web service.

There are three classes of JWT claims:

  • Registered/ Reserved claims. These are a set of predefined claims which are not mandatory but recommended, to provide a set of useful claims (Some of them are: “iss” (issuer), “sub” (subject) exp, “aud” (audience), “exp” (expiration time) etc.);
  • Public claims. These can be defined at will by those using JWTs. However, 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 is the encoded header and the encoded payload, signed with a key.

There are two ways to sign a JWT:

  • symmetric, with the help of a shared secret key;
  • asymmetric, with the help of a public&private key pair.

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

Since the signature already includes the hash of the header and the payload, if the information in any one of three parts is tampered or edited the signature along with the tampered message will never match, and the JWT becomes invalid and should not be trusted.

References

A number of platform-specific SDKs are available to integrate Mobile Connect into your applications and web services. All the SDKs are open source and royalty free, and all of them support decoding and verification of the JWT. The functionality itself is hidden inside the appropriate SDK – the application/web service obtains the decoded JWT ready to use. Please refer to SDKs page for further information.

Also, there are many open source libraries publicly available that provides the capability to decode and verify the JWT. For example, http://jwt.io provides a basic functionality to decode JWT as well as links to different libraries for different programming languages that you can download and use.


1Base64URL format and Base64 format are not the same. Base64 has some characters which are not URL safe, such as "+", "/" and "=". In order to convert a message from Base64 into Base64URL it’s necessary to replace them in the following way:

  • replace “+” by “-“;
  • replace “/” by “_”;
  • remove extra padding “=”.

Therefore, to revert the process it’s necessary to.

  • replace "-" by "+";
  • replace "_" by "/";
  • add extra padding "=" to the string based on modulo 4.

Example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9" (since there is not any "-" or "_" sign, there is nothing to replace). The length of this header value is 36, and this needs to be rounded up to a multiple of 4. 36 modulo 4 = 0, so this means that there is no extra padding to be added. This string can now be passed into a Base64 decoder to be decoded. Most of the Base64 decoding will auto pad this, but for some cases such as VB.net, you will have to manually insert the padding to work.