JSON Web Tokens Will Improve Your Life

JSON Web Tokens
Will Improve Your Life
John SJ Anderson • @genehack | Ohio LinuxFest • 30 Sep 2017
JWTs WIYL! - Ohio LinuxFest 2017 – @genehack 1

Hi, I’m John.
a/k/a @genehack

VP, Technology
Inﬁnity
Interactive
iinteractive.com
@iinteractive

This is
my dog,
Sammy.a/k/a @sammyGenehack

So, what’s
a JWT?JWTs WIYL! - Ohio LinuxFest 2017 – @genehack 5

jwt.io

What Does
That Even
Mean?

Holy RFCs, Batman
— RFC 7519 - JSON Web Token (JWT)

Holy RFCs, Batman
— RFC 7515 - JSON Web Signature (JWS)
— RFC 7516 - JSON Web Encryption (JWE)
— RFC 7517 - JSON Web Key (JWK)
— RFC 7518 - JSON Web Algorithms (JWA)
— RFC 7519 - JSON Web Token (JWT)
— RFC 7520 - Examples of Protecting Content Using JSON
Object Signing and Encryption (JOSE)

Sammy found
these RFCs
a bit …dry

Think of JWTs as…
— A lightweight alternative to cookies (kinda, sorta)
— …that also works with CLI, mobile, or even desktop apps
— An authorization or access control mechanism
— …kinda like OAuth but without losing your will to live
— Cross-domain friendly

Made of stuff you already know
— Plain ol’ JSON Objects (POJOs)
— Stringiﬁed, encoded, and cryptographically signed
— Transmitted over HTTP(S)

What do they look like?
— dot-delimited string ('.')
— 3 parts
— header
— payload
— signature
— Example: xxx.yyyyy.zzz

JWT teardown: header
— Plain ole JSON object
— Base64 encoded
— Typically metadata, such as token type and signing
algorithm
{
"alg": "HS256",
"typ": "JWT"
}

JWT teardown: payload
— Another Base64-encoded POJO
— Contains “claims” – just key-value data
— Types of keys: reserved, public, private
{
"name": "Ohio LinuxFest",
"admin": false,
"iat": 1488562999
}

JWT teardown: signature
— Encoded header POJO, plus
— Encoded payload POJO, plus
— A secret, plus
— Signing algorithm from header alg key

A word about my
code samples

Making a JWT
function base64EncodeJson (pojo) {
var jsonString = JSON.stringify(pojo);
var encoded = new Buffer(jsonString).toString("base64");
return encoded;
}
function hmacIt (string, secret) {
var hmac = crypto.createHmac("sha256" , secret);
hmac.update(string);
var signature = hmac.digest("hex");
return signature;
}
var header = {
"alg": "HS256",
"typ": "JWT"
};
var payload = {
"admin": false,
"iat": 1488562999
};
var secret = "be wery, wery qwiet, we're hunting JWTs";
var encodedHeader = base64EncodeJson(header);
var encodedPayload = base64EncodeJson(payload);
var signature = hmacIt(encodedHeader + "." + encodedPayload, secret);
var jwt = encodedHeader + "." + encodedPayload + "." + signature;

Helper function one
function base64EncodeJson (pojo) {
var jsonString = JSON.stringify(pojo);
var encoded = new Buffer(jsonString)
.toString("base64");
return encoded;
}

Helper function two
function hmacIt (string, secret) {
var hmac = crypto.createHmac("sha256" , secret);
hmac.update(string);
var signature = hmac.digest("hex");
return signature;
}

The actual data
var header = {
"alg": "HS256",
"typ": "JWT"
};
var payload = {
"admin": false,
"iat": 1488562999
};
var secret = "be wery, wery qwiet, we're hunting JWTs";

Actually generating the signature
var encodedHeader = base64EncodeJson(header);
var encodedPayload = base64EncodeJson(payload);
var signature = hmacIt(
encodedHeader + "." + encodedPayload,
secret
);

Assembling the token
var jwt = encodedHeader
+ "."
+ encodedPayload
+ "."
+ signature;

