Overview

The id_token is one of the tokens received in the response to a Token API request. It contains important security information about the Mobile Connect authentication. In order to be able to read this information, the token needs to decoded. The id_token comes in the form of a JSON Web Token.

JSON Web Token

JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties.

The JWT comes in 3 parts seperated by "."

eg.

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJub25jZSI6Im5vbmNlXzAucHBzdHR1aGFwNWV6aDBrOSIsInN1YiI6IjMyMzljNmQxNmYzYjAxM2FmYTZkMTFkZjc1OTIyYWY0IiwiYW1yIjoiU01TX1VSTCIsImF1dGhfdGltZSI6MTQ0NjY0MDgyOSwiYWNyIjoiMiIsImF6cCI6IjBjOWRmMjE5IiwiaWF0IjoxNDQ2NjQwODI5LCJleHAiOjE0NDY2NDQ0MjksImF1ZCI6WyIwYzlkZjIxOSJdLCJpc3MiOiJodHRwOi8vb3BlcmF0b3JfYS5zYW5kYm94Lm1vYmlsZWNvbm5lY3QuaW8vb2lkYy9hY2Nlc3N0b2tlbiJ9.VuJFR71XqEGZmC1bnrn9iWUReYm0iJAji1oWailXqjk

The first part (highlighted in yellow) is the header. It usually contains information on how the id_token is signed.

The second part (highlighted in blue), is the token payload. This contains all the claims that are being passed over by the operator. For a more detailed description of what claims are being passed and what they are, please refer to the Mobile Connect API section.

The third part (highlighted in green) is the signature hash. Using information obtained from the header, you will know which hashing algorithm to use. If the hash result of the first and the second parts matches the third part, you will know that this id_token has not been tampered with and can be trusted.

If they don´t match, there is a chance that the id_token is corrupted or has been tampered at some point and should not be trusted.

Decoding

The JSON Web Token is encoded using Base64URL format. This is not the same as Base64. Base64 has some characters which are not URL safe such as "+", "/" and "=".

To make it URL safe, the "=" which is the padding is removed. The î+î sign is replaced with "-" and the î/ì sign is replaced with "_". So, to revert the process, the id_token part needs to.

  1. 1. Replace any "-" sign to "+"
  2. 2. Replace any "_" sign to "/"
  3. 3. Add extra "=" padding to the string based on modulo 4

Example, "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9" (since there isn't any "-" or "_" sign, there is nothing to replace). The length of this header value is 36. "36 % 4" modulo 4 = 0, so this means that there is no extra padding to be added. This string can now be passed into a base64decoder to be decoded. Note: 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.

Validating

There are multiple hash algorithim used to validate the id_token, such as HS256, HS512, RS256, RS512. They are specified in the "header" part of the id_token.

example.

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

With that in mind, you will hash the value of

"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJub25jZSI6Im5vbmNlXzAucHBzdHR1aGFwNWV6aDBrOSIsInN1YiI6IjMyMzljNmQxNmYzYjAxM2FmYTZkMTFkZjc1OTIyYWY0IiwiYW1yIjoiU01TX1VSTCIsImF1dGhfdGltZSI6MTQ0NjY0MDgyOSwiYWNyIjoiMiIsImF6cCI6IjBjOWRmMjE5IiwiaWF0IjoxNDQ2NjQwODI5LCJleHAiOjE0NDY2NDQ0MjksImF1ZCI6WyIwYzlkZjIxOSJdLCJpc3MiOiJodHRwOi8vb3BlcmF0b3JfYS5zYW5kYm94Lm1vYmlsZWNvbm5lY3QuaW8vb2lkYy9hY2Nlc3N0b2tlbiJ9"

with the secret or public key to get a hash (in the above case, using a secret with HS256 algorithm). . Compare the result with the passed signature "VuJFR71XqEGZmC1bnrn9iWUReYm0iJAji1oWailXqjk". If they match, the id_token is validated.

References

There are many open source libraries publicly available that provides the capability to decode and verify the id_token. http://jwt.io provides a basic funcitonality to decode id_token as well as links to different library for different programming languages that you can download and use.