Skip to content

Session Management

📌 Current POC Implementation Status (as of 2026-04-16)

Live in the POC: - Server-side sessions table persists every login with userId, auth0SessionId, ipAddress, userAgent, parsed device fingerprint (device / browser / OS in JSONB metadata), issuedAt, expiresAt, and auto-updated lastSeenAt. - SessionService creates sessions on Auth0 callback, extends them on active use, and terminates them on logout. - Backend endpoints: GET /api/v1/auth/sessions, DELETE /api/v1/auth/sessions/:id, DELETE /api/v1/auth/sessions (terminate all others). - Frontend page /account/sessions (via SessionList.tsx) lists the user's active sessions with device info, last-seen timestamp, and a termination action.

Not yet implemented (Drop 1 Beta onwards): - Auth0 session-timeout configuration UI for platform admins (US-UM-49) - Role-specific timeout policies - Admin force-terminate with audit-log entry (depends on AuditLog write path — see Task 24) - Suspicious-activity alerts and security-event stream

This section takes precedence over specific acceptance criteria below when they conflict with current reality.

Feature Overview

Manages user sessions with appropriate timeout and security controls through Auth0 and the local application to protect user accounts from unauthorized access while maintaining a good user experience.

User Stories

US-UM-49: Configure Auth0 Session Timeout Policies

As a platform administrator, I want to configure Auth0 session timeout policies, So that inactive sessions are automatically terminated to protect user accounts.

Acceptance Criteria: - Given I am logged in as a platform administrator - When I navigate to the security policy settings - Then I should see options to configure Auth0 session timeout policies - And I should be able to set: - Idle session timeout duration in Auth0 - Absolute session timeout duration (maximum session length) - Token expiration settings - Different timeout policies for different user roles - Refresh token rotation policies - When I update these policies - Then: - The changes should be applied to Auth0 tenant settings - The local application should be updated to respect Auth0 token lifetimes - The changes should be applied organization-wide - And the changes should be logged for audit purposes in both systems - And existing sessions should be updated according to the new policies

US-UM-50: Manage Active Auth0 Session

As a staffing company user, I want to be notified when my Auth0 session is about to expire, So that I can extend it if I'm still actively using the platform.

Acceptance Criteria: - Given I am logged into the platform through Auth0 - When my session is approaching the idle timeout limit - Then I should receive a notification warning me about the impending timeout - And the notification should appear at least 2 minutes before the timeout occurs - When I interact with the notification to extend my session - Then: - The application should request a new token from Auth0 - My session should be renewed in both Auth0 and the local application - When I ignore the notification - Then: - My Auth0 token should expire after the timeout period - The local application should detect the expired token - I should be redirected to the Auth0 login page - And I should see a message explaining that my session expired due to inactivity

US-UM-51: View and Manage Active Auth0 Sessions

As a staffing company user, I want to view and manage all my active Auth0 sessions across devices, So that I can ensure no unauthorized access is occurring with my account.

Acceptance Criteria: - Given I am logged into the platform through Auth0 - When I navigate to my security settings - Then I should see a list of all my active sessions from Auth0 - And for each session, I should see: - Device type and browser - IP address - Location (approximate, based on IP) - Login time - Last activity time - Authentication method used (password, passkey, social login) - When I select to manage my sessions - Then I should be able to: - View detailed session information - Terminate any session individually - Terminate all sessions except my current one - When I terminate a session - Then: - The session should be immediately invalidated in Auth0 - The corresponding local session should be terminated - Auth0 tokens for that session should be revoked - And the action should be logged for security audit purposes in both systems

US-UM-52: Implement Secure Auth0 Token Management

As a platform administrator, I want to ensure secure Auth0 token management, So that user sessions are protected from hijacking and other attacks.

Acceptance Criteria: - Given the platform is handling user sessions through Auth0 - Then Auth0 tokens should be: - Securely stored in memory (not localStorage) - Transmitted only over HTTPS - Validated for proper signature and claims - Refreshed securely using refresh tokens - Revoked upon logout - And the local application should implement: - Proper token validation - Secure token storage - Protection against Cross-Site Request Forgery (CSRF) - Protection against XSS attacks - Token refresh mechanisms - And Auth0 should be configured for: - Proper token signing algorithms (RS256) - Appropriate token lifetimes - Audience and issuer validation - Refresh token rotation - And all token-related security events should be logged for audit purposes in both systems

US-UM-53: Control Concurrent Auth0 Sessions

As a platform administrator, I want to control the number of concurrent Auth0 sessions allowed per user, So that I can limit the risk of unauthorized access.

Acceptance Criteria: - Given I am logged in as a platform administrator - When I navigate to the security policy settings - Then I should see options to configure concurrent session policies - And I should be able to: - Set the maximum number of concurrent sessions per user in Auth0 - Choose the behavior when the limit is reached (terminate oldest session or prevent new login) - Set different limits for different user roles - Configure device-specific policies - When I update these policies - Then: - The changes should be applied to Auth0 tenant settings - The local application should be updated to respect these policies - When a user reaches their concurrent session limit - Then: - Auth0 should either terminate their oldest session or prevent the new login - The local application should respect this decision - The user should receive a notification explaining the situation - And the event should be logged for security audit purposes in both systems

US-UM-54: Force Auth0 Session Termination

As a staffing company administrator, I want to force termination of user Auth0 sessions when necessary, So that I can respond to security incidents or enforce immediate logout.

Acceptance Criteria: - Given I am logged in as a staffing company administrator - When I navigate to the user management section - Then I should see a list of all users - When I select a user - Then I should see an option to view their active Auth0 sessions - And I should be able to terminate any or all of their sessions - When I terminate a session - Then: - The session should be immediately invalidated in Auth0 - The corresponding tokens should be revoked - The local application session should be terminated - And the user should be logged out from that session - And the user should receive a notification explaining that their session was terminated by an administrator - And the action should be logged for security audit purposes in both systems

US-UM-55: Monitor Auth0 Session Security Events

As a platform administrator, I want to monitor Auth0 session security events, So that I can identify potential security issues and unauthorized access attempts.

Acceptance Criteria: - Given I am logged in as a platform administrator - When I navigate to the security monitoring dashboard - Then I should see analytics on Auth0 session events including: - Login successes and failures - Session creations and terminations - Token refreshes - Suspicious activity patterns - Geographic anomalies - And I should see alerts for potential security issues such as: - Multiple failed login attempts - Logins from unusual locations - Rapid session switching across different locations - Token reuse attempts - And I should be able to filter events by date range, user, and event type - And I should be able to set up custom alerts for specific session-related events - And I should be able to export reports for compliance purposes

Dependencies

  • Auth0 tenant setup and configuration
  • Auth0 Management API integration
  • Integration between local database and Auth0
  • Auth0 Logs API integration for monitoring