Hand-rolled, artisanal JWT
> console.log(jwt.split('.').join('.n'));
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJuYW1lIjoiT2hpbyBMaW51eEZlc3QiLCJhZG1pbiI6ZmFsc2UsImlhdCI6MTQ4ODU2Mjk5OX0=.
f2bdd1f7f0cfc975c0ae6e5c356812af748d6d589d64c9c97f02018166e6ae5e
The critical bit of all of this:
The signature means you can detect any attempts to modify
the header or the payload.

Validation

Libraries for DAYS

Libraries for DAYS
— .NET, Python, Node, Java, Javascript, Ruby, Perl, Go, PHP
— Haskell, Rust, Lua, Scala, Clojure, ObjectiveC, Swift, Delphi
— Support for your favorite language/platform is probably
not an issue

OK,
you’ve
got my
attentionJWTs WIYL! - Ohio LinuxFest 2017 – @genehack 31

How
do I
actually
use
JWTs?

Basic authn/authz usage
(image stolen from jwt.io)

Things to be aware of
— Payload/header NOT encrypted
— …so don’t send anything sensitive!
— Need to control expiration, re-issue, etc.
— Some APIs send a fresh JWT to the client per-request
— Sites other than issuing site can receive JWT
— …but they must share the secret to validate

How is it actually transmitted?
— Up to you! Various methods:
— As part of the URL in a GET
— In a POST body
— In the Authorization header using Bearer scheme:
Authorization: Bearer <token>

How would
you actually
use this
in an app?

Generate a token on login
app.post('/user/login', app.wrap(user_login));
var jwt = require('jwt'); // helper wrapper around 'jsonwebtoken'
function * user_login (req, res) {
if (! (req.body.email && req.body.password)) {
res.status(400);
res.json({message: 'invalid request'});
return;
}
var user = yield _fetch_user_by_email(req.body.email);
var claims;
if (_pw_validate(user.password, req.body.password)) {
claims = { user_id: user.id };
} else {
res.status(401);
res.header('WWW-Authenticate', 'Bearer realm=myapp');
res.json({ message: 'authorization required' });
return;
}
// sign the claim set and return the token in a header
var token = jwt.sign(claims);
res.append('X-MyApp-Token', token);
res.status(200);
}

app.post('/user/login', app.wrap(user_login));
function * user_login (req, res) {
if (! (req.body.email && req.body.password)) {
res.status(400);
res.json({message: 'invalid request'});
return;
}

var user = yield _fetch_user_by_email(req.body.email);
var claims;
if (_pw_validate(user.password, req.body.password)) {
claims = { user_id: user.id };
}
else {
res.status(401);
return;
}

// sign the claim set and return the token in a header
var token = jwt.sign(claims);
res.append('X-MyApp-Token', token);
res.status(200);
}

OK, that’s
how you
make one.
How do you
validate it?

Validate with a middleware
// enable JWT-verification middleware
app.use(function (req, res, next) {
// initialize the jwt object
req.jwt = {};
// now parse the Authorization header if it exists
Promise.resolve(req.headers.authorization).then(function (auth) {
// If the Authorization header is present and employs the correct
// Bearer scheme, extract the token and attempt to verify it.
if (auth) {
var scheme = auth.split(' ')[0];
var token = auth.split(' ')[1];
if (scheme == 'Bearer') {
return jwt.verify(token).catch(function (error) {
throw new Error('failed to verify claim');
});
}
}
throw new Error('authorization not attempted');
})
.then(function (payload) {
req.jwt = payload;
next();
})
.catch(function (error) {
// Allow login without JWT
if (req.path == '/user/login' && req.method == 'POST') {
return next();
}
res.status(401);
});
});

// enable JWT-verification middleware
app.use(function (req, res, next) {
// initialize the jwt object
req.jwt = {};

// now parse the Authorization header if it exists
Promise.resolve(req.headers.authorization).then(function (auth) {
// If the Authorization header is present and employs the correct
// Bearer scheme, extract the token and attempt to verify it.
if (auth) {
var scheme = auth.split(' ')[0];
var token = auth.split(' ')[1];
if (scheme === 'Bearer') {
return jwt.verify(token).catch(function (error) {
throw new Error('failed to verify claim');
});
}
}
throw new Error('authorization not attempted');
})

.then(function (payload) {
req.jwt = payload;
next();
})

.catch(function (error) {
// Allow login without JWT
if (req.path == '/user/login' && req.method == 'POST') {
return next();
}
res.status(401);
});
});

