Use Case 002: Trial User Login and Session Management

Overview

Property Value
Use Case ID UC-002
Use Case Name Trial User Login and Session Management
Module Identity Management - Session Management
Priority High
Status Implemented
Version 1.0
Last Updated January 30, 2026

Description

This use case describes the complete process of a trial user authenticating into the Riptide Application Manager platform, creating and managing active sessions, and handling session lifecycle including timeouts, concurrent session limits, and secure session termination. The system enforces session security policies, tracks user activity, and ensures trial users maintain valid, active sessions to access Riptide applications.

Actors

Actor Description Role
Trial User A registered trial account holder attempting to access applications Primary
System Application Manager platform Supporting
Riptide Application Target application requiring authentication Supporting
Session Monitor Background service managing session lifecycle Supporting
Administrator System admin monitoring sessions (optional) Secondary

Preconditions

  1. Trial user has successfully registered (UC-001 completed)
  2. Trial user has received login token via email
  3. Application Manager is running and accessible
  4. Identity database is operational
  5. User's trial has not expired
  6. Session configuration is properly set (timeout: 30 minutes, max sessions: 5)

Postconditions

Success Postconditions

  1. Active session created with unique session token
  2. Session record stored in database with creation timestamp
  3. User authenticated and redirected to application dashboard
  4. Session token returned to client for subsequent requests
  5. LastLoginAt timestamp updated on user record
  6. LoginCount incremented
  7. Activity logged in audit trail
  8. Session expiration scheduled (30 minutes from last activity)

Failure Postconditions

  1. No session created if authentication fails
  2. Failed login attempt logged for security monitoring
  3. Rate limiting applied if excessive failures detected
  4. Appropriate error message returned to user
  5. Existing sessions remain unaffected

Triggers

  • User navigates to login page
  • User submits login form with credentials
  • API client calls /api/v1/sessions/create POST endpoint
  • User clicks "Login" link from welcome email

Basic Flow (Happy Path)

sequenceDiagram actor User as Trial User participant Web as Web UI participant API as Application Manager API participant DB as Identity Database participant Cache as Session Cache participant App as Riptide Application participant Monitor as Session Monitor User->>Web: Navigate to login page Web->>User: Display login form User->>Web: Enter login token Web->>API: POST /api/v1/sessions/create API->>API: Validate request format API->>DB: Query trial user by login token DB->>API: User record found API->>API: Validate trial expiration API->>API: Check if user is active API->>DB: Count active sessions for user DB->>API: Current sessions: 3 (under limit of 5) API->>API: Generate secure session token (128 chars) API->>DB: Create session record DB->>API: Session created successfully API->>Cache: Store session token with user context Cache->>API: Session cached API->>DB: Update LastLoginAt and LoginCount DB->>API: User record updated API->>Web: 201 Created (session token, user info) Web->>Web: Store session token in secure cookie Web->>User: Redirect to dashboard Note over User,Monitor: User actively using application User->>App: Request application resource App->>API: Validate session token API->>Cache: Check session cache Cache->>API: Session found and valid API->>DB: Verify trial not expired DB->>API: Trial still active API->>App: Authentication confirmed App->>User: Grant resource access Note over Monitor: Session activity updates timestamp Monitor->>Monitor: Periodic check (every 5 minutes) Monitor->>DB: Query sessions idle > 30 minutes DB->>Monitor: List of idle sessions Monitor->>DB: Mark sessions as expired Monitor->>Cache: Remove expired sessions from cache

