Milestone: M2 — Platform and Client Admin | SOW Reference: FR7 (also feeds M2-07 IdP/MFA and M2-06 self-service) | Requirement Clarity: ✅ Clear | Dev Status: 🟡 Partially prototyped — Phase 1 (basic Auth0 login/session) done; Phase 2 (MFA/passkey) per this doc's own phasing is not Moved from docs/requirements/tasks/auth0-login-session-management.md — this is the original detailed implementation breakdown, unmodified below. This doc's "Phase 2" section is the source for M2-07 and M2-08.

M2-10 Auth0 Login and Session Management Tasks

This document breaks down the implementation tasks for Auth0 login and session management features based on the user stories, taking into account the existing entities and code.

Implementation Strategy

The implementation will follow a phased approach: 1. Phase 1: Basic Auth0 authentication without MFA for the initial period 2. Phase 2: Add MFA and passkey support as optional features 3. Phase 3: Implement advanced session management features

Current Implementation Status

The project already has a foundation for Auth0 integration:

1. Entity Models:
2. User entity has auth0Id field for linking with Auth0 users
3. Session entity has fields for tracking sessions, including auth0SessionId
4. MfaMethod entity supports different MFA providers, including Auth0

5. Passkey entity has fields for Auth0 WebAuthn credential IDs

6. Authentication:

7. JWT Strategy is implemented for validating Auth0 tokens
8. Auth0 Management API integration is set up in AuthService
9. User validation and profile retrieval from Auth0 is implemented
10. Fallback mechanisms for Auth0 token exchange failures

11. Temporary user and session creation for error scenarios

12. User Management:

13. Methods for finding users by Auth0 ID
14. Methods for updating user information
15. Methods for retrieving Auth0 roles and permissions
16. Robust error handling for user creation and updates

Backend Tasks

API Endpoints

Auth0 Login Flow

• Implement /api/auth/login endpoint
• Create endpoint to initiate Auth0 login flow
• Generate state parameter for CSRF protection
• Redirect to Auth0 authorization URL
• Implement /authorize endpoint
• Handle Auth0 callback after successful authentication
• Validate state parameter to prevent CSRF attacks
• Exchange authorization code for tokens
• Create or update local user record based on Auth0 profile
• Create new session record in the database
• Return tokens and user information

Session Management Endpoints

• Create /api/auth/sessions endpoints
• GET /api/auth/sessions - List all active sessions for current user
• DELETE /api/auth/sessions/:id - Terminate specific session
• DELETE /api/auth/sessions - Terminate all sessions except current
• Implement /api/auth/sessions/check endpoint
• Check if current session is valid and not expired
• Return time remaining until expiration
• Extend session if requested

Business Logic

Session Management

• Implement session tracking service
• Create methods to record new sessions when users log in
• Add functions to list active sessions for a user
• Implement methods to terminate sessions
• Add logic to update last activity timestamp
• Create methods to check session expiration
• Implement session cleanup job
• Create scheduled task to remove expired sessions
• Add logging for session cleanup activities

Auth0 Token Management

• Implement token refresh logic
• Create methods to refresh Auth0 tokens
• Add logic to handle token expiration
• Implement silent authentication for token refresh
• Implement token revocation
• Create methods to revoke Auth0 tokens on logout
• Add logic to handle token revocation failures

Frontend Tasks

UI Components

Authentication Components

• Create LoginButton component
• Implement click handler to redirect to Auth0 login page
• Add styling consistent with application design
• Include loading state during authentication
• Implement LogoutButton component
• Add confirmation dialog for logout
• Implement logout functionality with Auth0
• Handle post-logout navigation
• Create AuthStatus component
• Display current authentication status
• Show user profile information when logged in
• Include visual indicator for connection status

Session Management Components

• Implement SessionList component
• Create table/list view of active sessions
• Add device and location information display
• Include terminate session buttons
• Create SessionExpirationAlert component
• Implement countdown timer for session expiration
• Add session renewal functionality
• Include dismissible alert UI

API Calls

Auth0 Integration

• Implement Auth0 authentication hooks
• Create custom hook for Auth0 login/logout
• Add hook for session state synchronization
• Implement token refresh functionality
• Create API service for authentication
• Add methods to handle Auth0 tokens
• Implement functions to call authentication endpoints
• Create error handling for authentication failures

Session Management

• Implement session API service
• Create methods to fetch active sessions
• Add functions to terminate sessions
• Implement polling for session status updates

User Flows

Authentication Flow

• Implement login flow
• Create redirect to Auth0 login page
• Handle callback from Auth0
• Store authentication state in Redux
• Create logout flow
• Implement local state cleanup
• Add redirect to Auth0 logout endpoint
• Handle post-logout navigation
• Implement session renewal flow
• Add silent authentication for token refresh
• Create session timeout detection
• Implement automatic renewal when possible

Session Management Flow

• Create session listing page
• Implement UI for viewing active sessions
• Add filtering and sorting options
• Include session details display
• Implement session termination flow
• Add confirmation dialog for session termination
• Create success/error notifications
• Handle current session termination edge case

Dependencies & Assumptions

Prerequisites

• Auth0 tenant must be properly configured
• Environment variables for Auth0 must be set
• Database already has the required tables (User, Session, MfaMethod, Passkey)

Cross-team Needs

• UX team should provide mockups for login and session management screens
• Security team should review the authentication implementation
• DevOps team needs to configure Auth0 webhook endpoints

Phase 1 Implementation (Basic Auth0 Authentication)

For the initial period, we will implement basic authentication without MFA to avoid confusion:

Backend Tasks (Phase 1)

• Implement Auth0 login and callback endpoints
• Create session tracking for new logins
• Implement session listing and termination endpoints
• Add token refresh and revocation logic

Frontend Tasks (Phase 1)

• Create LoginButton and LogoutButton components
• Implement Auth0 authentication hooks
• Add protected route component
• Create basic session management UI

MFA and advanced session management features will be implemented in subsequent phases after users are comfortable with the basic authentication flow.

Recent Improvements

The following improvements have been made to the Auth0 login and session management implementation:

Backend Improvements

1. Robust Error Handling:
2. Added fallback mechanisms for Auth0 token exchange failures
3. Implemented error handling for user creation conflicts

4. Added error recovery for session creation issues

5. Session Management:

6. Enhanced session creation to handle database constraints
7. Improved session ID generation and validation
8. Added better logging for authentication and session errors

Frontend Improvements

1. Authentication Flow:
2. Fixed redirect issues after successful authentication
3. Improved handling of authentication state across components

4. Added proper session ID storage and retrieval

5. Login/Logout Functionality:

6. Enhanced login button with proper Auth0 parameters
7. Improved logout functionality with proper session termination

8. Added better error handling and user feedback

9. State Management:

10. Improved synchronization between Auth0 and Redux state
11. Enhanced session state management across components
12. Added better handling of authentication errors

These improvements ensure that users can successfully log in and access the dashboard, even when there are issues with the Auth0 service or database constraints.