That’s cool.
What else
you got?

Pre-signed
Content
Requests

Document store application
— Client-side Angular
— Uses JWT for authentication and sessions
— Uses Authorization: Bearer scheme

PROBLEM!
How do you
display or download
images via browser?

SOLUTION
JWTs, of course

(What talk
did you think
this was?)JWTs WIYL! - Ohio LinuxFest 2017 – @genehack 52

Solution
Generate a claim containing document ID:
{
"iat": 1497105117
"exp": 1497105177
"doc": 345345
}
NOTE: short expiration time

Solution
Sign it and put it in a URL:
/content/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0OTcxMDUxMTcsImV4cCI
6MTQ5NzEwNTE3NywiZG9jIjozNDUzNDV9.fKKCZgc2ckeONF9ELOcc9EgS-UPrCBX2bwoPmxjStdQ

Solution
Then on the server side, when you get a request like:
GET /content/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0OTcxMDUxMTcsImV4cC
I6MTQ5NzEwNTE3Ny wiZG9jIjozNDUzNDV9.fKKCZgc2ckeONF9ELOcc9EgS-UPrCBX2bwoPmxjStdQ
— Extract the token and validate
— Get the document ID from the payload
— Send back that document!

FAR
OUT
MAAAAANJWTs WIYL! - Ohio LinuxFest 2017 – @genehack 56

Recurring dilemma:
‘lightweight’
access control

Recurring dilemma: ‘lightweight’ access control
— Option 1: leave it wide open
— a/k/a the MongoDB or WTF,YOLO! pattern
— Option 2: implement full authn/authz subsystem
— …again
— Option 3: OAuth
— !!!!!!

Where’s the
middle
ground?

A screen
door
for APIs

Authorization without authentication
— Scenario:
— You have an API
— You don’t want to make anybody authenticate to use it
— You don’t want it wide open to the Internet either
— a/k/a authz without authn

Solution: JWT with RSA keys
— Another option for secret: RSA key-pair
— Include the public key in the JWT header using JWK
— JSON Web Key, natch
— Allows clients of your API to make tokens
— …which you can verify

To set it up:
— Give authorized API client an RSA key-pair
— Record the ﬁngerprint of the public key (important later!)
— You can even let the client generate the key-pair
— You just need the public key ﬁngerprint

On the client side:
— They make a JWT, using the private key to sign
— They include the public key in the header
— Include iat (issued-at) and exp (expires) claims
— Send JWT in with API request

On the API side:
— Get the public key out of the header
— Validate the signature using the public key
— Validate that public key ﬁngerprint is white-listed
— Signature produced with private key
— Public key is white-listed
— Therefore we know JWT is valid!

Things to be aware of:
— You still want to validate iat and exp and any other rules
— Your library should probably do that stuff for you,
mostly
— Again, nothing is encrypted, so don’t plan on sensitive
stuff in the payload or header

where’s
the
code?JWTs WIYL! - Ohio LinuxFest 2017 – @genehack 68

Client side
use Crypt::JWT qw(encode_jwt);
use Crypt::PK::RSA;
use HTTP::Request;
# generate a JWT and POST a request
my $pri_key = Crypt::PK::RSA->new('./key.pri');
my $pub_key = Crypt::PK::RSA->new('./key.pub');
my $token = encode_jwt(
alg => 'RS512',
extra_headers => {
jwk => $pub_key->export_key_jwk('public', 1),
nonce => undef ,
},
key => $pri_key ,
payload => { iat => time() },
relative_exp => 1800,
);
HTTP::Request->new(
'POST' => 'https://example.com/endpoint',
['Authorization' => "Bearer $token"],
encode_json({ request => 'body' })
);

Client side: load the libraries & keys
use Crypt::JWT qw(encode_jwt);
use Crypt::PK::RSA;
use HTTP::Request;
my $pri_key = Crypt::PK::RSA->new('./key.pri');
my $pub_key = Crypt::PK::RSA->new('./key.pub');

Client side: make the token
my $token = encode_jwt(
alg => 'RS512',
extra_headers => {
nonce => undef ,
},
key => $pri_key ,
payload => { iat => time() },
relative_exp => 1800,
);