Detailed Steps

  1. User Initiates Login

    • User navigates to /login or application-specific login page
    • System displays login form requesting credentials

  2. User Provides Credentials

    • User enters login token (32-character alphanumeric from registration email)
    • Optional: User checks "Remember Me" checkbox (extends session to 7 days)
    • User clicks "Login" button

  3. System Validates Request

    • Check login token is provided and not empty
    • Validate token format (32 characters, alphanumeric)
    • Apply rate limiting check (max 5 failed attempts per 15 minutes per IP)

  4. System Authenticates User

    • Query Identity database for trial user by login token
    • Verify user record exists
    • Check IsActive = true
    • Validate trial has not expired: TrialExpirationDate > CurrentDateTime
    • Verify user is not locked out due to security violations

  5. System Checks Concurrent Session Limit

    • Query database for active sessions belonging to user
    • Count sessions where ExpiresAt > CurrentDateTime and IsExpired = false
    • Verify count is less than maximum (5 concurrent sessions)
    • If at limit, optionally terminate oldest session to allow new login

  6. System Creates Session

    • Generate unique session ID (GUID)
    • Generate secure session token (128-character alphanumeric using cryptographic RNG)
    • Calculate session expiration time:
      • Standard: CurrentDateTime + 30 minutes
      • Remember Me: CurrentDateTime + 7 days
    • Create session record in database with:
      • SessionId (GUID)
      • TrialUserId (foreign key)
      • SessionToken (indexed for fast lookup)
      • CreatedAt (UTC timestamp)
      • LastActivityAt (UTC timestamp, same as CreatedAt initially)
      • ExpiresAt (calculated expiration time)
      • IsExpired (false)
      • IpAddress (client IP for security tracking)
      • UserAgent (client browser/device info)

  7. System Caches Session

    • Store session token in Redis or memory cache
    • Include user ID, expiration time, and trial status
    • Set cache TTL to match session expiration
    • Enable fast session validation without database queries

  8. System Updates User Record

    • Set LastLoginAt = CurrentDateTime
    • Increment LoginCount
    • Log successful authentication in audit trail

  9. System Returns Session Token

    • Return 201 Created status
    • Include session token in response body
    • Include user details and trial information
    • Set secure HTTP-only cookie with session token
    • Set appropriate cookie flags: Secure, SameSite=Strict

  10. User Redirected to Dashboard

    • Web UI stores session token in secure cookie
    • User automatically redirected to application dashboard
    • Dashboard displays user info and available applications

  11. User Accesses Applications

    • User clicks on application link
    • Application validates session with Application Manager
    • Session token sent in Authorization header or cookie
    • User granted access to application features

  12. Session Activity Updates

    • Each authenticated request updates LastActivityAt timestamp
    • Session expiration time recalculated (sliding window)
    • Cache updated with new activity time

Alternative Flows

Alt Flow 1: Invalid Login Token

sequenceDiagram actor User as Trial User participant Web as Web UI participant API as Application Manager API participant DB as Identity Database participant Security as Security Monitor User->>Web: Enter invalid/incorrect token Web->>API: POST /api/v1/sessions/create API->>DB: Query user by token DB->>API: No user found API->>Security: Log failed login attempt Security->>Security: Check rate limit for IP alt Rate limit not exceeded API->>Web: 401 Unauthorized - Invalid credentials Web->>User: "Invalid login token. Please check your email." else Rate limit exceeded (5 attempts in 15 min) API->>Security: Record IP for temporary block API->>Web: 429 Too Many Requests Web->>User: "Too many failed attempts. Try again in 15 minutes." end

Steps:

  1. User submits login form with incorrect token
  2. System queries database, no matching user found (step 4)
  3. System logs failed authentication attempt with IP address and timestamp
  4. System checks rate limiting rules:
    • Count failed attempts from IP in last 15 minutes
    • If < 5 attempts: Allow retry
    • If >= 5 attempts: Return 429 Too Many Requests, block for 15 minutes
  5. Return 401 Unauthorized with message: "Invalid login token. Please check your email or request a new token."
  6. User can retry with correct token or request password reset

Alt Flow 2: Expired Trial

sequenceDiagram actor User as Trial User participant Web as Web UI participant API as Application Manager API participant DB as Identity Database User->>Web: Enter valid login token Web->>API: POST /api/v1/sessions/create API->>DB: Query user by token DB->>API: User found API->>API: Check trial expiration Note over API: TrialExpirationDate < CurrentDateTime API->>Web: 403 Forbidden - Trial expired Web->>User: Display trial expired message Note over User,Web: Show upgrade/renewal options User->>Web: Click "Extend Trial" or "Upgrade" Web->>User: Redirect to upgrade page or contact form

Steps:

  1. User authentication succeeds (step 4 completed)
  2. System checks trial expiration during step 4
  3. TrialExpirationDate <= CurrentDateTime (trial has expired)
  4. System returns 403 Forbidden status
  5. Response includes:
    • Error code: "TrialExpired"
    • Message: "Your trial period has ended on [date]"
    • TrialExpirationDate
    • Options: Contact support, upgrade to paid plan
  6. Web UI displays friendly message with next steps
  7. User can contact support or use self-service upgrade (if available)

Alt Flow 3: Concurrent Session Limit Reached

