While working on one of the security-related aspects of the platform i’m building, i came across JWT specification which i find very interesting and thought will share with you the notes i made while reading:

1. JWT acronym stands for “JSON Web Tokens”.
2. Definition of a security token:

• encrypted data structure (in this case of JSON format) which contains:
  • information about the issuer and subject (claims)
  • proof of authenticity (digital signature)
  • expiration (validity) time

3. Suggested pronunciation of JWT is the same as the English word “jot”.
4. Basic facts:

• JWT is an emerging Web API’s security token standard
• developed by IETF (JSON Web Token (JWT) spec.)
• used by security protocols:
  • OAuth 2.0 (JWT Profile for OAuth 2.0 spec.)
  • OpenID Connect (mandated)

5. Why JSON-based standard?

• XML-based SAML data format, exchanged over SOAP protocol offered a ton of encryption and signature options but was percieved as a “heavy” technology and of not much use by mobile appliance (initially not that strong in terms of computing power). JSON messages on the other hand don’t require a fairly advanced technology stack (like SAX, StAX, etc.) to produce and parse data structures and can be exchanged over HTTP (also, each browser nowadays is supporting JavaScript).

6. Characteristics:

• Plaintext JWTs: support use cases where the JWT content is secured by means other than a signature and/or encryption contained within the JWT. A plaintext JWT has the header “alg” parameter value set to “none”.
• Encrypted JWTs: use JSON Web Signature (JWS) and JSON Web Encryption (JWE) to sign and/or encrypt the contents of the JWT using JSON Web Algorithms (JWA)
• symmetric (HMACSHA256-384) and asymmetric (ECDSA, RSA) signatures
• symmetric and asymmetric encryption (RSA, AES/CGM)

7. Structure:

• JWT Header
  • metadata
  • algorithms & keys used
• JWT Claims
  • Reserved Claim Names:
    • “iss” (Issuer)
    • “sub” (Subject)
    • “aud” (Audience)
    • “exp” (Expiration)
    • “nbf” (Not Before)
    • “iat” (Issued At)
    • “jti” (JWT ID)
    • “typ” (Type)
  • Public Claim Names
  • Private Claim Names

8. Example:

// header object
{
    "alg":"none"
}

// claims object
{
    "exp":1373625160,
    "sub":"Mariusz",
    "nbf":1373624561,
    "aud":[
        "https:\/\/my-web-app.com",
        "https:\/\/your-web-app.com"
    ],
    "iss":"https:\/\/my-auth-server.com",
    "jti":"c79772ea-8777-44dc-a0fe-9001aeee9d02",
    "iat":1373624561,

    // additional public claims
    "scope":["read", "search"],
    "client":"system A"

In the example above, the JWT Header implies that the encoded object is a Plaintext JWT. Additional public claims, may be useful for example in oAuth protocol (to know which system (A in this case) requested the token and what operations (read, search) will it be authorized to perform using this token).

9. Sample encoding:

• Base64url encoded representation of the JWT Header:
  • eyJhbGciOiJub25lIn0
• Base64url encoded representation of the JWT Claims Set:
  • eyJleHAiOjEzNzM2NDI3NzYsInN1YiI6Ik1hcml1c3oiLCJuYmYiOjEzNzM2NDIxNzYsI
    mF1ZCI6WyJodHRwczpcL1wvbXktd2ViLWFwcC5jb20iLCJodHRwczpcL1wveW9
    1ci13ZWItYXBwLmNvbSJdLCJpc3MiOiJodHRwczpcL1wvbXktYXV0aC1zZXJ2ZXIu
    Y29tIiwianRpIjoiMWI2YjMxMTItMzkyZi00MzIxLTk2YjktNzkyYjhhMjcxOTliIiwiaWF
    0IjoxMzczNjQyMTc2fSwiY2xpZW50Ijoic3lzdGVtIEEiLCJzY29wZSI6WyJyZWFkIi
    wgInNlYXJjaCJd

Complete JWT is a result of concatenating encoded representations of the header and the claims set with a period (‘.’) character between the parts:

• eyJhbGciOiJub25lIn0.eyJleHAiOjEzNzM2NDI3NzYsInN1YiI6Ik1hcml1c3oiLCJuYm
  YiOjEzNzM2NDIxNzYsImF1ZCI6WyJodHRwczpcL1wvbXktd2ViLWFwcC5jb20iLCJ
  odHRwczpcL1wveW91ci13ZWItYXBwLmNvbSJdLCJpc3MiOiJodHRwczpcL1wvb
  XktYXV0aC1zZXJ2ZXIuY29tIiwianRpIjoiMWI2YjMxMTItMzkyZi00MzIxLTk2YjktNzk
  yYjhhMjcxOTliIiwiaWF0IjoxMzczNjQyMTc2fSwiY2xpZW50Ijoic3lzdGVtIEEiLCJzY
  29wZSI6WyJyZWFkIiwgInNlYXJjaCJd

Finally, the above string representation of a JWT security token is what gets transmitted over the wire as a message header or url query parameter.

Sources:

• JSON Web Token (JWT) (http://tools.ietf.org/id/draft-ietf-oauth-json-web-token-08.html)
• JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants (http://tools.ietf.org/id/draft-ietf-oauth-jwt-bearer-05.html)
• JSON Web Signature (JWS) (http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-12)
• JSON Web Encryption (JWE) (http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-12)
• JSON Web Algorithms (JWA) (http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-12)

Tagged: JSON, JWT, OAuth, OpenID Connect