Client side: send the request
HTTP::Request->new(
'POST' => 'https://example.com/endpoint',
['Authorization' => "Bearer $token"],
encode_json({ request => 'body' })
);

Critical bit:adding the public key to the header
extra_headers => {
},
Pro tip: ﬁnd an RSA library that supports exporting keys to
JWK format!

API side
use Crypt::JWT qw(decode_jwt);
use Crypt::PK::RSA;
use Dancer;
use Try::Tiny;
my $auth_header = request_header 'Authorization' ;
my $token;
status_401 unless ( $token ) = $auth_header =~ /^Bearer (.*)$/;
# try to decode it and confirm valid sig,
# and valid iat and exp claims
my( $header, $payload );
try {
( $header, $payload ) = decode_jwt(
token => $token , decode_header => 1 ,
accepted_alg => 'RS512' ,
verify_iat => 1 , verify_exp => 1
);
};
# no catch block, just drop the error, we're out of here in that case
status_401 unless $header and $payload;
# check that expiration time is less than one hour
status_401 unless $payload->{exp} - $payload->{iat} < 3600;
# check that the included public key is on the whitelist
my $pk = Crypt::PK::RSA->new;
$pk->import_key($header->{jwk});
my $thumbprint = $pk->export_key_jwk_thumbprint;
status_401 unless config->{whitelist}{$thumbprint};
# if we get here, we're all good!
...

API side: get the token
use Crypt::JWT qw(decode_jwt);
use Crypt::PK::RSA;
use Dancer;
use Try::Tiny;
my $auth_header = request_header 'Authorization' ;
my $token;
status_401 unless ( $token ) = $auth_header =~ /^Bearer (.*)$/;

API side: decode the token
# try to decode it and confirm valid sig,
# and valid iat and exp claims
my( $header, $payload );
try {
( $header, $payload ) = decode_jwt(
token => $token , decode_header => 1 ,
accepted_alg => 'RS512' ,
verify_iat => 1 , verify_exp => 1
);
};
# no catch block, just drop the error, we're out of here in that case
status_401 unless $header and $payload;

API side: decode the token
— Key in header wrong? FAILS
— Not right algorithm? FAILS
— Doesn’t have iat and exp? FAILS
ALL that validation is happening inside the library, so I don’t
have to worry about it.
— Me? WINS

API side: more checks
— We specify in the API docs that tokens can only be valid for
one hour
— Have to check that ourselves
— Also need to make sure this isn’t some random RSA
keypair
— Need to make sure we know this public key

API side: more checks
# check that expiration time is less than one hour
status_401 unless $payload->{exp} - $payload->{iat} < 3600;
# check that the included public key is on the whitelist
my $pk = Crypt::PK::RSA->new;
$pk->import_key($header->{jwk});
my $thumbprint = $pk->export_key_jwk_thumbprint;
status_401 unless config->{whitelist}{$thumbprint};

API side: THAT’S ALL FOLKS
# if we get here, we're all good!
— We know the public key in the header by its ﬁngerprint,
— so we know the private key was used to sign the JWT
— (or it wouldn’t validate)
— and therefore the JWT is from the private key holder
— (who is, by deﬁnition, authorized!)

IMPORTANT NOTE!
This whole scheme does, of course, depend on the client
keeping the private key actually private
…but revocation is as simple as removing the ﬁngerprint from
the whitelist.

More advanced usage
— Encrypted payloads (JWE)
— Nested JWT
See those RFCs!

JWT
backlash

Conclusions
— JWTs solve some really common problems.
— JWTs solve them in a pretty elegant way.
— This is really pretty damn cool.

Conclusions
— JWTs solve some really common problems.
— JWTs solve them in a pretty elegant way.
— This is really pretty damn cool!!!
— You should think about using JWTs.

Thanks!
— JWT.io / auth0.com folks
— Ohio LinuxFest organizers
— YOU!

Questions?

JSON Web Tokens Will Improve Your Life

More Related Content

What's hot (20)

Similar to JSON Web Tokens Will Improve Your Life (20)

More from John Anderson (20)

Recently uploaded (20)

JSON Web Tokens Will Improve Your Life