sequenceDiagram actor User as Trial User participant Web as Web UI participant API as Application Manager API participant DB as Identity Database User->>Web: Attempt to login Web->>API: POST /api/v1/sessions/create API->>DB: Authenticate user (success) API->>DB: Count active sessions DB->>API: Active sessions: 5 (at limit) alt Strict enforcement API->>Web: 409 Conflict - Max sessions reached Web->>User: "Maximum concurrent sessions (5) reached" Note over User,Web: Display list of active sessions User->>Web: Terminate specific session Web->>API: DELETE /api/v1/sessions/{sessionId} API->>DB: Mark session as expired Web->>User: Session terminated, retry login else Automatic termination of oldest API->>DB: Query oldest session by CreatedAt DB->>API: Oldest session details API->>DB: Mark oldest session as expired API->>API: Proceed with new session creation API->>Web: 201 Created (with warning message) Web->>User: Login successful + "Oldest session terminated" end

Steps:

  1. User attempts to create 6th concurrent session
  2. System counts active sessions during step 5
  3. Session count = 5 (maximum allowed)
  4. System applies configured policy:
    • Strict Policy: Return 409 Conflict with error message listing active sessions
    • Auto-Terminate Policy: Terminate oldest session and proceed
  5. If strict:
    • User shown list of active sessions with creation times and device info
    • User can manually terminate a session via API or UI
    • User retries login after terminating a session
  6. If auto-terminate:
    • System finds oldest session by CreatedAt timestamp
    • System marks oldest session as expired
    • System proceeds with new session creation
    • User notified that oldest session was terminated

Alt Flow 4: Session Timeout (Idle Session)

sequenceDiagram actor User as Trial User participant App as Riptide Application participant API as Application Manager API participant DB as Identity Database participant Cache as Session Cache participant Monitor as Session Monitor Note over User,App: User idle for 30+ minutes Monitor->>Monitor: Periodic cleanup job runs Monitor->>DB: Query sessions idle > 30 minutes DB->>Monitor: Session XYZ idle for 35 minutes Monitor->>DB: UPDATE session SET IsExpired=true Monitor->>Cache: Remove session from cache Note over User: User returns and attempts action User->>App: Request resource (with expired session token) App->>API: Validate session token API->>Cache: Check cache for session Cache->>API: Session not in cache API->>DB: Query session by token DB->>API: Session found but IsExpired=true API->>App: 401 Unauthorized - Session expired App->>User: Redirect to login with message User->>App: See "Session expired. Please login again." App->>User: Show login form

Steps:

  1. User logged in and active (session created)
  2. User becomes idle (no requests for 30+ minutes)
  3. LastActivityAt timestamp not updated
  4. Background session monitor runs periodic check (every 5 minutes)
  5. Monitor queries: SELECT * FROM Sessions WHERE LastActivityAt < (NOW() - 30 minutes) AND IsExpired = false
  6. Monitor finds idle session(s)
  7. Monitor updates: UPDATE Sessions SET IsExpired = true WHERE SessionId = ?
  8. Monitor removes session from cache
  9. User returns and attempts to access application
  10. Application validates session token with API
  11. API checks cache (miss) then database
  12. Session found but IsExpired = true
  13. API returns 401 Unauthorized with error: "SessionExpired"
  14. Application redirects user to login page with message: "Your session has expired due to inactivity. Please login again."

Alt Flow 5: User Logs Out (Explicit Session Termination)

sequenceDiagram actor User as Trial User participant Web as Web UI participant API as Application Manager API participant DB as Identity Database participant Cache as Session Cache User->>Web: Click "Logout" button Web->>API: POST /api/v1/sessions/terminate Note over Web,API: Request includes current session token API->>DB: Query session by token DB->>API: Session found and active API->>DB: UPDATE session SET IsExpired=true, TerminatedAt=NOW() DB->>API: Session terminated API->>Cache: Remove session from cache Cache->>API: Session removed API->>Web: 200 OK - Session terminated Web->>Web: Clear session cookie Web->>Web: Clear local storage Web->>User: Redirect to login page User->>Web: See "You have been logged out successfully"

Steps:

  1. User clicks "Logout" button in application UI
  2. Web UI sends POST request to /api/v1/sessions/terminate
  3. Request includes current session token in Authorization header or cookie
  4. System queries session by token
  5. System validates session exists and belongs to authenticated user
  6. System updates session record:
    • IsExpired = true
    • TerminatedAt = CurrentDateTime
    • Optional: TerminationReason = "UserLogout"
  7. System removes session from cache
  8. System returns 200 OK status
  9. Web UI clears session cookie
  10. Web UI clears any cached user data from local storage
  11. User redirected to login page with success message: "You have been logged out successfully"

