The first draft for JSON Web Tokens (link resides outside ibm.com) (JWTs) is already 10 years old (it is from December 2010). The early draft states: “JSON Web Token (JWT) defines a token format that can encode claims transferred between two parties. The claims in a JWT are encoded as a JSON object that is digitally signed.“

In its latest version, IETF RFC 7519 (link resides outside ibm.com), it was expanded to the following: “JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.“

The new description hints at two representations of a JWT (often pronounced “jot”) — namely a JSON Web Signature (link resides outside ibm.com) (JWS) or a JSON Web Encryption (link resides outside ibm.com) (JWE) structure. JWS is defined in RFC 7515 (link resides outside ibm.com), JWE in RFC 7516 (link resides outside ibm.com). There are even some more related JSON-based security standards (link resides outside ibm.com), all defined by a workgroup called JOSE: JSON Object Signing and Encryption (link resides outside ibm.com). You can read more about even earlier work and how it came to the naming in “JWT 5 years in the making. (A history)” (link resides outside ibm.com) by John Bradley (link resides outside ibm.com).

OAuth 2.0 (link resides outside ibm.com) is an industry standard for authorization. Without going into detail, it offers an authorization flow and core concepts, including the so-called access token and refresh token (link resides outside ibm.com). It is not a requirement to use them, but JWTs are typically used used these days. As stated, the OAuth focus is on authorization, and it was sometimes misused for handling identification, too. OpenID Connect (link resides outside ibm.com) adds this missing piece in the puzzle and introduces the identity or ID token (link resides outside ibm.com). The ID token is represented as JWT.

With that history and some standards as a foundation, how can we process the JWT from above and what information does it hold?

The JWT above consists of three parts, separated each by a dot (‘.’):

1. Header:: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
2. Payload: eyJzdWIiOiIxMjM0NTY3ODkwQUJDIiwibmFtZSI6IkhlbnJpayBMb2VzZXIiLCJpYXQiOjE2MTExNDA0MDAsImV4cCI6MTYxMTIzNDU2N30
3. Signature: _iVbBcypdse-9sjrxp9iOrGsXKBWrBB3mrHgBtukcfM

Both the header and payload are base64url (link resides outside ibm.com) encoded and, not taking possible padding into account, can be decoded like this:

henrik@home> base64 -d <<< eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
{"alg":"HS256","typ":"JWT"}

henrik@home> base64 -d <<< eyJzdWIiOiIxMjM0NTY3ODkwQUJDIiwibmFtZSI6IkhlbnJpayBMb2VzZXIiLCJpYXQiOjE2MTExNDA0MDAsImV4cCI6MTYxMTIzNDU2N30
{"sub":"1234567890ABC","name":"Henrik Loeser","iat":1611140400,"exp":1611234567}base64: invalid input

The header contains information about the utilized alg(orithm) — here, HS256 (HMAC SHA256). (link resides outside ibm.com) The payload depends on the kind of (access/refresh/ID/…) token and is made up of claims (link resides outside ibm.com). Those and other predefined JOSE header and payload fields (link resides outside ibm.com) are managed by IANA (link resides outside ibm.com). In the example above, the fields and claims are subj(ect), name, issued at (iat) and exp(iration time).

The signature is computed by applying the stated algorithm to the concatenation of header, ‘.’ and payload and then base64url encoding the result. Thereafter, the three parts separated by a dot make up the JWT. Details of how signature are derived are defined in RFC 7515 (link resides outside ibm.com).

You can access the above JWT in this online debugger at JTW.io (link resides outside ibm.com). First, it will show a message “Invalid Signature.” You can resolve it by replacing the shown default secret with !!!my-really-big-256-bit-secret!!!.

Because IBM Cloud provides many services in its catalog and it is an Internet app with many components of its own, it makes heavy use of tokens, including JWTs. You probably have used the IBM Cloud Command Line Interface (CLI) and the command ibmcloud iam oauth-tokens:

It prints out the OAuth bearer tokens (access tokens) for the current CLI session, implemented as JWTs. These IAM tokens are used to access IAM-enabled cloud services. 

If you want to integrate external users into your cloud account, then JWTs are in use, too. Identity tokens and their included claims are exchanged for authentication to identity the user. Many solutions utilize the security service IBM Cloud App ID. It helps to authenticate users and protect resources. It leverages the mentioned OAuth 2.0 and OpenID Connect standards and therefore deals with access, ID and refresh tokens.

One of my (and your) favorite services is watsonx Assistant to build chatbot. If you want to secure web chats (i.e., to further protect exchanged messages and to certify message origin), JWTs come to the rescue.

Of course, there are many more examples of how JWTs are utilized to easily exchange (security) claims and thereby hardening the security of a cloud solution.

JWTs are an easy, self-contained means of exchanging claims between two parties. They are an ubiquitous data structure, in the cloud and on-premises. Hopefully, the above was a useful introduction to get you interested (if you were not already!).

If you want to examine and tinker with JWTs yourself, I recommend an online tool like https://jwt.io/ (link resides outside ibm.com) to get started. If you are deeper into it, use a network monitor or the developer tools in your browser (link resides outside ibm.com) to watch out for JWTs. Have fun and check out our IBM Cloud tutorials, including many security-related tutorials.

If you have feedback, suggestions, or questions about this post, please reach out to me on Twitter (@data_henrik)  (link resides outside ibm.com) or LinkedIn.