It seems the JSON Web Token (JWT) specs are finally ready to become RFCs. I’ve wrote about security tokens before in the past: it was 2008, XML, SAML and WS-Security were still hot subjects and JWT didn’t existed yet. The more recent “Designing Evolvable Web APIs with ASP.NET” book already includes a discussion of JWT in its security chapter. However, I think this announcement deserves a few more words and a colorful diagram.
A security token is a data structure that holds security related information, during the communication between two parties. For instance, on a distributed authentication scenario a security token may be used to transport the identity claims, asserted by the identity provider, to the consuming relying party.
As a transport container, the security token structure must provide important security properties:
- Integrity – the consuming party should be able to detect any modifications to the token while in transit between the two parties. This property is usually mandatory, because the token information would be of little use without it
- Confidentiality – only the authorized receiver should be able to access the contained information. This property isn’t required in all scenarios.
Kerberos tickets, SAML assertions and JSON Web Tokens are all examples of security tokens. Given the available prior art, namely SAML assertions, one may ask what’s the motivation for yet another security token format. JWT tokens where specifically designed to be more compact than the alternatives and also to be URL-safe by default. These two properties are very important for the modern usage scenarios (e.g. OpenID Connect protocol), where tokens are transported in URIs query strings and HTTP headers. Also, JWT tokens use the JavasScript Object Notation (JSON) standard, which seems to be the data interchange format du jour for the Web.
The following diagram presents an example of an encoded token, the contained information and how it relates to the token issuer, the token recipient and and the token subject.
A JWT is composed by multiple base64url encoded parts, separated by the ‘.’ character. The first part is the header and is composed by a single JSON object. In the example, the object’s properties, also called claims, are:
"typ":"JWT"– the token type.
"alg":"HS256"– the token protection algorithm, which in this case is only symmetric signature (i.e. message authentication code) using HMAC-SHA-256.
The second part is the payload and is composed by the claim set asserted by the issuer. In the example they are:
"iss":"https://issuer.webapibook.net"(issuer) – the issuer identifier.
"aud":"https://example.net"(audience) – the intended recipient.
"sub":"firstname.lastname@example.org"(subject) – the claims subject (e.g. the authenticated user).
"email":"email@example.com"(email) – the subject’s email.
"name":"Alice"(name) – the subject’s name.
The first five claims (
sub) have their syntax and semantics defined by the JWT spec. The remaining two (
name) are defined by other specs such as OpenID Connect, which rely on the JWT spec.
Finally, the last part is the token signature produced using the HMAC-SHA-256 algorithm. In this example, the token protection only includes integrity verification. However, it is possible to also have confidentiality by using encryption techniques.