Alt Flow 6: Inactive User Account

flowchart TD A[User attempts login] --> B{Check IsActive flag} B -->|IsActive = false| C[Return 403 Forbidden] B -->|IsActive = true| D[Continue authentication] C --> E{Check deactivation reason} E -->|Admin deactivated| F[Show: Account deactivated by admin] E -->|Security violation| G[Show: Account locked for security] E -->|Terms violation| H[Show: Account suspended] F --> I[Provide support contact] G --> I H --> I

Steps:

  1. User submits valid login token
  2. System finds user record in database
  3. System checks IsActive flag during step 4
  4. IsActive = false (account deactivated)
  5. System returns 403 Forbidden status
  6. Response includes:
    • Error code: "AccountInactive"
    • Message based on reason: "Your account has been deactivated. Contact support for assistance."
    • Support contact information
  7. User cannot create session until account is reactivated by administrator

Alt Flow 7: Remember Me Functionality

sequenceDiagram actor User as Trial User participant Web as Web UI participant API as Application Manager API participant DB as Identity Database User->>Web: Check "Remember Me" checkbox User->>Web: Submit login form Web->>API: POST /api/v1/sessions/create {rememberMe: true} API->>API: Authenticate user (success) API->>API: Calculate extended expiration Note over API: ExpiresAt = CurrentDateTime + 7 days API->>DB: Create session with extended expiration API->>Web: 201 Created (session token) Web->>Web: Set cookie with 7-day expiration Web->>User: Login successful Note over User,Web: User closes browser and returns days later User->>Web: Navigate to application Web->>Web: Session cookie still valid Web->>API: Validate session token API->>DB: Check session expiration DB->>API: Session still valid (within 7 days) API->>Web: Session valid Web->>User: User remains logged in

Steps:

  1. User checks "Remember Me" checkbox on login form
  2. Web UI includes rememberMe: true in session creation request
  3. System creates session with extended expiration (7 days instead of 30 minutes)
  4. System sets RememberMe = true flag on session record
  5. Web UI sets session cookie with 7-day expiration
  6. User can close browser and return within 7 days without re-authenticating
  7. Session remains subject to trial expiration limits
  8. Security note: Remember Me sessions still expire if trial ends

Business Rules

Rule ID Description Enforcement
BR-001 Maximum 5 concurrent active sessions per trial user Session creation validation
BR-002 Session timeout after 30 minutes of inactivity (standard mode) Background monitor service
BR-003 Extended session timeout of 7 days for "Remember Me" mode Session creation logic
BR-004 Session tokens must be 128 alphanumeric characters Token generation logic
BR-005 Session tokens must be cryptographically random and unique Token generation using RNG
BR-006 Failed login attempts limited to 5 per IP address per 15 minutes Rate limiting middleware
BR-007 Session validation must check trial expiration status Every session validation call
BR-008 Expired sessions automatically cleaned up after 7 days Scheduled cleanup job
BR-009 Session activity timestamp updated on every authenticated request API middleware
BR-010 Sessions cannot be created for inactive (IsActive=false) users Authentication validation

Data Requirements

Note: For complete TrialUser data model including inheritance structure, see UC-001 Data Requirements section.

Session Record

{
  "SessionId": "uuid-v4",
  "TrialUserId": "uuid-v4 (foreign key)",
  "SessionToken": "string (128 chars, alphanumeric, indexed)",
  "CreatedAt": "datetime (UTC)",
  "LastActivityAt": "datetime (UTC)",
  "ExpiresAt": "datetime (UTC)",
  "IsExpired": "boolean (default: false)",
  "IsRememberMe": "boolean (default: false)",
  "IpAddress": "string (client IP, max 45 chars for IPv6)",
  "UserAgent": "string (browser/device info, max 500 chars)",
  "TerminatedAt": "datetime (UTC, nullable)",
  "TerminationReason": "string (nullable: UserLogout, Timeout, AdminTerminated, MaxSessionsReached)"
}

Session Validation Request

{
  "sessionToken": "string (128 chars, required)"
}

Session Validation Response

