 |
| JWT: Encoded or decoded security claims |
Some JWT history and standards
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:
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 include the so-called access token and refresh token. It is not a requirement, but typically they are JWTs. As stated, the OAuth focus is on authorization and it was sometimes misused for 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.
BTW: If you have an IBM Cloud account, then look at the output of ibmcloud iam oauth-tokens on the command line.
Encoding and decoding JWTs
With that history and some standards as foundation, how does an actual JWT look like? Here is one:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiAiZGF0YV9oZW5yaWsiLCAibmFtZSI6ICJoZW5yaWsiLCAiaWF0IjogMTYxMDM3OTI0OCwgImV4cCI6IDE2MTAzODI4NDh9.-hDQcUK1WI8jxQ_VXKHVCm8a9C-M_8f4F1-rFpT6bP0
The JWT above consists of three parts, separated each by a dot ('.'):
- Header: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
- Payload: eyJpc3MiOiAiZGF0YV9oZW5yaWsiLCAibmFtZSI6ICJoZW5yaWsiLCAiaWF0IjogMTYxMDM3OTI0OCwgImV4cCI6IDE2MTAzODI4NDh9
- Signature: -hDQcUK1WI8jxQ_VXKHVCm8a9C-M_8f4F1-rFpT6bP0
Both the header and payload are base64url encoded and can be decoded like this (not taking padding into account):
henrik@home> base64 -d <<< eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
{"typ":"JWT","alg":"HS256"}
henrik@home> base64 -d <<< eyJpc3MiOiAiZGF0YV9oZW5yaWsiLCAibmFtZSI6ICJoZW5yaWsiLCAiaWF0IjogMTYxMDM3OTI0OCwgImV4cCI6IDE2MTAzODI4NDh9
{"iss": "data_henrik", "name": "henrik", "iat": 1610379248, "exp": 1610382848}
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. Predefined JOSE header and payload fields are managed by IANA. The signature is computed by applying the stated algorithm to the concatenation of header, '.' and payload and base64url encodes 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.
Summary
JWTs are an easy self-contained means of exchanging claims between two parties. The idea is over 10 years old, JWTs have been around for years. If you want to fiddle with JWTs yourself, I recommend an online tool like https://jwt.io/ to get started. The above screenshot shows that site with one of my recent JWTs.
If you have feedback, suggestions, or questions about this post, please reach out to me on Twitter (@data_henrik) or LinkedIn.