strapi-plugin-magic-sessionmanager

v4.4.7

Published

22 days ago

Advanced Session Management for Strapi v5 - Track user sessions with IP geolocation, security scoring, and real-time monitoring

0High
0Medium
0Low

schero94

strapi strapi-plugin strapi-v5 sessions user-tracking login-logout activity-monitoring

Magic Session Manager 🔐

See who's logged into your Strapi app - and control their sessions!

Track logins, monitor active users, and secure your app with one simple plugin. No complicated setup required.

📸 What It Looks Like

Homepage Widget - Quick Stats at a Glance

On your Strapi homepage:

See online users instantly
Active in last 15/30 minutes
Total users count
Blocked users count
No need to navigate anywhere!

Main Dashboard - See All Active Sessions

Dashboard

What you see:

Who is logged in right now (green = online)
When they logged in
What device they're using
Their IP address and location
One-click session termination

Session Details Modal

Session Modal

Click any session to see:

Full device information
Browser and operating system
Complete session history
IP geolocation (Premium)
Security risk score (Premium)

Content Manager Integration

Session Info Panel

When viewing a user:

Sidebar shows their active sessions
Quick actions (terminate, block)
Offline/Online status indicator
No need to leave the page!

Settings Page

Settings 1

Easy configuration:

Session timeouts
Rate limiting
Email alerts
Webhook notifications
Geo-blocking rules

Settings 2

Advanced security:

Encryption key generator (one click!)
Country allow/block lists
VPN detection
Threat blocking

✨ What This Plugin Does

Simple Version

When users login:

Plugin saves who logged in, when, and from where
You can see them in the dashboard (see screenshot above)
You can force-logout anyone anytime

When users logout:

Plugin marks their session as "logged out"
They disappear from the active sessions list
Manual logout permanently blocks session reactivation (security feature)

Session Timeout vs Manual Logout:

Timeout: Session can be reactivated on next request (seamless UX)
Manual Logout: Session is permanently terminated (security-first)

While users are active:

Plugin updates their "last seen" time
You always know who's currently using your app

🚀 Quick Install

Step 1: Install

npm install strapi-plugin-magic-sessionmanager

Step 2: Enable Plugin

Add this to config/plugins.ts:

export default () => ({
  'magic-sessionmanager': {
    enabled: true,
  },
});

Step 3: Rebuild & Start

npm run build
npm run develop

Step 4: Open Dashboard

Go to Strapi Admin: http://localhost:1337/admin
Look in the left sidebar for "Sessions"
Click it!
You'll see the dashboard (like the screenshot above)

That's it! You're done!

🔐 Security Features (Optional)

Encryption Key (Recommended)

Your JWT tokens are encrypted before saving to database. Generate a key:

In Admin Panel:

Go to Sessions → Settings
Scroll to "JWT Encryption Key Generator"
Click "Generate Key"
Click "Copy for .env"
Paste into your .env file
Restart Strapi

Or generate manually:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Then add to .env:

SESSION_ENCRYPTION_KEY=your-key-here

Why? If someone hacks your database, they can't steal user sessions! 🔒

🎯 Main Features Explained Simply

1. See Who's Logged In

Dashboard Tab:

Shows all active users
Green badge = currently online
Gray badge = logged out
Click to see details

2. Force Logout Anyone

Need to kick someone out?

Find their session
Click "Terminate"
Done! They're logged out immediately

Even works if they have refresh tokens! (See below)

3. Session Details

Click any session to see:

When they logged in
Last time they did something
What browser/device they use
Their IP address
Location (if Premium)

4. Multiple Devices

Users can login from:

Desktop computer
Phone
Tablet
All at the same time!

Each login = separate session. You can see them all and logout each individually.

5. Auto-Cleanup

Inactive sessions are automatically cleaned up:

If user doesn't do anything for 15 minutes (configurable)
Session is marked as "inactive"
Keeps your database clean

🔒 Refresh Token Protection (Advanced)

The Problem (Without This Plugin)

Admin kicks out a user
   ↓
User has "refresh token"
   ↓
User gets new login token automatically
   ↓
User is back in! 😱

The Solution (With This Plugin)

Admin kicks out a user
   ↓
User tries to use refresh token
   ↓
Plugin blocks it! 🚫
   ↓
User MUST login again

How to enable:

Add to config/plugins.ts:

'users-permissions': {
  config: {
    jwtManagement: 'refresh',  // Enable refresh tokens
    sessions: {
      accessTokenLifespan: 3600,  // 1 hour
      maxRefreshTokenLifespan: 2592000,  // 30 days
    },
  },
}

What this does:

Users stay logged in longer (better experience)
But admins can still force-logout completely (better security)
Best of both worlds! ✅

🌍 Premium Features (Optional License)

IP Geolocation

See where users login from:

Country (with flag! 🇩🇪🇺🇸🇬🇧)
City
ISP Provider
Coordinates (for map)

Threat Detection

Automatically check if IP is:

VPN
Proxy
Known threat
Security score (0-100)

Auto-Blocking

Block logins from:

Specific countries
VPNs or proxies
Low security score IPs
Known threat IPs

Notifications

Get alerts when:

Suspicious login detected
VPN used
New location login
Send to Discord or Slack!

📧 Email Alerts Setup (Premium)

The Session Manager uses Strapi's Email Plugin to send notifications. You need to configure an email provider first.

Step 1: Install Email Provider

Choose one of these providers:

Option A: Nodemailer (Recommended)

npm install @strapi/provider-email-nodemailer

Option B: SendGrid

npm install @strapi/provider-email-sendgrid

Option C: Mailgun

npm install @strapi/provider-email-mailgun

Step 2: Configure Email Plugin

Add to config/plugins.ts:

export default () => ({
  // Email configuration
  email: {
    config: {
      provider: 'nodemailer',
      providerOptions: {
        host: process.env.SMTP_HOST || 'smtp.gmail.com',
        port: process.env.SMTP_PORT || 587,
        auth: {
          user: process.env.SMTP_USER,
          pass: process.env.SMTP_PASSWORD,
        },
      },
      settings: {
        defaultFrom: process.env.SMTP_DEFAULT_FROM || '[email protected]',
        defaultReplyTo: process.env.SMTP_DEFAULT_REPLY_TO || '[email protected]',
      },
    },
  },
  
  // Session Manager configuration
  'magic-sessionmanager': {
    enabled: true,
  },
});

Step 3: Add Environment Variables

Add to your .env file:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-app-password
[email protected]
[email protected]

For Gmail:

Use an App Password, not your regular password!

Step 4: Enable in Admin Panel

Go to Sessions → Settings
Scroll to "Email Notifications"
Toggle "Enable Email Alerts" to ON
Customize email templates (optional)
Click Save

Step 5: Test It

Trigger a suspicious login (e.g., use a VPN) and check if the email arrives!

Troubleshooting:

Check Strapi logs for email errors
Verify SMTP credentials are correct
Test SMTP connection with a tool like smtp-tester

📋 Content-API Endpoints (For Frontend/Apps)

All Content-API endpoints require a valid JWT token in the Authorization header. Users can only access their own sessions.

Get My Sessions

Returns all sessions for the authenticated user.

GET /api/magic-sessionmanager/my-sessions
Authorization: Bearer <JWT>

Response:

{
  "data": [
    {
      "id": 41,
      "documentId": "abc123xyz",
      "sessionId": "sess_m5k2h_8a3b1c2d_f9e8d7c6",
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36...",
      "loginTime": "2026-01-02T10:30:00.000Z",
      "lastActive": "2026-01-02T13:45:00.000Z",
      "logoutTime": null,
      "isActive": true,
      "deviceType": "desktop",
      "browserName": "Chrome 143",
      "osName": "macOS 10.15.7",
      "geoLocation": null,
      "securityScore": null,
      "isCurrentSession": true,
      "isTrulyActive": true,
      "minutesSinceActive": 2
    },
    {
      "id": 40,
      "documentId": "def456uvw",
      "sessionId": "sess_m5k1g_7b2a0c1d_e8d7c6b5",
      "ipAddress": "10.0.0.50",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)...",
      "loginTime": "2026-01-01T08:15:00.000Z",
      "lastActive": "2026-01-01T12:00:00.000Z",
      "logoutTime": null,
      "isActive": true,
      "deviceType": "mobile",
      "browserName": "Safari",
      "osName": "iOS 17",
      "geoLocation": null,
      "securityScore": null,
      "isCurrentSession": false,
      "isTrulyActive": false,
      "minutesSinceActive": 1545
    }
  ],
  "meta": {
    "count": 2,
    "active": 1
  }
}