{
  "isValid": "boolean",
  "userId": "uuid-v4 (if valid)",
  "email": "string (if valid)",
  "trialExpiresAt": "datetime (UTC, if valid)",
  "sessionExpiresAt": "datetime (UTC, if valid)",
  "error": "string (if invalid: SessionExpired, TrialExpired, SessionNotFound, UserInactive)"
}

Session Cache Entry (Redis)

{
  "key": "session:{{sessionToken}}",
  "value": {
    "userId": "uuid-v4",
    "email": "string",
    "trialExpiresAt": "datetime",
    "sessionExpiresAt": "datetime",
    "isActive": "boolean"
  },
  "ttl": "1800 seconds (30 min) or 604800 seconds (7 days)"
}

User Interface

Login Form

┌─────────────────────────────────────────────────────┐
│  Welcome Back to Riptide                            │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Login to Your Trial Account                        │
│                                                     │
│  Login Token *                                      │
│  ┌─────────────────────────────────────────────┐   │
│  │ Enter your 32-character login token         │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ☐ Remember me for 7 days                           │
│                                                     │
│  ┌─────────────────────┐                           │
│  │       Login          │                          │
│  └─────────────────────┘                           │
│                                                     │
│  Don't have an account? [Sign up for free trial]   │
│  Lost your token? [Request new token]               │
│                                                     │
│  🔒 Secure login with encrypted connection          │
└─────────────────────────────────────────────────────┘

Dashboard After Login

┌─────────────────────────────────────────────────────┐
│  Riptide Platform                    [Logout] ⚙️   │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Welcome back, John Doe! 👋                         │
│                                                     │
│  📊 Trial Status                                    │
│  ┌─────────────────────────────────────────────┐   │
│  │ ⏰ 23 days remaining                         │   │
│  │ 📅 Expires: February 22, 2026                │   │
│  │ 🎯 [Upgrade to Full Access]                  │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  🚀 Your Applications                               │
│  ┌─────────────────────────────────────────────┐   │
│  │ 💰 Fee Manager              [Launch]         │   │
│  │    Last accessed: 2 hours ago                │   │
│  ├─────────────────────────────────────────────┤   │
│  │ 💎 Value Manager            [Launch]         │   │
│  │    Last accessed: Yesterday                  │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  🔐 Active Sessions (3/5)                           │
│  • Chrome on macOS (current)                        │
│  • Firefox on Windows (2 hours ago) [Terminate]    │
│  • Mobile Safari on iPhone (1 day ago) [Terminate] │
│                                                     │
│  📚 [Getting Started Guide] [API Documentation]     │
└─────────────────────────────────────────────────────┘

Session Expired Message

┌─────────────────────────────────────────────────────┐
│  ⏰ Session Expired                                  │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Your session has expired due to inactivity.        │
│  For your security, you need to login again.        │
│                                                     │
│  Session Duration: 30 minutes                       │
│  Idle Time: 35 minutes                              │
│                                                     │
│  ┌─────────────────────┐                           │
│  │   Login Again        │                          │
│  └─────────────────────┘                           │
│                                                     │
│  💡 Tip: Check "Remember me" to stay logged in      │
│     for up to 7 days.                               │
└─────────────────────────────────────────────────────┘

Max Sessions Reached

┌─────────────────────────────────────────────────────┐
│  ⚠️ Maximum Sessions Reached                        │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  You have reached the maximum number of active      │
│  sessions (5). Please terminate a session below     │
│  to login from this device.                         │
│                                                     │
│  Active Sessions:                                   │
│  ┌─────────────────────────────────────────────┐   │
│  │ 🖥️  Chrome on macOS                          │   │
│  │     Created: 3 hours ago                     │   │
│  │     IP: 192.168.1.100                        │   │
│  │     [Terminate]                              │   │
│  ├─────────────────────────────────────────────┤   │
│  │ 🦊 Firefox on Windows                        │   │
│  │     Created: 5 hours ago                     │   │
│  │     IP: 192.168.1.101                        │   │
│  │     [Terminate]                              │   │
│  ├─────────────────────────────────────────────┤   │
│  │ 📱 Safari on iPhone                          │   │
│  │     Created: 1 day ago                       │   │
│  │     IP: 10.0.0.50                            │   │
│  │     [Terminate]                              │   │
│  ├─────────────────────────────────────────────┤   │
│  │ 🖥️  Chrome on Linux                          │   │
│  │     Created: 2 days ago                      │   │
│  │     IP: 172.16.0.20                          │   │
│  │     [Terminate]                              │   │
│  ├─────────────────────────────────────────────┤   │
│  │ 💻 Edge on Windows                           │   │
│  │     Created: 3 days ago                      │   │
│  │     IP: 192.168.1.105                        │   │
│  │     [Terminate]                              │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  [Cancel]                                           │
└─────────────────────────────────────────────────────┘

