ocramius / psr7-session
Storageless PSR-7 Session support
Installs: 3 510
Dependents: 0
Suggesters: 0
Security: 0
Stars: 648
Watchers: 24
Forks: 38
Open Issues: 7
Requires
- php: ~8.2.0 || ~8.3.0
- dflydev/fig-cookies: ^3.1.0
- lcobucci/clock: ^3.2.0
- lcobucci/jwt: ^5.1.0
- psr/http-message: ^1.1 || ^2.0
- psr/http-server-handler: ^1.0.2
- psr/http-server-middleware: ^1.0.2
Requires (Dev)
- doctrine/coding-standard: ^12.0.0
- laminas/laminas-diactoros: ^3.3.0
- laminas/laminas-httphandlerrunner: ^2.9.0
- phpunit/phpunit: ^9.6.13
- psalm/plugin-phpunit: ^0.18.4
- roave/infection-static-analysis-plugin: ^1.33.0
- squizlabs/php_codesniffer: ^3.7.2
- vimeo/psalm: ^5.15.0
Replaces
- ocramius/psr7-session: 9.1.0
- dev-master
- 9.2.x-dev
- 9.1.x-dev
- 9.1.0
- 9.0.x-dev
- 9.0.1
- 9.0.0
- 8.18.x-dev
- 8.17.x-dev
- 8.17.0
- 8.16.x-dev
- 8.16.0
- 8.15.x-dev
- 8.15.0
- 8.14.x-dev
- 8.14.0
- 8.13.x-dev
- 8.13.0
- 8.12.x-dev
- 8.12.0
- 8.11.x-dev
- 8.11.0
- 8.10.x-dev
- 8.10.0
- 8.9.x-dev
- 8.9.0
- 8.8.x-dev
- 8.8.0
- 8.7.x-dev
- 8.7.0
- 8.6.x-dev
- 8.6.0
- 8.5.x-dev
- 8.5.0
- 8.4.x-dev
- 8.4.0
- 8.3.x-dev
- 8.3.0
- 8.2.x-dev
- 8.2.0
- 8.1.x-dev
- 8.1.0
- 8.0.x-dev
- 8.0.0
- 7.4.x-dev
- 7.3.x-dev
- 7.3.0
- 7.2.x-dev
- 7.2.0
- 7.1.x-dev
- 7.1.0
- 7.0.x-dev
- 7.0.0
- 6.0.x-dev
- 6.0.0
- 5.1.0
- 5.0.x-dev
- 5.0.0
- 4.0.x-dev
- 4.0.0
- 3.0.x-dev
- 3.0.1
- 3.0.0
- 2.0.x-dev
- 2.0.0
- 1.0.x-dev
- 1.0.2
- 1.0.1
- 1.0.0
- dev-renovate/phpunit-phpunit-11.x
- dev-renovate/all-minor-patch
- dev-renovate/lock-file-maintenance
- dev-dependabot/add-v2-config-file
This package is auto-updated.
Last update: 2024-10-14 21:39:47 UTC
README
PSR7Session is a PSR-7 and PSR-15 compatible middleware that enables session without I/O usage in PSR-7 based applications.
Proudly brought to you by ocramius, malukenho and lcobucci.
Installation
composer require psr7-sessions/storageless
Usage
You can use the PSR7Sessions\Storageless\Http\SessionMiddleware
in any
PSR-15
compatible middleware.
In a mezzio/mezzio
application, this would look like following:
use Lcobucci\JWT\Configuration as JwtConfig; use Lcobucci\JWT\Signer; use Lcobucci\JWT\Signer\Key\InMemory; use PSR7Sessions\Storageless\Http\SessionMiddleware; use PSR7Sessions\Storageless\Http\Configuration as StoragelessConfig; $app = new \Mezzio\Application(/* ... */); $app->pipe(new SessionMiddleware( new StoragelessConfig( JwtConfig::forSymmetricSigner( new Signer\Hmac\Sha256(), InMemory::base64Encoded('OpcMuKmoxkhzW0Y1iESpjWwL/D3UBdDauJOe742BJ5Q='), // replace this with a key of your own (see below) ) ) ));
After this, you can access the session data inside any middleware that
has access to the Psr\Http\Message\ServerRequestInterface
attributes:
$app->get('/get', function (ServerRequestInterface $request, ResponseInterface $response) : ResponseInterface { /** @var \PSR7Sessions\Storageless\Session\SessionInterface $session */ $session = $request->getAttribute(SessionMiddleware::SESSION_ATTRIBUTE); $session->set('counter', $session->get('counter', 0) + 1); $response ->getBody() ->write('Counter Value: ' . $session->get('counter')); return $response; });
You can do this also in asynchronous contexts and long-running processes, since no super-globals nor I/O are involved.
It is recommended that you use a key with lots of entropy, preferably generated using a cryptographically secure pseudo-random number generator (CSPRNG). You can use the CryptoKey tool to do this for you.
Note that you can also use asymmetric keys; please refer to
lcobucci/jwt
documentation:
- The
Configuration
object: https://lcobucci-jwt.readthedocs.io/en/stable/configuration/ - Supported algorithms: https://lcobucci-jwt.readthedocs.io/en/stable/supported-algorithms/
Session Hijacking mitigation
To mitigate the risks associated to cookie stealing and thus
session hijacking,
you can bind the user session to its IP ($_SERVER['REMOTE_ADDR']
) and
User-Agent ($_SERVER['HTTP_USER_AGENT']
) by enabling client fingerprinting:
use PSR7Sessions\Storageless\Http\SessionMiddleware; use PSR7Sessions\Storageless\Http\Configuration as StoragelessConfig; use PSR7Sessions\Storageless\Http\ClientFingerprint\Configuration as FingerprintConfig; $app = new \Mezzio\Application(/* ... */); $app->pipe(new SessionMiddleware( (new StoragelessConfig(/* ... */)) ->withClientFingerprintConfiguration( FingerprintConfig::forIpAndUserAgent() ) ));
If your PHP service is behind a reverse proxy of yours, you may need to retrieve the client IP from a different source of truth.
In such cases you can extract the information you need by writing a custom
\PSR7Sessions\Storageless\Http\ClientFingerprint\Source
implementation:
use Psr\Http\Message\ServerRequestInterface; use PSR7Sessions\Storageless\Http\SessionMiddleware; use PSR7Sessions\Storageless\Http\Configuration as StoragelessConfig; use PSR7Sessions\Storageless\Http\ClientFingerprint\Configuration as FingerprintConfig; use PSR7Sessions\Storageless\Http\ClientFingerprint\Source; $app = new \Mezzio\Application(/* ... */); $app->pipe(new SessionMiddleware( (new StoragelessConfig(/* ... */)) ->withClientFingerprintConfiguration( FingerprintConfig::forSources(new class implements Source{ public function extractFrom(ServerRequestInterface $request): string { return $request->getHeaderLine('X-Real-IP'); } }) ) ));
Examples
Simply browse to the examples
directory in your console, then run
php -S localhost:9999 index.php
Then try accessing http://localhost:9999
: you should see a counter
that increases at every page refresh
WHY?
In most PHP+HTTP related projects, ext/session
serves its purpose and
allows us to store server-side information by associating a certain
identifier to a visiting user-agent.
What is the problem with ext/session
?
This is all fair and nice, except for:
- relying on the
$_SESSION
superglobal - relying on the shutdown handlers in order to "commit" sessions to the storage
- having a huge limitation of number of active users (due to storage)
- having a lot of I/O due to storage
- having serialized data cross different processes (PHP serializes and
de-serializes
$_SESSION
for you, and there are security implications) - having to use a centralized storage for setups that scale horizontally
- having to use sticky sessions (with a "smart" load-balancer) when the storage is not centralized
- not designed to be used for multiple dispatch cycles
What does this project do?
This project tries to implement storage-less sessions and to mitigate the issues listed above.
Assumptions
- your sessions are fairly small and contain only few identifiers and
some CSRF tokens. Small means
< 400
bytes - data in your session is
JsonSerializable
or equivalent - data in your session is freely readable by the client
How does it work?
Session data is directly stored inside a session cookie as a JWT token.
This approach is not new, and is commonly used with Bearer
tokens in
HTTP/REST/OAuth APIs.
In order to guarantee that the session data is not modified, that the client can trust the information and that the expiration date is mutually agreed between server and client, a JWT token is used to transmit the information.
The JWT token is always signed to ensure that the user-agent is never able to manipulate the session. Both symmetric and asymmetric keys are supported for signing/verifying tokens.
Advantages
- no storage required
- no sticky sessions required (any server having a copy of the private or public keys can generate sessions or consume them)
- can transmit cleartext information to the client, allowing it to share some information with the server (a standard example is about sharing the "username" or "user-id" in a given session)
- can transmit encrypted information to the client, allowing server-only consumption of the information
- not affected by PHP serialization RCE attacks
- not limited to PHP process scope: can have many sessions per process
- no reliance on global state
- when in a multi-server setup, you may allow read-only access to servers that only have access to public keys, while writes are limited to servers that have access to private keys
- can be used over multiple dispatch cycles
Configuration options
Please refer to the configuration documentation.
Known limitations
Please refer to the limitations documentation.
Contributing
Please refer to the contributing notes.
License
This project is made public under the MIT LICENSE.