sidebar_key	jwt-session
sidebar_category	http-apis
tags	php cryptography authentication

JWT Session Handler

Keep using $_SESSION, but store the session in a signed JWT cookie instead of on the server: no Redis, no sticky sessions.

Why

PHP sessions live on the server that created them. Behind a load balancer, that means sticky sessions or a shared store such as Redis or Memcached, one more service to run for data the user already carries in a cookie.

JWT Session is a SessionHandlerInterface, so nothing else in the application changes:

$handler = new JwtSession((new SessionConfig('your.domain.com'))->withSecret($secret));
session_set_save_handler($handler, true);

session_start();
$_SESSION['user'] = 'john';   // stored in a signed token, not on the server

Any server that has the key can read the session, so the application scales without a session store. Sign with a shared secret, or with an RSA key pair so other services can verify the session without being able to forge it.

Documentation

• Getting Started - Installation, basic usage, and motivation
• Configuration - Session timeout, contexts, cookies, and all configuration options
• RSA Keys - Using RSA private/public keys for enhanced security
• How It Works - Architecture and internal implementation details
• Security - Security considerations and best practices
• API Reference - Complete API documentation for all classes and methods

How to use

Before the session_start() use the command:

<?php
$sessionConfig = (new \ByJG\Session\SessionConfig('your.domain.com'))
    ->withSecret('your base64 encoded 64-byte secret key');

$handler = new \ByJG\Session\JwtSession($sessionConfig);
session_set_save_handler($handler, true);

Now, all your $_SESSION variable will be saved directly to a JWT Token!!

Note: The secret must be base64 encoded (standard alphabet) and decode to at least 64 bytes: the token is signed with HS512, and a shorter key fails with Provided key is too short when the session is written. Create one with:

php -r 'echo base64_encode(random_bytes(64)), PHP_EOL;'

For more details on motivation, security considerations, and best practices, see the Documentation section above.

Configuration Examples

Setting the validity of JWT Token

<?php
$sessionConfig = (new \ByJG\Session\SessionConfig('your.domain.com'))
    ->withSecret('your base64 encoded 64-byte secret key')
    ->withTimeoutMinutes(60);   // You can use withTimeoutHours(1)

$handler = new \ByJG\Session\JwtSession($sessionConfig);
session_set_save_handler($handler, true);

Setting different Session Contexts

<?php
$sessionConfig = (new \ByJG\Session\SessionConfig('your.domain.com'))
    ->withSecret('your base64 encoded 64-byte secret key')
    ->withSessionContext('MYCONTEXT');

$handler = new \ByJG\Session\JwtSession($sessionConfig);
session_set_save_handler($handler, true);

For complete configuration options including cookie domains and automatic session handler replacement, see Configuration.

Using RSA Private/Public Keys