API Endpoints

Create Session (Login)

Endpoint: POST /api/v1/sessions/create

Authentication: None (public endpoint, requires login token)

Request Body:

{
  "loginToken": "abc123xyz789abc123xyz789abc12345",
  "rememberMe": false
}

Success Response: 201 Created

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionToken": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6A7B8C9D0E1F2G3H4I5J6K7L8M9N0O1P2Q3R4S5T6U7V8W9X0Y1Z2a3b4c5d6e7f8g9h0i1j2k3l4",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "companyName": "Acme Corporation",
    "trialExpiresAt": "2026-03-01T10:30:00Z",
    "isActive": true,
    "daysRemaining": 23
  },
  "session": {
    "createdAt": "2026-01-30T14:25:00Z",
    "expiresAt": "2026-01-30T14:55:00Z",
    "isRememberMe": false
  },
  "applications": [
    {
      "applicationId": "app-id-fee-manager",
      "applicationName": "Fee Manager",
      "applicationUrl": "https://fee-manager.riptide.example.com"
    },
    {
      "applicationId": "app-id-value-manager",
      "applicationName": "Value Manager",
      "applicationUrl": "https://value-manager.riptide.example.com"
    }
  ],
  "message": "Login successful. Welcome back!"
}

Error Responses:

401 Unauthorized - Invalid credentials

{
  "error": "InvalidCredentials",
  "message": "Invalid login token. Please check your email or request a new token.",
  "requestId": "req-123456"
}

403 Forbidden - Trial expired

{
  "error": "TrialExpired",
  "message": "Your trial period ended on March 1, 2026. Contact support to extend or upgrade.",
  "trialExpirationDate": "2026-03-01T10:30:00Z",
  "supportEmail": "support@riptide.example.com"
}

403 Forbidden - Account inactive

{
  "error": "AccountInactive",
  "message": "Your account has been deactivated. Contact support for assistance.",
  "supportEmail": "support@riptide.example.com"
}

409 Conflict - Max sessions reached

{
  "error": "MaxSessionsReached",
  "message": "Maximum concurrent sessions (5) reached. Please terminate an existing session.",
  "maxSessions": 5,
  "activeSessions": [
    {
      "sessionId": "session-1",
      "createdAt": "2026-01-30T11:00:00Z",
      "lastActivityAt": "2026-01-30T14:00:00Z",
      "ipAddress": "192.168.1.100",
      "userAgent": "Chrome/120.0 (macOS)"
    }
  ]
}

429 Too Many Requests - Rate limit exceeded

{
  "error": "RateLimitExceeded",
  "message": "Too many failed login attempts. Please try again in 15 minutes.",
  "retryAfter": 900,
  "requestId": "req-123456"
}

Validate Session

Endpoint: POST /api/v1/sessions/validate

Authentication: Session token (in Authorization header or cookie)

Request Body:

{
  "sessionToken": "a1b2c3d4...x0y1z2a3b4c5d6e7f8g9h0i1j2k3l4"
}

Success Response: 200 OK

{
  "isValid": true,
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "email": "john.doe@example.com",
  "fullName": "John Doe",
  "trialExpiresAt": "2026-03-01T10:30:00Z",
  "sessionExpiresAt": "2026-01-30T14:55:00Z",
  "lastActivityAt": "2026-01-30T14:30:00Z",
  "applications": ["app-id-fee-manager", "app-id-value-manager"]
}

Error Response: 401 Unauthorized

{
  "isValid": false,
  "error": "SessionExpired",
  "message": "Your session has expired. Please login again."
}

Terminate Session (Logout)

Endpoint: POST /api/v1/sessions/terminate

Authentication: Session token (in Authorization header or cookie)

Request Body:

{
  "sessionToken": "a1b2c3d4...x0y1z2a3b4c5d6e7f8g9h0i1j2k3l4"
}

Success Response: 200 OK

{
  "message": "Session terminated successfully",
  "terminatedAt": "2026-01-30T14:45:00Z"
}

List Active Sessions

Endpoint: GET /api/v1/sessions

Authentication: Session token (in Authorization header or cookie)

Success Response: 200 OK

