JSON Web token (JWT) is a little tricky to pin down, the interpretation below is from the ietf description: https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-27#section-3. I found myself quickly thinking, how do I go about actually implementing this?

What does a JWT look like?

JWT is a string containing 3 base64 encoded elements separated by the "." character.
i.e.
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEyMzQ1Njc4OTAsIm5hbWUiOiJKb2huIERvZSIsImFkbWluIjp0cnVlfQ.eoaDVGTClRdfxUZXiPs3f8FmJDkDE_VCQFXqKxpLsts

How is it actually sent?

It was actually difficult to find any reference as to how the token is recommended to be sent!

It's sent either as a parameter in the URL i.e.
www.example.com?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEyMzQ1Njc4OTAsIm5hbWUiOiJKb2huIERvZSIsImFkbWluIjp0cnVlfQ.eoaDVGTClRdfxUZXiPs3f8FmJDkDE_VCQFXqKxpLsts

or in the authorization header:
i.e.
Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEyMzQ1Njc4OTAsIm5hbWUiOiJKb2huIERvZSIsImFkbWluIjp0cnVlfQ.eoaDVGTClRdfxUZXiPs3f8FmJDkDE_VCQFXqKxpLsts

It can be included in the JSON POST body of the message itself if required.

What's in the token?

Slightly easier to find information on! See http://jwt.io

The first segment identifies the encryption algorithm used i.e.
{ "alg": "HS256", "typ": "JWT" }

The second segment includes the claim info:
{ "sub": 1234567890, "name": "John Doe", "admin": true }

The ietf sets a series of standards as to what appears in this segment. This includes an expiration date (which is useful for expiring links etc).

The third segment is the signature. This the an encrypted representation of the first and second segments using a shared "secret". This is verified before reading the token and accepting the message.

HMACSHA256(BASE64(Segment1) + "." + BASE64(Segment2), sharedSecret)

Creation

Can be created by a separate authorization app you create within your stack or you can generate this within your application.

Upsides:

  • Adds another layer of security onto basic auth using encryption paired with a "shared secret".
  • Allows us to add an authorization server later if we decide apps should request tokens rather than generate them.
  • Can expire tokens. might be useful for links.

Downsides:

  • The shared secret gets compromised, you're screwed.
  • Spec is in flux.
  • Libraries are quite young (read sketchy).