Understand how to claim your identity.

I am not sure when I saw a JSON Web Token (JWT) for the first time, but since then, I have seen many of them. To the untrained eye, they look like some garbled computer output:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwQUJDIiwibmFtZSI6IkhlbnJpayBMb2VzZXIiLCJpYXQiOjE2MTExNDA0MDAsImV4cCI6MTYxMTIzNDU2N30._iVbBcypdse-9sjrxp9iOrGsXKBWrBB3mrHgBtukcfM

The reality is that the above (and JWTs in general) hold essential information (see screenshot below) that has a direct impact on security both in the cloud and on-premises. It is information to identity and authenticate users. JWTs are crucial to making microservices-based solutions work and an important building block to realize 12-factor apps.

In this blog post, I am going to share some history behind JWTs, introduce their basic concepts and look into common JWT usage scenarios on IBM Cloud.

Some JWT history

The first draft for JSON Web Tokens (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, 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 (JWS) or a JSON Web Encryption (JWE) structure. JWS is defined in RFC 7515, JWE in RFC 7516. There are even some more related JSON-based security standards, all defined by a workgroup called JOSE: JSON Object Signing and Encryption. You can read more about even earlier work and how it came to the naming in “JWT 5 years in the making. (A history)” by John Bradley.

OAuth 2.0 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. 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 adds this missing piece in the puzzle and introduces the identity or ID token. The ID token is represented as JWT.

JWT encoding and decoding

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 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). The payload depends on the kind of (access/refresh/ID/…) token and is made up of claims. Those and other predefined JOSE header and payload fields are managed by IANA. 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.

You can access the above JWT in this online debugger at JTW.io. 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!!!.

IBM Cloud and JWTs

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.

Summary

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/ to get started. If you are deeper into it, use a network monitor or the developer tools in your browser 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) or LinkedIn.