{
  "totalSessions": 3,
  "maxSessions": 5,
  "sessions": [
    {
      "sessionId": "session-1",
      "createdAt": "2026-01-30T14:25:00Z",
      "lastActivityAt": "2026-01-30T14:45:00Z",
      "expiresAt": "2026-01-30T15:15:00Z",
      "ipAddress": "192.168.1.100",
      "userAgent": "Chrome/120.0 (macOS)",
      "isCurrent": true
    },
    {
      "sessionId": "session-2",
      "createdAt": "2026-01-30T12:00:00Z",
      "lastActivityAt": "2026-01-30T14:30:00Z",
      "expiresAt": "2026-01-30T15:00:00Z",
      "ipAddress": "192.168.1.101",
      "userAgent": "Firefox/121.0 (Windows)",
      "isCurrent": false
    },
    {
      "sessionId": "session-3",
      "createdAt": "2026-01-29T10:00:00Z",
      "lastActivityAt": "2026-01-29T11:00:00Z",
      "expiresAt": "2026-01-29T11:30:00Z",
      "ipAddress": "10.0.0.50",
      "userAgent": "Safari/17.0 (iPhone)",
      "isCurrent": false
    }
  ]
}

Terminate Specific Session

Endpoint: DELETE /api/v1/sessions/{sessionId}

Authentication: Session token (in Authorization header or cookie)

Success Response: 200 OK

{
  "message": "Session terminated successfully",
  "sessionId": "session-2",
  "terminatedAt": "2026-01-30T14:50:00Z"
}

Performance Requirements

Metric Target Critical Threshold
Session creation time < 500ms < 2 seconds
Session validation time (cached) < 50ms < 200ms
Session validation time (database) < 200ms < 1 second
Concurrent login requests supported 200/second 100/second
Session cache hit rate > 95% > 85%
Background cleanup job execution < 30 seconds < 2 minutes
API endpoint response time (95th percentile) < 500ms < 2 seconds

Security Considerations

Token Security

  • Session tokens must be 128 characters using cryptographic RNG
  • Tokens generated using System.Security.Cryptography.RandomNumberGenerator
  • Tokens must be unique across all sessions (database unique constraint)
  • Tokens never logged in plain text (masked in logs: first 8 chars + ***)
  • Tokens transmitted only via HTTPS and secure HTTP-only cookies

Session Security

  • Sessions use secure, HTTP-only cookies with SameSite=Strict flag
  • Session tokens not exposed in URLs or client-side JavaScript
  • Session binding to IP address (optional, configurable)
  • Anomaly detection for session hijacking attempts
  • User-Agent tracking to detect suspicious device changes

Rate Limiting

  • Maximum 5 failed login attempts per IP per 15 minutes
  • Temporary IP block after rate limit exceeded (15-minute cooldown)
  • Exponential backoff for repeated violations
  • Rate limiting per user account (prevent credential stuffing)

Audit Trail

  • All login attempts logged (success and failure)
  • Session creation, validation, and termination logged
  • IP addresses and User-Agent strings recorded
  • Failed authentication attempts trigger security alerts
  • Suspicious activity patterns monitored (multiple IPs, rapid logins)

Session Hijacking Prevention

  • Session tokens rotated on privilege escalation
  • Concurrent session monitoring for anomalies
  • Optional two-factor authentication for sensitive operations
  • Session invalidation on password/token change
  • Logout from all devices feature available

Data Protection

  • Session data encrypted at rest in database
  • Session cache encrypted in Redis
  • PII minimized in session records
  • GDPR compliance: sessions deleted with user account

Testing Scenarios

Test Case 1: Successful Login

Given: Valid trial user with unexpired trial
When: User submits correct login token
Then: Session created, 201 response, user redirected to dashboard
Verify: Session record in database, cache populated, LastLoginAt updated, LoginCount incremented

Test Case 2: Invalid Login Token

Given: Non-existent or incorrect login token
When: User attempts to login
Then: 401 Unauthorized returned, no session created
Verify: Failed attempt logged, rate limit counter incremented

Test Case 3: Expired Trial Cannot Login

Given: Trial user with expired trial (TrialExpirationDate < now)
When: User attempts to login with valid token
Then: 403 Forbidden returned with trial expired message
Verify: No session created, expiration date included in response

Test Case 4: Concurrent Session Limit Enforcement

Given: User with 5 active sessions
When: User attempts 6th login
Then: 409 Conflict returned or oldest session terminated (based on policy)
Verify: Total active sessions never exceeds 5

