README.md

Strapi JWT Cookies

Securely use users-permissions's JWT on cookies. Compatible with Strapi v4 and requires @strapi/plugin-users-permissions@^4.1.12

How this package works

This package extends the @strapi/plugin-users-permissions core plugin via Extending a plugin's interface. It exports a higher-order function to wrap strapi-server customization.

What this package does to the plugin

• Adds two middlewares and applies the jwtCookieSetter middleware to auth routes only, so it wont affect the other routes.
• Adds one route and logout controller to remove cookie server-side: POST /api/auth/logout

Features

• Split JWT into two cookies, httpOnly for JWT header.signature and javascript-accessible cookie for the payload, so frontend can easily read the JWT payload. read it more here
• Automatically log out on user inactivity by setting cookie expires

How About CSRF?

Note that this package doesn't add a CSRF prevention mechanism, but it does ensure the request is from the frontend by using SameSite flag sets to lax, and by checking request custom headers which only can be sent from the same CORS domain.

• set X-Requested-With to XMLHttpRequest to be able receive and validate jwt cookies on the server

Install

npm install --save @bwyx/strapi-jwt-cookies

Create file under directory src/extensions/users-permissions/strapi-server.js:

// src/extensions/users-permissions/strapi-server.js

module.exports = require('@bwyx/strapi-jwt-cookies')(); 

If you already extend the strapi-server.js, you could wrap your function like this:

const withJwtCookie = require('@bwyx/strapi-jwt-cookies');

module.exports = withJwtCookie((plugin) => {
  // some customization

  return plugin
});

Then add the global middleware, this middleware reconstructs JWT from request cookies and then assigns it to headers.authorization

// config/middlewares.js

module.exports = [
  'strapi::errors',
  ...
  'strapi::public',
  'plugin::users-permissions.jwtCookieGetter'
]

Configurations

By default, frontend users will be logged out after 30 mins of inactivy (not make an api request)

COOKIE_PAYLOAD_LIFESPAN_MINUTES=30

You can restrict the cookie to your specific frontend domain (recommended):

FRONTEND_DOMAIN=myfrontend.com

The default cookies name are user for the payload and token for headers.signature, you can prefix the cookies name with env

APP_NAME=myapp

then the cookies will be myapp_user and myapp_token

TODO

• Add test (?)

References

• Getting Token Authentication Right in a Stateless Single Page Application by Peter Locke