<?php
        $secret = <<<PRIVATE
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA5PMdWRa+rUJmg6QMNAPIXa+BJVN7W0vxPN3WTK/OIv5gxgmj
2inHGGc6f90TW/to948LnqGtcD3CD9KsI55MubafwBYjcds1o9opZ0vYwwdIV80c
OVZX1IUZFTbnyyKcXeFmKt49A52haCiy4iNxcRK38tOCApjZySx/NzMDeaXuWe+1
nd3pbgYa/I8MkECa5EyabhZJPJo9fGoSZIklNnyq4TfAUSwl+KN/zjj3CXad1oDT
7XDDgMJDUu/Vxs7h3CQI9zILSYcL9zwttbLnJW1WcLlAAIaAfABtSZboznsStMnY
to01wVknXKyERFs7FLHYqKQANIvRhFTptsehowIDAQABAoIBAEkJkaQ5EE0fcKqw
K8BwMHxKn81zi1e9q1C6iEHgl8csFV03+BCB4WTUkaH2udVPJ9ZJyPArLbQvz3fS
wl1+g4V/UAksRtRslPkXgLvWQ2k8KoTwBv/3nn9Kkozk/h8chHuii0BDs30yzSn4
SdDAc9EZopsRhFklv9xgmJjYalRk02OLck73G+d6MpDqX56o2UA/lf6i9MV19KWP
HYip7CAN+i6k8gA0KPHwr76ehgQ6YHtSntkWS8RfVI8fLUB1UlT3HmLgUBNXMWkQ
ZZbvXtNOt6NtW/WIAHEYeE9jmFgrpW5jKJSLn5iGVPFZwJIZXRPyELEs9NHWkS6e
GmdzxnECgYEA8+m05B/tmeZOuMrPVJV9g+aBDcuxmW+sdLRch+ccSmx4ZNQOLVoU
klYgTZq/a1O4ENq0h2WgccNlRHdcH4sXMBvLalA/tFhZMUuA/KXWyZ1F0hBnjHVF
cj1alHCqh+9qJDGdn4mxSmrp8p0rfeWgBwlFtJEJmjjDWDCtVY+JZcsCgYEA8EuV
WF/ilgDjgC4jMCYNuO0oFGBbtNP17PuU3kh8W+joqK/nufZ3NLy1WrDIpqa9YPex
328Nnjljf5GJWSdMchAp82waLzl7FaaBTY0iyFAK4J0jfC/fVLx82+wpM3utDnh8
9x5iIboO5U7uEJ7k8X2p64GoprlKJSRmGAJ7eIkCgYEAw5IsXI3NMY0cqcbUHvoO
PehgqfMdX+3O1XSYjM+eO35lulLdWzfTLtKn7BGcUi46dCkofzfZQd5uIEukLhaU
bRqcK45UxgHg4kmsDufaJKZaCWjl3hVZrZPMQSFlWsF41bSCshzxbr3y/3lOGhA4
E+w3W+S/Uk0ZNGkzUltYy6kCgYEA0gRNeBr9z7rhG4O3j3qC3dCxCfYZ0Na8hy5v
M0PJJQ9QYTa04iyOjVItcyE1jaoHtLtoA+9syJBB7RoHIBufzcVg1Pbzf7jOYeLP
+jbTYp3Kk/vjKsQwfj/rJM+oRu3eF9qo5dbxT6btI++zVGV7lbEOFN6Sx30EV6gT
bwKkZXkCgYEAnEtN43xL8bRFybMc1ZJErjc0VocnoQxCHm7LuAtLOEUw6CwwFj9Q
GOl+GViVuDHUNQvURLn+6gg4tAemYlob912xIPaU44+lZzTMHBOJBGMJKi8WogKi
V5+cz9l31uuAgNfjL63jZPaAzKs8Zx6R3O5RuezympwijCIGWILbO2Q=
-----END RSA PRIVATE KEY-----
PRIVATE;

        $public = <<<PUBLIC
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5PMdWRa+rUJmg6QMNAPI
Xa+BJVN7W0vxPN3WTK/OIv5gxgmj2inHGGc6f90TW/to948LnqGtcD3CD9KsI55M
ubafwBYjcds1o9opZ0vYwwdIV80cOVZX1IUZFTbnyyKcXeFmKt49A52haCiy4iNx
cRK38tOCApjZySx/NzMDeaXuWe+1nd3pbgYa/I8MkECa5EyabhZJPJo9fGoSZIkl
Nnyq4TfAUSwl+KN/zjj3CXad1oDT7XDDgMJDUu/Vxs7h3CQI9zILSYcL9zwttbLn
JW1WcLlAAIaAfABtSZboznsStMnYto01wVknXKyERFs7FLHYqKQANIvRhFTptseh
owIDAQAB
-----END PUBLIC KEY-----
PUBLIC;

$sessionConfig = (new \ByJG\Session\SessionConfig('example.com'))
    ->withRsaSecret($secret, $public)
    ->replaceSessionHandler();

$handler = new \ByJG\Session\JwtSession($sessionConfig);

For more details about RSA keys and how to generate them, see RSA Keys and https://github.com/byjg/jwt-wrapper

Installation

composer require "byjg/jwt-session"

Running Tests

vendor/bin/phpunit

---

Open source ByJG