Test Case 5: Session Timeout After Inactivity

Given: Active session with no activity for 30+ minutes
When: Background monitor runs
Then: Session marked as expired, removed from cache
When: User attempts to use expired session
Then: 401 Unauthorized, user redirected to login
Verify: Session IsExpired=true in database

Test Case 6: Remember Me Extended Session

Given: User logs in with "Remember Me" checked
When: Session created
Then: Session expiration set to 7 days
Verify: Session remains valid for 7 days without activity

Test Case 7: Rate Limiting Failed Logins

Given: IP address with 0 failed attempts
When: User makes 6 failed login attempts in 10 minutes
Then: First 5 attempts return 401, 6th attempt returns 429
Verify: IP blocked for 15 minutes, cannot attempt login

Test Case 8: Explicit Logout

Given: Active session
When: User clicks logout button
Then: Session terminated, cookie cleared, user redirected
Verify: Session IsExpired=true, TerminatedAt set, TerminationReason="UserLogout"

Test Case 9: Inactive Account Cannot Login

Given: Trial user with IsActive=false
When: User attempts to login with valid token
Then: 403 Forbidden returned
Verify: No session created, appropriate error message

Test Case 10: Session Validation Performance

Given: 10,000 active sessions in cache
When: Session validation request received
Then: Response returned in < 50ms (cache hit)
Verify: Cache hit recorded, no database query executed

Monitoring and Analytics

Key Metrics to Track

  • Login Success Rate: Successful logins / Total login attempts
  • Failed Login Rate: Failed attempts / Total attempts (security indicator)
  • Average Session Duration: Mean time between session creation and expiration/termination
  • Active Sessions Count: Current number of active sessions across all users
  • Concurrent Sessions per User: Distribution of session counts (1, 2, 3, 4, 5)
  • Session Timeout Rate: Sessions expired due to inactivity / Total sessions
  • Cache Hit Rate: Session validations served from cache / Total validations
  • Rate Limit Triggers: Number of IPs hitting rate limits per hour

Performance Monitoring

  • Session creation response time (P50, P95, P99)
  • Session validation response time (P50, P95, P99)
  • Database query execution time for session operations
  • Cache lookup latency
  • Background cleanup job duration

Security Monitoring

  • Failed login attempts per hour/day
  • Accounts with multiple failed login attempts
  • Rate limit violations by IP address
  • Suspicious login patterns (multiple IPs, geographic anomalies)
  • Session hijacking indicators (IP changes, User-Agent changes)
  • Concurrent session limit violations

Alerts

  • Login failure rate > 20% in 1 hour
  • Rate limit triggers > 50 per hour (potential attack)
  • Cache hit rate < 85% (cache performance issue)
  • Session creation response time > 2 seconds (database issue)
  • Background cleanup job fails to complete
  • Abnormal spike in active sessions (potential abuse)
  • Geographic anomaly detected (login from unusual location)
  • UC-001: Trial User Self-Registration and Access
  • UC-003: Trial User Application Access Validation
  • UC-004: Trial Expiration and Renewal
  • UC-005: Administrator Trial User Management
  • UC-008: Session Management and Monitoring (Admin)
  • UC-009: Security Audit Trail and Reporting
  • UC-010: Rate Limiting and Abuse Prevention

Notes and Assumptions

  1. Session Storage: Sessions stored in relational database with Redis cache for performance
  2. Token Format: 128-character alphanumeric tokens balance security and transmission efficiency
  3. Timeout Policy: 30-minute idle timeout balances security and user experience
  4. Concurrent Limit: 5 concurrent sessions accommodate multiple devices while preventing abuse
  5. Remember Me: Optional 7-day extension for user convenience on trusted devices
  6. Rate Limiting: IP-based rate limiting may affect users behind NAT; consider user-based limits
  7. Cache Invalidation: Sessions removed from cache when expired or terminated
  8. Cleanup Strategy: Expired sessions retained for 7 days for audit purposes, then purged
  9. Mobile Considerations: Mobile apps should handle session expiration gracefully with token refresh
  10. Load Balancing: Session validation must work across multiple application instances (stateless design)

Revision History

Version Date Author Changes
1.0 2026-01-30 System Analyst Initial use case documentation

Document Owner: Platform Architecture Team
Stakeholders: Product Management, Engineering, Security, Customer Success
Review Cycle: Quarterly or as needed for major changes