EWD 3 Training Course Part 43: Using JSON Web Tokens with QEWD REST Services

Copyright © 2016 M/Gateway Developments Ltd
EWD 3 Training Course
Part 43
Using JSON Web Tokens
with QEWD REST Services
Rob Tweed
Director, M/Gateway Developments Ltd
Twitter: @rtweed

Using JSON Web Tokens with
QEWD REST Services
• This part of the course assumes that
you've taken, at least:
• Part 2: Overview of EWD 3
– https://www.slideshare.net/robtweed/ewd-3-overview
• Part 4: Installing & Configuring QEWD
– https://www.slideshare.net/robtweed/installing-configuring-ewdxpress
• Part 31: Using QEWD for Web and REST
Services
– http://www.slideshare.net/robtweed/ewd-3-training-course-part-31-ewdxpress-for-web-and-rest-services

JSON Web Tokens:
Background
• For an introduction on JSON Web Tokens
(JWTs), what they are, how they work and
when and why they should be considered,
see this presentation on QEWD and
JWTs:
• https://www.slideshare.net/robtweed/qewdjs-json-web-tokens-microservices

Moving to JWTs
• In this course, we'll change the example
application that was described in Part 31
– From using QEWD server-side Sessions
– To using browser-side JWTs

Our original QEWD startup file
var config = {
managementPassword: 'keepThisSecret!',
serverName: 'QEWD REST Server',
port: 8080,
poolSize: 2,
database: {
type: 'gtm'
}
};
var routes = [
{path: '/api', module: 'myRestService'}
];
var qewd = require('qewd').master;
qewd.start(config, routes);
~/qewd/rest.js

Tell QEWD to enable JWTs
var config = {
managementPassword: 'keepThisSecret!',
serverName: 'QEWD REST Server',
port: 8080,
poolSize: 2,
database: {
type: 'gtm'
},
jwt: {
secret: 'someSecret123'
}
};
var routes = [
{path: '/api', module: 'myRestService'}
];
var qewd = require('qewd').master;
qewd.start(config, routes);
The secret can be any
text string you want.
The longer and less
guessable the better

Modify the Worker Process
Handler Module
• Instead of standard server-side QEWD
Sessions:
– /api/login should create a new JWT
• Send it as the token response just as before

Handler Module
Sessions:
– All other routes should include the JWT in the
Authorization Header
• Authorization: Bearer {{JWT}}

Handler Module
Sessions:
– All other routes should include the JWT in the
Authorization Header
• Authorization: Bearer {{JWT}}
– Validate the incoming JWT and use its
payload to get/set session values

Edit the handler module
• ~/qewd/node_modules/myRestService.js
• All we need to do is:
– Modify the login() function
– Modify the beforeHandler() function

Original Login Function
function login(args, finished) {
var username = args.req.body.username;
if (!username || username === '') {
return finished({error: 'You must provide a username'});
}
var password = args.req.body.password;
if (!password || password === '') {
return finished({error: 'You must provide a password'});
}
if (username !== 'rob') return finished({error: 'Invalid username'});
if (password !== 'secret') return finished({error: 'Invalid password'});
var session = this.sessions.create('testWebService', 3600);
session.authenticated = true;
session.data.$('username').value = username;
finished({token: session.token});
}

Change to use JWTs
}
}
var session = this.jwt.handlers.createRestSession.call(this, args);
session.welcomeText = 'Welcome ' + username;
session.username = username;
session.timeout = 1200;
var jwt = this.jwt.handlers.setJWT.call(this, session);
finished({token: jwt});
}

Change to use JWTs
}
}
}
Create a new JWT-compatible
Session object, using
information from the request
this.jwt.handlers provides
the APIs you'll need for JWT
Handling

Change to use JWTs
}
}
}
Add some extra properties
of our own to the
Session Object

Change to use JWTs
}
}
}
The authenticated and
timeout properties are
special built-in ones
timeout specifies how
long before the JWT
expires

