AdminForth User Sessions plugin
Shows admin user their active sessions (one per browser they signed in from) and lets them revoke any of those sessions. Logging out revokes the session as well, so its auth token stops working immediately instead of staying valid until it expires.
Full documentation: adminforth.dev/docs/tutorial/Plugins/user-sessions
Installation
npm i @adminforth/user-sessions @adminforth/key-value-adapter-redis --save
import UserSessionsPlugin from '@adminforth/user-sessions';
import RedisKeyValueAdapter from '@adminforth/key-value-adapter-redis';
export const admin = new AdminForth({
...
globalPlugins: [
new UserSessionsPlugin({
keyValueAdapter: new RedisKeyValueAdapter({ redisUrl: process.env.REDIS_URL }),
}),
],
...
});
Sessions then appear under "Active sessions" in the user menu settings.
To let a privileged user see and revoke sessions of other users, add canManageOtherUsersSessions.
The same block then appears on the show page of the users resource:
new UserSessionsPlugin({
keyValueAdapter,
canManageOtherUsersSessions: async (adminUser) => adminUser.dbUser.role === 'superadmin',
})
Without this option, sessions of other users are not shown and can't be revoked by anybody.
How it works
- AdminForth puts a unique session id into every issued auth JWT.
auth.afterSessionCreatedhook stores<user pk>:<session id>in the key-value adapter, with the same expiration as the token, holdingip,country,user_agent,created_atandlast_used_at.auth.adminUserAuthorizehook checks that the session of the request is still stored, and refreshes itslast_used_at. A session which is not stored is rejected with 401.auth.beforeLogouthook and the revoke endpoints delete the stored session, and delete it once more 5 seconds later: a request running at that moment may have read the session just before and write it back while refreshinglast_used_at.
Because a missing record means "revoked", the store must outlive the app process: use Redis (or another shared, persistent adapter) in production. With an in-memory adapter every restart signs all users out. Installing the plugin also signs out everyone who was logged in before it.
Requests authorized without a session id — MCP api keys, or tokens issued before the plugin was installed — are left alone.
Options
| Option | Default | Description |
|---|---|---|
keyValueAdapter | required | Where active sessions are stored |
collection | adminforth-user-sessions | Collection (key prefix) used in the adapter |
countryHeader | CF-IPCountry | Header with two-letter country code set by your CDN. Empty string disables it |
canManageOtherUsersSessions | — | (adminUser) => Promise<boolean>. When it returns true, that user sees and can revoke sessions of other users on the users show page |
resolveCountry | — | ({ ip, headers }) => Promise<string | null>, called when the header did not tell the country |
lastUsedThrottleSeconds | 60 | How often last_used_at is refreshed, one adapter write per refresh |
The Device column shows the browser and OS parsed from the stored User-Agent (e.g.
Chrome 131 on macOS) with a desktop/mobile/tablet icon. The raw header is stored as it came, so
parsing always runs on the current plugin version.
Client IP is taken from adminforth.auth.getClientIp, so configure auth.clientIpHeader when
running behind a proxy — otherwise the IP is not trustworthy and is null for private addresses.
Development
pnpm i
# hooks this plugin uses are not released yet, so point it at a local adminforth checkout
# (every `pnpm i` resets this link back to the published package)
pnpm link ../../adminforth
pnpm test
pnpm build