Get Current Session

Returns only the session associated with the current JWT token.

GET /api/magic-sessionmanager/current-session
Authorization: Bearer <JWT>

Response:

{
  "data": {
    "id": 41,
    "documentId": "abc123xyz",
    "sessionId": "sess_m5k2h_8a3b1c2d_f9e8d7c6",
    "ipAddress": "192.168.1.100",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36...",
    "loginTime": "2026-01-02T10:30:00.000Z",
    "lastActive": "2026-01-02T13:45:00.000Z",
    "logoutTime": null,
    "isActive": true,
    "deviceType": "desktop",
    "browserName": "Chrome 143",
    "osName": "macOS 10.15.7",
    "geoLocation": null,
    "securityScore": null,
    "isCurrentSession": true,
    "isTrulyActive": true,
    "minutesSinceActive": 2
  }
}

Logout (Current Session)

Terminates only the current session.

POST /api/magic-sessionmanager/logout
Authorization: Bearer <JWT>

Response:

{
  "message": "Logged out successfully"
}

Logout All Devices

Terminates ALL sessions for the authenticated user (logs out everywhere).

POST /api/magic-sessionmanager/logout-all
Authorization: Bearer <JWT>

Response:

{
  "message": "Logged out from all devices successfully"
}

Terminate Specific Session

Terminates a specific session (not the current one). Useful for "Log out other devices".

DELETE /api/magic-sessionmanager/my-sessions/:sessionId
Authorization: Bearer <JWT>

Response:

{
  "message": "Session abc123xyz terminated successfully",
  "success": true
}

Error (trying to terminate current session):

{
  "error": {
    "status": 400,
    "message": "Cannot terminate current session. Use /logout instead."
  }
}

📋 Admin-API Endpoints (For Admin Panel)

These endpoints require admin authentication.

Get All Sessions

GET /magic-sessionmanager/sessions

Get Active Sessions Only

GET /magic-sessionmanager/sessions/active

Force Terminate Session

POST /magic-sessionmanager/sessions/:sessionId/terminate

Terminate All User Sessions

POST /magic-sessionmanager/user/:userId/terminate-all

Block/Unblock User

POST /magic-sessionmanager/user/:userId/toggle-block

Clean Inactive Sessions

POST /magic-sessionmanager/sessions/clean-inactive

⚙️ Settings You Can Change

In config/plugins.ts:

'magic-sessionmanager': {
  config: {
    // How often to update "last seen" (in milliseconds)
    lastSeenRateLimit: 30000,  // Default: 30 seconds
    
    // When to mark sessions inactive (in milliseconds)
    inactivityTimeout: 900000,  // Default: 15 minutes
  },
}

In Admin Panel (Settings Tab):

Email alerts on/off
Webhook URLs (Discord/Slack)
Countries to block/allow
VPN detection on/off
Generate encryption key

🐛 Common Problems & Fixes

I don't see the Sessions menu

Fix:

Make sure plugin is in config/plugins.ts
Run npm run build
Restart Strapi
Refresh browser (Cmd+Shift+R)

Sessions not being created

Fix:

Check Strapi logs for errors
Make sure users are logging in (not already logged in)
Check database is working

401 or 403 errors

Fix:

401 = Not logged in (need to login as admin)
403 = Not allowed (check you're admin, not regular user)

Database table "sessions" already exists

Fix:

This plugin uses magic_sessions table (not sessions)
If you see this error, another plugin is using that name
Our plugin automatically uses the correct name

💡 When To Use This Plugin

Perfect for:

Multi-tenant apps (see which tenant users are online)
E-commerce (track customer sessions)
Collaboration tools (show who's currently working)
Security-critical apps (force-logout compromised accounts)
Compliance requirements (session audit logs)

Not needed if:

Single-user app
No need to see who's logged in
No security requirements

🔧 How To Test It

Quick Manual Test

Login to your Strapi app (frontend or admin)
Go to Admin → Sessions
You should see your session!
Click "Terminate" on your session
Try to use the app → You're logged out!

With Postman

1. Login:

POST http://localhost:1337/api/auth/local
Body: { "identifier": "[email protected]", "password": "pass123" }

2. Check session created:

GET http://localhost:1337/magic-sessionmanager/sessions

3. Logout:

POST http://localhost:1337/api/auth/logout
Authorization: Bearer YOUR_JWT_TOKEN

Done!

📦 What Gets Installed

When you install this plugin, you get:

✅ Dashboard to see all sessions
✅ Session tracking (automatic)
✅ Force logout buttons
✅ Activity monitoring
✅ Encryption (secure)
✅ Multi-device support

Premium features require a license (free to generate):

🔒 IP Geolocation
🔒 Threat detection
🔒 Auto-blocking
🔒 Email/webhook alerts

🙋 FAQ

Q: Do I need to change my Strapi code?
A: No! Just install and enable the plugin.

Q: Will this break my existing logins?
A: No! It just tracks them, doesn't change them.

Q: Can users see each other's sessions?
A: No! Only admins can see all sessions. Users only see their own.

Q: What if I uninstall the plugin?
A: Sessions will stop being tracked. Everything else works normally.

Q: Does it slow down my app?
A: No! It has smart rate-limiting to prevent database spam.

Q: Can I customize the dashboard?
A: Not yet, but it's planned for future versions!

📚 Resources

NPM: https://www.npmjs.com/package/strapi-plugin-magic-sessionmanager
GitHub: https://github.com/Schero94/Magic-Sessionmanager
Report Bugs: https://github.com/Schero94/Magic-Sessionmanager/issues

📄 License

MIT License - Free to use for personal and commercial projects!

Important License Restriction

This plugin is free and open source, BUT:

⚠️ You CANNOT modify the license validation system

This means:

❌ Cannot remove license-guard.js
❌ Cannot bypass license activation
❌ Cannot disable license checks
❌ Cannot modify license-related endpoints

Why? The license system ensures:

Quality and ongoing support
Spam prevention
Usage analytics for improvements
Fair use tracking

What you CAN do:

✅ Use freely (personal & commercial)
✅ View and study source code
✅ Report issues and contribute
✅ Deploy in production without fees
✅ Integrate in your projects

See LICENSE and COPYRIGHT_NOTICE.txt for full terms.

🌐 Supported Languages

The admin interface is available in 5 languages:

🇬🇧 English - Default
🇩🇪 Deutsch - German
🇪🇸 Español - Spanish
🇫🇷 Français - French
🇵🇹 Português - Portuguese

Language automatically follows your Strapi admin interface setting.

Made for Strapi v5

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Magic Session Manager 🔐

📸 What It Looks Like

Homepage Widget - Quick Stats at a Glance

Main Dashboard - See All Active Sessions

Session Details Modal

Content Manager Integration

Settings Page

✨ What This Plugin Does

Simple Version

🚀 Quick Install

Step 1: Install

Step 2: Enable Plugin

Step 3: Rebuild & Start

Step 4: Open Dashboard

🔐 Security Features (Optional)

Encryption Key (Recommended)

🎯 Main Features Explained Simply

1. See Who's Logged In

2. Force Logout Anyone

3. Session Details

4. Multiple Devices

5. Auto-Cleanup

🔒 Refresh Token Protection (Advanced)

The Problem (Without This Plugin)

The Solution (With This Plugin)

🌍 Premium Features (Optional License)

IP Geolocation

Threat Detection

Auto-Blocking

Notifications

📧 Email Alerts Setup (Premium)

Step 1: Install Email Provider

Step 2: Configure Email Plugin

Step 3: Add Environment Variables

Step 4: Enable in Admin Panel

Step 5: Test It

📋 Content-API Endpoints (For Frontend/Apps)

Get My Sessions

Get Current Session

Logout (Current Session)

Logout All Devices

Terminate Specific Session

📋 Admin-API Endpoints (For Admin Panel)

Get All Sessions

Get Active Sessions Only

Force Terminate Session

Terminate All User Sessions

Block/Unblock User

Clean Inactive Sessions

⚙️ Settings You Can Change

🐛 Common Problems & Fixes

I don't see the Sessions menu

Sessions not being created

401 or 403 errors

Database table "sessions" already exists

💡 When To Use This Plugin

🔧 How To Test It

Quick Manual Test

With Postman

📦 What Gets Installed

🙋 FAQ

📚 Resources

📄 License

Important License Restriction

🌐 Supported Languages