Change to use JWTs
}
}
}
Create a JWT from
the Session data.
The secret you defined in the
startup file is used by QEWD
to sign the JWT

Change to use JWTs
}
}
}
Finally, return the
JWT as the response

Start QEWD using your startup file
cd ~/qewd
node rest

Try out the /api/login Request

Here's our JWT

Inspecting a JWT
• Use:
– https://jwt.io/

Inspecting a JWT

Here's our JWT
A JWT has 3 Base64-encoded parts, separated by a "."

Here's our JWT
We're only really interested in the middle bit – the payload

Our JWT Payload: Decoded
Anyone can Base64 Decode the payload of a JWT
Secret is not required for this

Here's the timeout we set

…and the other properties we set in the Session

These are reserved JWT payload properties
QEWD created them for you
Known as "reserved claims"

This was added by QEWD, using the incoming
Request payload data. It's used by QEWD
internally

The qewd property/claim is encrypted using the
Secret, so is only usable by anyone with access
to the Secret. It contains data for use in the QEWD
Back-end only

You can optionally add data into this private claim,
but only from within your worker process handler
functions: see later

If a client returning a JWT makes any changes to
the payload, the signature will no longer match,
so it will be rejected by QEWD

Add the JWT Authorization Header

Here's the original
beforeHandler() function
beforeHandler: function(req, finished) {
if (req.path !== '/api/login') {
return this.sessions.authenticateRestRequest(req, finished);
}
},
Using server-side
QEWD Sessions

Modified to use JWTs
beforeHandler: function(req, finished) {
if (req.path !== '/api/login') {
return this.jwt.handlers.validateRestRequest.call(this, req, finished);
}
},
Change to use this API
- Checks the JWT's signature
using the Secret
- Checks if the JWT has expired
- Unpacks the JWT payload into
the Session object
- Decrypts the qewd claim

We'll try the /api/search API
• But first we need to check its handler
function:
init: function(application) {
routes = [
{
url: '/api/search',
//method: 'GET',
handler: search
},

Original /api/search handler function
function search(args, finished) {
console.log('*** search args: ' + JSON.stringify(args, null, 2));
finished({
test: 'finished ok',
username: args.session.data.$('username').value
});
}

finished({
});
}
Will display the args object
To the QEWD Node.js console

finished({
});
}
Returns the username from
the back-end QEWD Session

Change it to use the JWT-derived Session
finished({
username: args.session.username
});
}
args.session now contains
the Session object, containing
the JWT payload
QEWD did this for us
automatically

Restart QEWD and Try It

Take a look at the QEWD
Node.js Console Log
*** search args: {
"req": {
"type": "ewd-qoper8-express",
"path": "/api/search",
"method": "GET",
"headers": {
"host": "192.168.1.117:8080",
"authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MD…",
"content-type": "application/json"
},
"params": {
"type": "search"
},
"query": {},
"body": {},
"ip": "::ffff:192.168.1.74",
"ips": [],
"application": "api",
"expressType": "search",
…...
Here's the args object

Scroll down further…
"session": {
"exp": 1503046402,
"iat": 1503045202,
"iss": "qewd.jwt",
"timeout": 1200,
"qewd": {
"ipAddress": "::ffff:192.168.1.74",
"authenticated": true
},
"welcomeText": "Welcome rob",
"username": "rob",
"qewd_list": {
"ipAddress": true,
},
"ipAddress": "::ffff:192.168.1.74",
}
}
Here's args.session
Contains the JWT payload
values

args.session
"session": {
"exp": 1503046402,
"iat": 1503045202,
"iss": "qewd.jwt",
"timeout": 1200,
"qewd": {
"ipAddress": "::ffff:192.168.1.74",
},
"username": "rob",
"qewd_list": {
"ipAddress": true,
},
"ipAddress": "::ffff:192.168.1.74",
}
}
Here's the username
value that was added
to the JWT Session
by the login function

