jwt-guard

Provides Express middleware for guarding resources based on JWT roles and claims. Supports chaining with and/or.

Works great with Auth0 or other JWT implementations.

app.get('/user/:id', function (req, res) {
    req.token.require
        .role('admin')
        .or.claim('user_id', req.params.id)
        .guard()    

    res.send('You are allowed to access this user!')
})

• Installation
• Usage
  • Guard
    • Using roles
    • Using claims
    • Chaining roles and claims
  • Check
  • Getting a claim

Installation

npm install jwt-guard

Include the Express middleware as early as possible. It validates and decodes the JWT from the Authorization: Bearer header using jsonwebtoken.

import express from 'express'
import jwtGuard from 'jwt-guard'

const app = express()

app.use(jwtGuard('secret_key_shhhhh'))

Usage

.token is added to every request object. This can be used to guard access by requiring roles and/or claims.

Guard

Guarding throws an HTTP error on failure.

Using roles

Roles come from the roles: claim in the JWT.

app.get('/admin-area', function (req, res) {
    req.token.require.role('admin').guard()
    
    res.send('Welcome to the secret area')
})

Using claims

Claims come from the payload of the JWT. Often this is used to hold things like user_id.

app.post('/user', function (req, res) {
    const userId = req.body.user_id

    req.token.require.claim('user_id', user_id)
        .guard('Sorry you can only update your own account.')

    // passed, update logic here
})

Chaining roles and claims

You can require multiple roles and claims by chaining with or and and.

app.post('/blog', function (req, res) {
    req.token.require
        .role('blog:post')
        .or.role('blog:admin')
        .or.role('god')
        .guard()
    
    // passed, post the blog
})

app.delete('/blog/:id', function (req, res) {
    const blogPost = '...'

    req.token.require
        .role('admin')
        .or.claim('user_id', blogPost.ownerUserId)
        .and.role('blog:delete')
        .guard()
    
    // passed, delete the blog
})

Check

Works like .guard() but returns true/false instead of throwing an error. Supports [chaining](#Chaining roles and claims) as well.

app.get('/admin-area', function (req, res) {
    const isAdmin = req.token.require.role('admin').check
    
    if(isAdmin) {
        res.send('Welcome to the secret area')
    } else{
        res.redirect('/')
    }
})

Getting a claim

Retrieving the value of a claim is easy

app.get('/', function (req, res) {
    const name = req.token.claims.name
    
    res.send(`Hello ${name}`)
})