Download the PHP package locksyk/api-session-bundle without Composer

ApiSessionBundle

Stateful Symfony firewalls for API endpoints: the session id travels in the Authorization: Bearer header instead of a cookie.

Status: published. Available on Packagist as locksyk/api-session-bundle; feature-complete against its design (DESIGN.md) and fully tested. Pre-1.0: minor releases may still adjust the API.

Why

Stateless token schemes (JWT & friends) give up what server-side sessions provide for free: instant revocation, server-side state, idle expiry, no claims-refresh problem. This bundle keeps Symfony's ordinary session machinery - it just moves the session id out of the cookie and into a bearer token:

• Bearer-token sessions - no Set-Cookie on API responses, ever; session cookies sent by clients are ignored. The token is handed to the client at login and presented as Authorization: Bearer <token>.
• Pre-authentication sessions work - a session created before login (a WebAuthn challenge, OIDC state, a CSRF-protected form) gets a token too, and login rotates it (fixation protection included).
• Explicit switch-user endpoints - impersonation only exists on routes the app mounts; the generic _switch_user parameter never works.
• Coexistence - tokens the bundle doesn't recognise (OIDC access tokens, HTTP Basic, API keys) pass through untouched to the rest of the authenticator chain on the same firewall.
• Optional absolute lifetime + refresh - expiry is embedded and signed in the token itself; no server-side bookkeeping to corrupt.

Requirements: PHP >= 8.2, Symfony 6.4 LTS, 7.x or 8.x (Symfony 8 requires PHP >= 8.4).

Installation

Enable the bundle (Flex does this automatically):

Quick start

Keep your firewall exactly as it would be for cookie sessions - any authenticator works (json_login, WebAuthn, OIDC, custom):

Then bridge it:

Optionally mount the ready-made login responder (the authenticator still handles credentials; this shapes the success response):

That's it. Log in and the response carries the session token in the X-Session-Token header (and, with LoginController, in the body as {user, roles, token}); present it on every request:

The client contract

A ready-made browser implementation, @locksyk/api-session-client, lives in frontend/ - a dependency-free TypeScript module with a drop-in fetch wrapper. The rules it implements:

• Whenever a response carries the token header (X-Session-Token by default), it announces the current token - store it and use it from then on. In practice the token changes at anonymous-session creation and at login; a refresh (below) mints an additional token.
• A 401 carrying WWW-Authenticate: Bearer error="invalid_token" (RFC 6750) means the presented token was genuinely one of ours but is no longer usable - expired or its session is gone. Discard it and re-authenticate. A plain 401 without that header means no (valid) credentials were presented at all.
• No cookies are involved in either direction.

Pre-authentication flows work naturally: e.g. a WebAuthn ceremony calls POST /api/auth/options (server stores the challenge in a fresh anonymous session -> response carries its token), then presents that token on POST /api/auth/verify; the login success response carries the rotated, authenticated token.

Configuration reference

Token format

The default strategy signs the claims with HMAC-SHA256, keyed by a derivation of kernel.secret (rotating the secret invalidates all outstanding tokens):

The MAC covers the expiry, so clients may read it (to refresh proactively) but cannot alter it. A leaked session-store key is not a usable credential - building a token requires the app secret.

Absolute lifetime and refresh

By default tokens live as long as their session (sliding idle expiry). Setting token.lifetime embeds a signed absolute expiry in every minted token, enforced before the session is ever touched. Mount the refresh endpoint to let clients extend their stay:

POST /api/refresh with a valid token returns {token, expires_in} - an additional token for the same session with a fresh expiry. Notes:

• Refresh does not revoke the previous token; it remains valid until its own expiry. Revocation is what logout/session invalidation is for: the session dies, killing every outstanding token at once. (See "Enhancement patterns" for stricter semantics.)
• Concurrent refreshes from racing client threads are harmless.
• Sessions have no built-in cap on total age under active refresh.

Logout

Symfony's plain logout: firewall config works as-is - the session is invalidated, so every token for it dies instantly, and no stray cookie headers leak. logout.json_response: true answers 204 No Content instead of the default redirect; your own LogoutEvent listeners can still replace the response.

Impersonation (switch-user)

Do not enable Symfony's switch_user firewall option. Mount the endpoints instead - nothing impersonation-related exists unless you do:

POST with {"identifier": "<user>"} enters impersonation (requires switch_user.role; the impersonation token carries the target's roles, and IS_IMPERSONATOR and friends behave as usual); DELETE exits. Responses: 400 bad body, 403 missing role or listener veto, 404 unknown target, 409 already/not impersonating.

The token also carries ROLE_PREVIOUS_ADMIN on Symfony 6.4 only, matching what that version's built-in switch_user did. Symfony 7.0 dropped the convention on both sides at once - SwitchUserListener stopped granting the role, and ContextListener stopped expecting it - so on 7.0+ the role must be absent or the token's roles no longer match the reloaded user's and the session is deauthenticated on the next request. Check IS_IMPERSONATOR rather than the role in your own voters; it works on every supported version.

The default grant_previous_admin_role: auto reads http-kernel's version as a stand-in for security-http's, which is right for any install that keeps its Symfony components on one major. Set it to true or false if yours does not - security-http 6.4 with http-kernel ^7.0 is the pairing auto gets wrong (it needs true). The symptom of a wrong value is impersonation that returns 200 and then 401s on every request after it.

Guard listeners subscribe to the bundle's ImpersonationEnteredEvent / ImpersonationExitedEvent - each fires only for its direction, so no request-parameter sniffing - and veto by throwing AccessDeniedException. Symfony's SwitchUserEvent is also dispatched for existing listeners. The target is resolved through your user provider (the autowiring alias when exactly one is configured; multi-provider apps rebind the controller's provider argument).

Exiting dispatches a pair of events, because it is two pieces of work under two identities. ImpersonationExitedEvent fires while the impersonation token is still in place - the current user is the one being put down, so this is where work about the borrowed identity goes. ImpersonatorResumedEvent fires once the original token is back, for work about the impersonator; a listener there can ask the token storage who is acting and get the right answer.

To end an impersonation without waiting to be asked - a deadline of your own having passed, say - inject ImpersonationManager:

It returns the user now acting again, or null if nothing was being impersonated, and produces the same events in the same order as the endpoint. A forced exit cannot be vetoed: AccessDeniedException from a listener stands only for a requested exit, and listeners that guard exits should check $event->isVetoable() before throwing.

Stale-token signalling

When a presented token verifies as ours but is no longer usable, three signals fire:

• request attribute StaleTokenDetector::STALE_ATTRIBUTE - computed before your entry point runs, so it can distinguish "session expired, log in again" from "no credentials";
• WWW-Authenticate: Bearer error="invalid_token" appended to the 401 (disable with stale_token.www_authenticate: false);
• a StaleSessionTokenEvent for telemetry, once per request.

CSRF

Bearer-carried sessions have no ambient credential, so classic CSRF does not apply; by default the bundle bypasses CSRF validation on bridged firewalls (form-login, logout, and app-level checks alike) while leaving the rest of the app untouched. Set csrf_bypass: false to keep validation.

Custom token strategies

Alias LocksyK\ApiSessionBundle\Token\TokenStrategyInterface to your own service to change the token encoding - e.g. authenticated encryption that hides the session id from the client entirely:

Security contract: every claim - session id and expiry - must be integrity-protected. The bridge enforces expiry from the decoded claims alone; an encoding that lets a client alter them without detection is exploitable by construction, and that responsibility sits with the implementation. Strategies must be able to mint for any session id the session layer chooses (non-invertible mappings are unsupported).

Enhancement patterns: revocation

Two events form the extension surface for stricter token semantics:

• VerifySessionTokenEvent - dispatched before the firewall for a presented token whose session is live; call revoke(?reason) to reject it into the stale-token signalling. The session record is preserved (newer tokens may share it); invalidate it yourself for a full kill. Dispatched only when listened to - registering a listener makes the bridge start sessions eagerly on token-presenting requests.
• SessionTokenMintedEvent - every mint, with the new token's claims and a reason (anonymous / login / refresh), for stamping.

Reference implementations (copy them from the test suite; the stamped fields are ordinary app-owned session data):

• Early revocation after refresh - tests/Functional/Fixture/RevokeSupersededTokensListener.php: superseded tokens die a grace period after a refresh instead of living to their own expiry.
• Hard session-age cap - tests/Functional/Fixture/SessionAgeCapListener.php: the session dies N seconds after login no matter how often it refreshes; the pre-firewall guard means refresh can't extend past the cap.
• Mint-policy tripwire - tests/Functional/Fixture/UnexpectedTokenMintListener.php: an app that returns tokens in JSON bodies on known endpoints 500s if a token is ever minted on any other route, catching stray session creation (e.g. a per-request authenticator persisting a session on an arbitrary route) before clients silently lose tokens they never saw. Encodes the allowlist gotchas: login mints twice, logout's response advertises a fresh anonymous token, stale-token 401s mint replacements anywhere (skipped via the stale attribute), and the throw happens once per request so the error response can render.

Testing your app against the bundle

BrowserKit's loginUser() does not work on a bridged firewall - it plants a session cookie, which the bridge deliberately ignores, so API requests stay unauthenticated with no error to point at the cause. Functional tests must log in through the real path instead, so the token contract (authenticator -> session migration -> token advertisement) is exercised rather than bypassed.

The bundle ships a ready-made authenticator for exactly that: LocksyK\ApiSessionBundle\Test\TestLoginAuthenticator answers POST /api/test/login with {"email": "<identifier>"} and logs that user in through the full stack. It is not registered by the bundle's DI - it is test-only tooling, and your app wires it up itself (it refuses to run unless the kernel environment is test, and the route only exists there anyway). Three snippets:

A test then logs in and captures the advertised token:

The constructor optionally takes the path, the environment name the authenticator is active in (default test), and the JSON key holding the user identifier (default email).

License

GNU General Public License, version 2 only (GPL-2.0-only). See LICENSE.