JSON Web Token

What is JSON Web Token?

JSON Web Token, referred as JWT henceforth, is an open standard method for secure information exchange between two parties. This information may be anything and in this article we are going to explore it for Authorization use case. Actual implementation details of the JWT and working example of an authorization flow is coming soon.

When to use it?

• Authorization: For secure authorization of a client application, from an identity provider, where the authorization server trusts the client application.
• Information exchange: Securely transmit information between two parties.

How it look like?

It consists of three parts separated by dots (.)

• Header
• Payload
• Signature

It looks like this,

xxx.yyyyy.zzzzz

Header

It consists of two attributes, type and algorithm. The attribute names may be different in different implementations, but these values are most widely used. It looks like this,

{
    typ: \"JWT\",
    alg: \"RS256\"
}

This JSON is base64 url encoded to form the first part of the token. Will explain the algorithm and encoding with example in my next post.

Payload

This will contain the actual information being exchanged. For authorization, this will contain the information about who the client application is. This again depends on the implementation, but for our example it looks like this,

{
    iss: \"details about the issuer\",
    sub: \"subject of the request\",
    aud: \"audience (url of the identity provider)\",
    exp: expiry date & time of the request,
    iat: date & time of the request
}

In an authorization from Salesforce as authorization server these are sample values,

iss: issuer is always the client id generated by creating a connected app

sub: username of an active user in the identity provider org, who have access to the connected app and api

aud: login url of Salesforce org.

exp: this depends on implementation, for Salesforce org, this has to be with 5 minutes of the request

iat: request date and time. If this is outside of few minutes from server time, the request will get rejected. Will update actual number soon.

This JSON is base64 url encoded to form the second part of the token.

Note: base64 url encode, makes it url safe, and the third part (signature) makes it protected against tampering, however this may be read by anyone if intercepted. Please be sure to communicate through encrypted channel, if there is confidential information. For authorization with Salesforce, this is ensured through TLS 1.1 and above.

Signature

This is the last part of the token and this ensures the token from tampering by any interceptor. The based 64 encoded first two parts are concatenated using a dot (.) separator and encoded using the algorithm defined in header (RS256 for this example) and the private key of the client. It looks like this,

RS256 ( 
     base64URLEncode (header) + \'.\'
     base64URLEncode (payload)
)

How it really looks

Here is a sample JWT with base 64 encoded header, base 64 encoded payload and RS256 encoded signature.

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiIzTVZHOUNFbl9PM2p2djB3Q08yYkJBcVp3czZJa1lBR3IuYThKX2xHNzVZeEpkdXAuVms3NGhtNF9XSlZNTXFuUTJhREIxbDRTdkFCVGppbi5QRDcyIiwic3ViIjoic2FyZmFyYWpleUBwbGF5ZnVsLW1vb3NlLTM5MTUwNC5jb20iLCJhdWQiOiJodHRwczovL2xvZ2luLnNhbGVzZm9yY2UuY29tIiwiZXhwIjoxNTMzODI2Mzk3LCJpYXQiOjE1MzM4MjYyMTd9.NGSPTJqW5qMZVnuhGHLkOTAlefn0N12fxhm9PZnlh-kBW-ZTRyo40RxMFnUMzCi4aqcYjV986rboGPv7k0u1-ZzeoCubK0MfqPcu7Qi5OsYQwKmVvXTXxe8_VhzcLqNKB1VGkhl7EjCDK2TIqWI2CxOAqWbKtAtNpBjP2w_-viA0T88Q9VhR2D7lsDb_dEXuVpFBbJMGackDB2lNHh5UzJF-t-V2Gv-3lF6ywhAxlT6xmKwqltQdF9i2j5a_mGQIkPTOhnDF67P-OsPjUZrOFt0PDEeTQDNwcJACHsAjsO9IeqG6MMmdTqEDmv-9Ei5j56wp6tHMCpwyPR3xIoRSCQ

Please note that, this is not encrypted and hence you may decode it. Here is a nice debugger, that gives nice readable output,

Please note that the signature cannot be tampered by an interceptor, if they don\’t have access to the private key of the requestor. This signature may be decoded by the authorization server (or any recipient) using the public key of the requestor, and the payload may be verified for sanity.

Will discuss this topic in detail with working code sample in my next post soon. Thanks for reading.