args.session
"session": {
"exp": 1503046402,
"iat": 1503045202,
"iss": "qewd.jwt",
"timeout": 1200,
"qewd": {
"ipAddress": "::ffff:192.168.1.74",
},
"username": "rob",
"qewd_list": {
"ipAddress": true,
},
"ipAddress": "::ffff:192.168.1.74",
}
}
But also notice the
qewd claim
It's been decrypted

args.session
"session": {
"exp": 1503046402,
"iat": 1503045202,
"iss": "qewd.jwt",
"timeout": 1200,
"qewd": {
"ipAddress": "::ffff:192.168.1.74",
},
"username": "rob",
"qewd_list": {
"ipAddress": true,
},
"ipAddress": "::ffff:192.168.1.74",
}
}
And its properties have
been copied to
args.session, as
properties in their
own right

JWT-based Session
• Your handler functions can
add/change/delete properties within the
Session by accessing the args.session
properties
• Don't modify the reserved claim properties
– iss
– exp
– iat
– application

JWT-based Session
• By default, any properties you add to the
Session will be visible within the JWT
payload (after Base64 decoding)
• We saw this with the username and
welcomeText fields
– Added in the login() function
– We cut and pasted the JWT into the jwt.io
Inspector screen

Here's the login() function
}
}
}
username and
welcomeText
added to the
Session Object

JWT-based Session
• There may be properties/values that you
want to add to the JWT/Session that are
visible and usable in your back-end
handler functions, but too sensitive to be
visible to the client/user
• QEWD makes this easy

JWT-based Session
• There may be properties/values that you
want to add to the JWT/Session that are
visible and usable in your back-end
handler functions, but too sensitive to be
visible to the client/user
• QEWD makes this easy
– Let's make the username secret, but leave the
welcomeText visible

Edit the login() function
}
}
session.makeSecret('username');
}
Just add this

Restart QEWD. Send /api/login

Restart QEWD. Send /api/login
Copy the JWT

Paste it into the jwt.io Inspector

Paste it into the jwt.io Inspector
welcomeText is still visible
but username has disappeared
It's been encrypted into the qewd
claim

Now send /api/search using new JWT

Now send /api/search using new JWT
username appears as before

Take a look at args.session in
the QEWD Node.js Console Log
"session": {
"exp": 1503049897,
"iat": 1503048697,
"iss": "qewd.jwt",
"timeout": 1200,
"qewd": {
"ipAddress": "::ffff:192.168.1.74",
"authenticated": true,
"username": "rob"
},
"qewd_list": {
"ipAddress": true,
"username": true
},
"ipAddress": "::ffff:192.168.1.74",
"username": "rob"
}

"session": {
"exp": 1503049897,
"iat": 1503048697,
"iss": "qewd.jwt",
"timeout": 1200,
"qewd": {
"ipAddress": "::ffff:192.168.1.74",
"username": "rob"
},
"qewd_list": {
"ipAddress": true,
"username": true
},
"ipAddress": "::ffff:192.168.1.74",
"username": "rob"
}
username is inside the
qewd sub-object

"session": {
"exp": 1503049897,
"iat": 1503048697,
"iss": "qewd.jwt",
"timeout": 1200,
"qewd": {
"ipAddress": "::ffff:192.168.1.74",
"username": "rob"
},
"qewd_list": {
"ipAddress": true,
"username": true
},
"ipAddress": "::ffff:192.168.1.74",
"username": "rob"
}
And has been added as a
property in its own right to
args.session

"session": {
"exp": 1503049897,
"iat": 1503048697,
"iss": "qewd.jwt",
"timeout": 1200,
"qewd": {
"ipAddress": "::ffff:192.168.1.74",
"username": "rob"
},
"qewd_list": {
"ipAddress": true,
"username": true
},
"ipAddress": "::ffff:192.168.1.74",
"username": "rob"
}
If the JWT is updated, username
remains secret. It is removed as
a property in its own right before the
JWT is created

"session": {
"exp": 1503049897,
"iat": 1503048697,
"iss": "qewd.jwt",
"timeout": 1200,
"qewd": {
"ipAddress": "::ffff:192.168.1.74",
"username": "rob"
},
"qewd_list": {
"ipAddress": true,
"username": true
},
"ipAddress": "::ffff:192.168.1.74",
"username": "rob"
}
If the JWT is updated, username
remains secret. It is removed as
a property in its own right before the
JWT is created
That's the purpose of this
QEWD-managed sub-object

Modifying/Updating the JWT
• You may want to add
values/objects/arrays to the JWT-based
session within your handler functions
• If so, you need to create a new JWT using
the args.session object and return it with
the response
• It's a good idea to return an updated JWT
even if you don't add/change session data
– To update the JWT's expiry time

Modifying/Updating the JWT
• Let's make the /api/search handler update
the JWT

Here's our search() function
finished({
});
}

Edit the search() function
args.session.ranSearchAt = Date.now();
finished({
});
}
Add a new property – ranSearchAt -
to args.session

var jwt = this.jwt.handlers.setJWT.call(this, args.session);
finished({
});
} Create a new JWT using args.session

finished({
username: args.session.username,
token: jwt
});
}
Return the new JWT with the response

Restart QEWD and send /api/search

Here's the new JWT – let's inspect it

The new JWT

The new JWT
Here's the field we added

Where is username?

Look in the search() function
finished({
token: jwt
});
}
We're asking it to send the username
using the value in args.session.username

Look in the search() function
finished({
token: jwt
});
}
We're asking it to send the username
using the value in args.session.username
But we're doing this after we created the
new JWT. In doing so, all secret fields
have been removed from args.session
So args.session.username no longer
exists

var username = args.session.username;
finished({
username: username,
token: jwt
});
} Let's get hold of the username value
before the JWT is created, and
send that value in the response

Restart QEWD and Try Again

Restart QEWD and Try Again
Now username appears as expected

Using JWTs with QEWD REST Services
• You now know everything needed to use
JWTs with QEWD.js REST Services
• JWTs allow a very different approach to
authentication and session management
– Completely stateless architecture
– Does not require any database for session
management
– State/session info is held by client in the JWT

• JWTs allow you to scale out your
QEWD.js systems
– Multiple QEWD systems just need to share
the same secret
• Each defines the same secret text string in their
QEWD startup file

JWT security
Server
Client
Both servers share same secret key
Server

JWT security
Server
Client
Server
Create initial JWT

JWT security
Server
Client
Server
Validate and use JWT

QEWD.js Architecture
ewd-qoper8
queue
Express
Node.js
socket.io
Cache
GT.M,
YottaDB
Redis
Node.js
Worker
Process
Cache
GT.M,
YottaDB
Redis
Node.js
Worker
Process
Cache
GT.M,
YottaDB
Redis
Node.js
Worker
Process
ewd-qoper8
queue
Express
Node.js
socket.io
Cache
GT.M,
YottaDB
Redis
Node.js
Worker
Process
Cache
GT.M,
YottaDB
Redis
Node.js
Worker
Process
Cache
GT.M,
YottaDB
Redis
Node.js
Worker
Process
ewd-qoper8
queue
Express
Node.js
socket.io
Cache
GT.M,
YottaDB
Redis
Node.js
Worker
Process
Cache
GT.M,
YottaDB
Redis
Node.js
Worker
Process
Cache
GT.M,
YottaDB
Redis
Node.js
Worker
Process
Load Balancer
Or Proxy (eg nginx)
Same Secret

• JWTs also provide the basis by which you
can break out your QEWD.js applications
into fine-grained MicroServices, each
running in their own separate
machine/VM/container
• This will be described in the next part of
this course.

EWD 3 Training Course Part 43: Using JSON Web Tokens with QEWD REST Services

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to EWD 3 Training Course Part 43: Using JSON Web Tokens with QEWD REST Services

Similar to EWD 3 Training Course Part 43: Using JSON Web Tokens with QEWD REST Services (20)

More from Rob Tweed

More from Rob Tweed (14)

Recently uploaded

Recently uploaded (20)

EWD 3 Training Course Part 43: Using JSON Web Tokens with QEWD REST Services