Use Case 003: Application Access Validation

Overview

Description

This use case describes the real-time validation process that registered applications perform to verify that a user has valid access before allowing them to use application features. The Application Manager acts as a centralized authorization service, validating session tokens, checking trial expiration, and confirming application-specific access grants. This validation occurs on every protected operation to ensure security and enforce trial limitations.

Note: Application Manager supports any registered application, including Riptide suite applications (Fee Manager, Value Manager, etc.), third-party applications, and custom applications built by developers using the Application Manager platform.

Actors

Preconditions

1. Application Manager is running and accessible
2. Client application is registered with Application Manager
3. User has an active session (session token exists)
4. User has previously authenticated (logged in)
5. Application-to-Application Manager network connectivity is available
6. Database is accessible for validation queries

Postconditions

Success Postconditions

1. Access validation result (granted/denied) returned to application
2. Session activity timestamp updated
3. Validation metrics logged for monitoring
4. Cache updated with validation result (if caching enabled)
5. User access permitted by requesting application
6. Audit trail record created

Failure Postconditions

1. Access denied response returned with specific reason
2. Failed validation logged for security monitoring
3. User redirected to login or error page by application
4. Session may be invalidated if compromised
5. Alert triggered if suspicious pattern detected

Triggers

• User attempts to access protected feature in registered application
• User navigates to new page requiring authentication
• Application performs periodic session validation (heartbeat)
• User invokes API endpoint requiring authorization
• Application startup/initialization requiring user context

Basic Flow (Happy Path)

sequenceDiagram
    actor User as End User
    participant App as Client Application
    participant AppMgr as Application Manager
    participant Cache as Redis Cache
    participant DB as Identity Database
    participant Metrics as Monitoring Service

    User->>App: Access protected feature
    App->>App: Extract session token from request
    
    Note over App,Cache: Check local cache first (if enabled)
    App->>Cache: Check cached validation (key: token:appId)
    
    alt Cache Hit (< 60s old)
        Cache->>App: Valid access (cached)
        App->>User: Grant access to feature
    else Cache Miss or Expired
        App->>AppMgr: POST /api/v1/sessions/validate
        Note over App,AppMgr: Request includes: sessionToken, applicationId
        
        AppMgr->>AppMgr: Validate request format
        AppMgr->>DB: Query session by token
        DB->>AppMgr: Session record found
        
        AppMgr->>AppMgr: Check session is active
        AppMgr->>AppMgr: Check session not expired
        
        AppMgr->>DB: Query trial user details
        DB->>AppMgr: User record found
        
        AppMgr->>AppMgr: Check trial not expired
        AppMgr->>AppMgr: Check user is active
        
        AppMgr->>DB: Query application access grant
        DB->>AppMgr: Grant record found
        
        AppMgr->>AppMgr: Check grant not revoked
        AppMgr->>AppMgr: Check grant not expired
        
        AppMgr->>DB: Update session last activity timestamp
        DB->>AppMgr: Updated successfully
        
        AppMgr->>Metrics: Log validation success
        AppMgr->>App: 200 OK (access granted)
        
        App->>Cache: Cache validation result (60s TTL)
        App->>User: Grant access to feature
    end
    
    Note over User,Metrics: User successfully uses application

Detailed Steps

1. User Initiates Protected Action

   • User clicks button, navigates to page, or calls API
   • Application intercepts request requiring authorization
   • Application determines authentication is required

2. Application Extracts Session Token

   • Check HTTP Authorization header: Bearer {token}
   • Check session cookie: riptide_session={token}
   • Check query parameter: ?session={token} (fallback)
   • If no token found, return 401 Unauthorized immediately

3. Application Checks Local Cache (Optional)

   • Generate cache key: session:${sessionToken}:${applicationId}
   • Check Redis/Memory cache for recent validation
   • If cached result found and < 60 seconds old:
     • Use cached validation result
     • Skip remote validation call
     • Proceed to step 9
   • If cache miss or expired, proceed to step 4

4. Application Calls Validation Endpoint

   • Construct validation request payload
   • Include: sessionToken, applicationId, requestedOperation (optional)
   • Send POST to /api/v1/sessions/validate
   • Set timeout: 5 seconds
   • Include retry logic: 2 retries with exponential backoff

5. Application Manager Validates Request

   • Verify request body is valid JSON
   • Ensure sessionToken is present and format is valid (GUID)
   • Ensure applicationId is present and format is valid
   • Return 400 Bad Request if validation fails

6. Application Manager Queries Session

   • Query database: SELECT * FROM Sessions WHERE SessionToken = @token
   • If not found, return 401 Unauthorized (reason: "SessionNotFound")
   • If found, proceed to step 7

7. Application Manager Validates Session Status

   • Check IsActive = true
   • Check ExpiresAt > NOW()
   • Check session hasn't been explicitly invalidated
   • If any check fails, return 401 Unauthorized (reason: "SessionInvalid" or "SessionExpired")

8. Application Manager Validates Trial User

   • Query database: SELECT * FROM TrialUsers WHERE Id = @userId
   • Check IsActive = true
   • Check TrialExpirationDate > NOW()
   • If trial expired, return 403 Forbidden (reason: "TrialExpired")
   • If user inactive, return 403 Forbidden (reason: "UserInactive")

9. Application Manager Validates Application Access

   • Query database: SELECT * FROM TrialUserApplications WHERE TrialUserId = @userId AND ApplicationId = @appId
   • If grant not found, return 403 Forbidden (reason: "NoAccessGrant")
   • Check IsRevoked = false
   • Check ExpiresAt > NOW() (may differ from trial expiration)
   • If any check fails, return 403 Forbidden (reason: "AccessRevoked" or "GrantExpired")

10. Application Manager Updates Session Activity

    • Update LastActivityAt = NOW() on session record
    • Increment RequestCount (for analytics)
    • Log validation event asynchronously

11. Application Manager Returns Success

    • Return 200 OK with validation response
    • Include user context, trial info, remaining days
    • Include cache TTL suggestion (60 seconds)

12. Application Caches Result

    • Store validation result in cache
    • Set expiration: 60 seconds
    • Use consistent cache key format

13. Application Grants Access

    • Allow user to proceed with requested operation
    • User context available for personalization
    • Application features enabled based on trial status

Alternative Flows

Alt Flow 1: Session Token Not Found

sequenceDiagram
    participant App as Client Application
    participant AppMgr as Application Manager
    participant DB as Identity Database
    participant Audit as Audit Log

    App->>AppMgr: POST /api/v1/sessions/validate
    AppMgr->>DB: Query session by token
    DB->>AppMgr: No session found
    
    AppMgr->>Audit: Log failed validation (SessionNotFound)
    AppMgr->>App: 401 Unauthorized
    
    Note over AppMgr,App: Response: SessionNotFound
    
    App->>App: Clear local session data
    App->>App: Redirect to login page

Steps:

1. Session query returns no results (step 6)
2. Application Manager logs failed validation
3. Return 401 Unauthorized with reason: "SessionNotFound"
4. Application receives 401 response
5. Application clears any local session data
6. Application redirects user to login page
7. User must re-authenticate to continue

Alt Flow 2: Trial Has Expired

sequenceDiagram
    participant User as End User
    participant App as Client Application
    participant AppMgr as Application Manager
    participant DB as Identity Database

    User->>App: Attempt to use feature
    App->>AppMgr: POST /api/v1/sessions/validate
    AppMgr->>DB: Validate session (OK)
    AppMgr->>DB: Query trial user
    DB->>AppMgr: User found, trial expired
    
    Note over AppMgr: TrialExpirationDate < NOW()
    
    AppMgr->>DB: Mark session for notification
    AppMgr->>App: 403 Forbidden (TrialExpired)
    
    App->>User: Display trial expired message
    Note over User,App: "Your trial has expired.<br/>Contact us to upgrade."
    
    alt User requests extension
        User->>App: Click "Request Extension"
        App->>App: Navigate to upgrade/contact page
    else User logs out
        User->>App: Acknowledge and logout
    end

Steps:

1. Session validation succeeds (steps 6-7)
2. Trial user query succeeds (step 8)
3. Application Manager checks TrialExpirationDate
4. Current date/time is past expiration date
5. Return 403 Forbidden with reason: "TrialExpired"
6. Include expiration date and contact information in response
7. Application displays user-friendly expiration message
8. Application offers options:
   • Request trial extension
   • Upgrade to paid plan
   • Contact sales
9. User cannot proceed with protected operation

Alt Flow 3: No Access Grant for Application

sequenceDiagram
    participant App as Client Application
    participant AppMgr as Application Manager
    participant DB as Identity Database

    App->>AppMgr: POST /api/v1/sessions/validate
    Note over App,AppMgr: User trying to access "Workflow Designer"
    
    AppMgr->>DB: Validate session (OK)
    AppMgr->>DB: Validate trial user (OK)
    AppMgr->>DB: Query application grant
    DB->>AppMgr: No grant found for this application
    
    AppMgr->>App: 403 Forbidden (NoAccessGrant)
    
    App->>App: Display access denied message
    Note over App: "You don't have access to this application.<br/>Available applications: Fee Manager, Value Manager"

Steps:

1. Session and trial user validation succeed (steps 6-8)
2. Application grant query returns no results (step 9)
3. Return 403 Forbidden with reason: "NoAccessGrant"
4. Include list of applications user has access to
5. Application displays access denied message
6. Application suggests available applications
7. User can:
   • Navigate to an application they have access to
   • Contact administrator to request access
   • Logout

Alt Flow 4: Session Has Expired (Timeout)

sequenceDiagram
    participant User as End User
    participant App as Client Application
    participant AppMgr as Application Manager
    participant DB as Identity Database

    Note over User,App: User inactive for 2+ hours
    
    User->>App: Resume activity
    App->>AppMgr: POST /api/v1/sessions/validate
    AppMgr->>DB: Query session
    DB->>AppMgr: Session found
    AppMgr->>AppMgr: Check ExpiresAt timestamp
    
    Note over AppMgr: ExpiresAt < NOW()
    
    AppMgr->>DB: Mark session as expired
    AppMgr->>App: 401 Unauthorized (SessionExpired)
    
    App->>App: Clear session data
    App->>User: Display session expired message
    Note over User,App: "Your session has expired.<br/>Please login again."
    
    App->>App: Redirect to login page

Steps:

1. Session query succeeds (step 6)
2. Session status check fails due to expiration (step 7)
3. ExpiresAt timestamp is in the past
4. Mark session as explicitly expired (for auditing)
5. Return 401 Unauthorized with reason: "SessionExpired"
6. Application displays session timeout message
7. Application redirects to login page
8. User must re-authenticate to continue

Alt Flow 5: Application Manager Unavailable

sequenceDiagram
    participant User as End User
    participant App as Client Application
    participant AppMgr as Application Manager
    participant Cache as Cache Service

    User->>App: Access protected feature
    App->>Cache: Check cached validation
    Cache->>App: Cache miss
    
    App->>AppMgr: POST /api/v1/sessions/validate
    Note over AppMgr: Service unavailable
    AppMgr--xApp: Connection timeout
    
    App->>App: Retry with backoff (attempt 2/3)
    App->>AppMgr: POST /api/v1/sessions/validate
    AppMgr--xApp: Connection timeout
    
    App->>App: Check grace period policy
    
    alt Grace period enabled
        App->>Cache: Check extended cache (5 min)
        alt Extended cache hit
            Cache->>App: Cached validation (stale)
            App->>User: Grant access (degraded mode)
            Note over User,App: Display warning banner
        else No extended cache
            App->>User: 503 Service Unavailable
            Note over User,App: "Service temporarily unavailable"
        end
    else Grace period disabled
        App->>User: 503 Service Unavailable
        Note over User,App: "Authentication service unavailable"
    end

Steps:

1. Application attempts validation call (step 4)
2. Connection to Application Manager fails (network issue, service down)
3. Application retries request (2 more attempts with exponential backoff)
4. All retry attempts fail
5. Application checks configuration for grace period policy
6. If grace period enabled (degraded mode):
   • Check cache for stale validation (up to 5 minutes old)
   • If stale cache found, allow access with warning banner
   • Log degraded mode operation for investigation
7. If grace period disabled or no stale cache:
   • Return 503 Service Unavailable to user
   • Display maintenance message
   • User cannot proceed
8. Alert sent to operations team

Alt Flow 6: Invalid/Malformed Session Token

flowchart TD
    A[User sends request with token] --> B{Token format valid?}
    B -->|Not GUID format| C[Return 400 Bad Request]
    B -->|Too short/long| D[Return 400 Bad Request]
    B -->|Contains invalid chars| E[Return 400 Bad Request]
    B -->|Valid format| F[Proceed to database lookup]
    
    F --> G{Token found in DB?}
    G -->|No| H[Return 401 Unauthorized]
    G -->|Yes| I[Validate session status]
    
    C --> J[Log validation error]
    D --> J
    E --> J
    H --> J
    
    J --> K[User redirected to login]

Steps:

1. Application Manager receives validation request (step 5)
2. Token format validation fails:
   • Not a valid GUID format
   • Contains special characters or SQL injection attempt
   • Token length incorrect
   • Token is null or empty
3. Return 400 Bad Request with reason: "InvalidTokenFormat"
4. Log suspicious activity (potential attack)
5. If pattern detected (multiple invalid tokens from same IP):
   • Trigger rate limiting
   • Alert security team
6. Application displays generic error message (don't leak security details)
7. User redirected to login page

Alt Flow 7: Access Grant Revoked Mid-Session

sequenceDiagram
    actor Admin as Administrator
    participant AdminUI as Admin Panel
    participant AppMgr as Application Manager
    participant DB as Identity Database
    participant User as End User
    participant App as Client Application

    Note over User,App: User actively using application
    
    Admin->>AdminUI: Revoke access for user
    AdminUI->>AppMgr: PATCH /api/v1/trial-users/{id}/applications/{appId}
    AppMgr->>DB: Update grant: IsRevoked = true
    DB->>AppMgr: Grant revoked
    AppMgr->>AdminUI: Access revoked confirmation
    
    Note over User,App: User continues work (cache not expired yet)
    
    User->>App: Access feature
    App->>App: Check cache (still valid)
    App->>User: Access granted (from cache)
    
    Note over App: 60 seconds pass, cache expires
    
    User->>App: Access another feature
    App->>App: Cache expired
    App->>AppMgr: POST /api/v1/sessions/validate
    AppMgr->>DB: Check access grant
    DB->>AppMgr: Grant is revoked
    AppMgr->>App: 403 Forbidden (AccessRevoked)
    
    App->>App: Invalidate session
    App->>User: Display access revoked message
    Note over User,App: "Your access has been revoked.<br/>Please contact administrator."

Steps:

1. Administrator revokes application access while user is active
2. Database grant record updated with IsRevoked = true
3. User continues working with cached validation (up to 60 seconds)
4. Cache expires
5. Next validation request checks database
6. Revocation detected (step 9)
7. Return 403 Forbidden with reason: "AccessRevoked"
8. Application invalidates local session
9. User notified of access revocation
10. User logged out from application

Business Rules

Data Requirements

Validation Request

{
  "sessionToken": "uuid-v4 (required)",
  "applicationId": "string (required)",
  "requestedOperation": "string (optional, e.g., 'read', 'write', 'admin')",
  "clientIpAddress": "string (optional, for audit)",
  "clientUserAgent": "string (optional, for analytics)"
}

Validation Response - Success (200 OK)

{
  "isValid": true,
  "userId": "uuid-v4",
  "userEmail": "john.doe@example.com",
  "fullName": "John Doe",
  "trialStatus": "active",
  "trialExpirationDate": "2026-03-01T10:30:00Z",
  "trialDaysRemaining": 30,
  "sessionExpiresAt": "2026-01-30T18:30:00Z",
  "applicationAccess": {
    "applicationId": "app-id-fee-manager",
    "applicationName": "Fee Manager",
    "hasAccess": true,
    "grantExpiresAt": "2026-03-01T10:30:00Z",
    "permissions": ["read", "write"]
  },
  "cacheTtlSeconds": 60,
  "validatedAt": "2026-01-30T16:30:00Z"
}

Validation Response - Access Denied (401 Unauthorized)

{
  "isValid": false,
  "reason": "SessionNotFound",
  "message": "Session token is invalid or expired",
  "errorCode": "AUTH_001",
  "timestamp": "2026-01-30T16:30:00Z",
  "requestId": "req-123456"
}

Possible Reason Codes:

• SessionNotFound - Token doesn't exist in database
• SessionExpired - Session past expiration time
• SessionInvalid - Session marked as inactive/revoked

Validation Response - Access Denied (403 Forbidden)

{
  "isValid": false,
  "reason": "TrialExpired",
  "message": "Your trial period has ended",
  "errorCode": "AUTH_002",
  "trialExpiredAt": "2026-01-15T10:30:00Z",
  "upgradeUrl": "https://riptide.example.com/upgrade",
  "contactEmail": "sales@example.com",
  "timestamp": "2026-01-30T16:30:00Z",
  "requestId": "req-123456"
}

Possible Reason Codes:

• TrialExpired - Trial expiration date passed
• UserInactive - User account disabled by admin
• NoAccessGrant - No access grant exists for this application
• GrantExpired - Application-specific grant expired
• AccessRevoked - Access explicitly revoked by admin

Session Record (Database)

{
  "SessionId": "uuid-v4",
  "SessionToken": "uuid-v4 (indexed)",
  "TrialUserId": "uuid-v4 (foreign key)",
  "CreatedAt": "datetime (UTC)",
  "ExpiresAt": "datetime (UTC)",
  "LastActivityAt": "datetime (UTC)",
  "IsActive": "boolean",
  "RequestCount": "integer",
  "IpAddress": "string (optional)",
  "UserAgent": "string (optional)"
}

Application Access Grant Record (Database)

{
  "Id": "uuid-v4",
  "TrialUserId": "uuid-v4 (foreign key)",
  "ApplicationId": "uuid-v4 (foreign key)",
  "GrantedAt": "datetime (UTC)",
  "ExpiresAt": "datetime (UTC)",
  "IsRevoked": "boolean",
  "RevokedAt": "datetime (UTC, nullable)",
  "RevokedBy": "string (nullable, admin user ID)"
}

API Endpoints

Validate Session

Endpoint: POST /api/v1/sessions/validate

Authentication: Service-to-Service (API Key or Mutual TLS)

Request Body:

{
  "sessionToken": "550e8400-e29b-41d4-a716-446655440000",
  "applicationId": "app-id-fee-manager",
  "requestedOperation": "read",
  "clientIpAddress": "192.168.1.100",
  "clientUserAgent": "Mozilla/5.0..."
}

Success Response: 200 OK

{
  "isValid": true,
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "userEmail": "john.doe@example.com",
  "fullName": "John Doe",
  "trialStatus": "active",
  "trialExpirationDate": "2026-03-01T10:30:00Z",
  "trialDaysRemaining": 30,
  "sessionExpiresAt": "2026-01-30T18:30:00Z",
  "applicationAccess": {
    "applicationId": "app-id-fee-manager",
    "applicationName": "Fee Manager",
    "hasAccess": true,
    "grantExpiresAt": "2026-03-01T10:30:00Z",
    "permissions": ["read", "write"]
  },
  "cacheTtlSeconds": 60,
  "validatedAt": "2026-01-30T16:30:00Z"
}

Error Responses:

400 Bad Request - Invalid request

{
  "error": "ValidationError",
  "message": "Invalid session token format",
  "errors": {
    "sessionToken": ["Must be a valid GUID"]
  }
}

401 Unauthorized - Session invalid

{
  "isValid": false,
  "reason": "SessionExpired",
  "message": "Session has expired",
  "errorCode": "AUTH_001",
  "timestamp": "2026-01-30T16:30:00Z"
}

403 Forbidden - Access denied

{
  "isValid": false,
  "reason": "TrialExpired",
  "message": "Your trial period has ended",
  "errorCode": "AUTH_002",
  "trialExpiredAt": "2026-01-15T10:30:00Z",
  "upgradeUrl": "https://riptide.example.com/upgrade",
  "timestamp": "2026-01-30T16:30:00Z"
}

503 Service Unavailable - Service error

{
  "error": "ServiceUnavailable",
  "message": "Validation service temporarily unavailable",
  "retryAfterSeconds": 30,
  "requestId": "req-123456"
}

Performance Requirements

Performance Optimization Strategies

1. Caching

   • Cache validation results for 60 seconds
   • Use Redis for distributed cache across application instances
   • Implement cache warming for frequently accessed sessions

2. Database Optimization

   • Index on SessionToken (unique, clustered)
   • Index on TrialUserId, ApplicationId for grant lookups
   • Use read replicas for validation queries (high read volume)
   • Implement connection pooling (min: 10, max: 100)

3. Query Optimization

   • Single query joining Sessions, TrialUsers, and TrialUserApplications
   • Pre-compute trial expiration status during query
   • Use compiled queries (Entity Framework) or stored procedures

4. Application-Level Optimization

   • Implement circuit breaker pattern (fail fast when Application Manager is down)
   • Use async/await for non-blocking I/O
   • Batch validation requests where possible (multi-tenant scenarios)
   • Implement request deduplication (same token validated multiple times concurrently)

5. Network Optimization

   • Use HTTP/2 for multiplexing
   • Enable gzip compression for responses
   • Co-locate applications and Application Manager in same region/VPC
   • Use keep-alive connections

Security Considerations

Token Security

• Token Transmission: All validation requests must use HTTPS (TLS 1.2+)
• Token Storage: Applications should not persist tokens to disk (memory only)
• Token Logging: Never log session tokens in plain text (mask or hash)
• Token Validation: Strict format validation to prevent injection attacks

Authentication

• Service-to-Service Auth: Registered applications authenticate to Application Manager using:
  • API Keys (minimum: 256-bit entropy)
  • Mutual TLS certificates (preferred for production)
  • OAuth 2.0 Client Credentials flow (for third-party integrations)
• Rate Limiting: Per-application rate limits prevent abuse
• IP Whitelisting: Restrict validation endpoint to known application IPs (optional)

Authorization

• Least Privilege: Applications only receive data needed for authorization decision
• No Sensitive Data: Validation responses exclude passwords, tokens, payment info
• Role-Based Access: Future enhancement for operation-level permissions

Audit and Monitoring

• Audit Trail: All validation attempts logged with:
  • Timestamp, session token (hashed), application ID, result, reason
• Failed Validation Monitoring: Alert on patterns indicating:
  • Brute force attacks (many failed validations from same IP)
  • Token theft (same token used from multiple IPs)
  • Expired token reuse (same expired token attempted repeatedly)
• Anomaly Detection: Machine learning models detect unusual validation patterns

Token Hijacking Prevention

• Session Binding: Bind sessions to IP address and User-Agent (optional, configurable)
• Token Rotation: Rotate session tokens periodically (e.g., every 24 hours)
• Concurrent Session Limits: Maximum 5 active sessions per user
• Suspicious Activity Detection: Invalidate session if:
  • Used from significantly different geolocation within short time
  • User-Agent changes mid-session
  • Unusual request patterns detected

Data Protection

• Encryption at Rest: Database encrypted using transparent data encryption (TDE)
• Encryption in Transit: All communication over TLS
• PII Handling: User emails and names handled per GDPR/CCPA requirements
• Token Expiration: Sessions expire after 2 hours of inactivity (configurable)

Testing Scenarios

Test Case 1: Successful Validation (Happy Path)

Given: Valid session token, active trial, access grant exists
When: Application validates session
Then: 200 OK response, access granted
Verify: Response includes user context, trial info, cache TTL

Test Case 2: Session Not Found

Given: Non-existent or invalid session token
When: Application validates session
Then: 401 Unauthorized, reason: "SessionNotFound"
Verify: No database changes, audit log entry created

Test Case 3: Trial Expired During Session

Given: Valid session, but trial expiration date passed
When: Application validates session
Then: 403 Forbidden, reason: "TrialExpired"
Verify: Response includes expiration date and upgrade information

Test Case 4: No Access Grant for Application

Given: Valid session, active trial, but no grant for requested app
When: Application validates session for unauthorized app
Then: 403 Forbidden, reason: "NoAccessGrant"
Verify: Response includes list of authorized applications

Test Case 5: Session Expired (Timeout)

Given: Valid session token, but ExpiresAt timestamp passed
When: Application validates session
Then: 401 Unauthorized, reason: "SessionExpired"
Verify: Session marked as expired in database

Test Case 6: Cache Performance

Given: Same session token validated twice within 60 seconds
When: Second validation occurs
Then: Cached result returned (no database query)
Verify: Response time < 10ms, cache hit metric incremented

Test Case 7: Access Revoked Mid-Session

Given: Active session, admin revokes access grant
When: Application validates after cache expires
Then: 403 Forbidden, reason: "AccessRevoked"
Verify: User cannot proceed, session invalidated

Test Case 8: Application Manager Unavailable

Given: Application Manager service is down
When: Application attempts validation (with retries)
Then: 503 Service Unavailable after retries exhausted
Verify: Circuit breaker triggered, alert sent to operations

Test Case 9: Concurrent Validations (Load Test)

Given: 1,000 concurrent validation requests for different sessions
When: All requests sent simultaneously
Then: All complete within 200ms, success rate > 99.9%
Verify: No database deadlocks, no memory leaks

Test Case 10: Token Format Validation

Given: Malformed tokens (SQL injection, XSS, invalid format)
When: Application validates with malformed token
Then: 400 Bad Request immediately (no database query)
Verify: Security alert triggered, IP logged for monitoring

Test Case 11: Session Binding (IP/User-Agent Change)

Given: Valid session, but request from different IP/User-Agent
When: Application validates with session binding enabled
Then: 401 Unauthorized, reason: "SessionBindingViolation"
Verify: Session invalidated, security alert triggered

Test Case 12: Graceful Degradation (Extended Cache)

Given: Application Manager unavailable, stale cache available (2 min old)
When: Application validates with grace period enabled
Then: Access granted using stale cache, warning banner displayed
Verify: Degraded mode logged, operations alerted

Monitoring and Analytics

Key Metrics to Track

Performance Metrics

• Validation Latency: p50, p95, p99 response times
• Throughput: Validations per second by application
• Cache Hit Rate: Percentage of validations served from cache
• Database Query Time: Time spent on database operations
• Error Rate: Failed validations / Total validations

Business Metrics

• Active Sessions: Number of active sessions by application
• Validation Volume: Total validations per hour/day
• Peak Usage Times: When validation volume is highest
• Top Applications: Which applications validate most frequently
• User Activity: Validations per user (engagement metric)

Security Metrics

• Failed Validations by Reason: Breakdown of failure reasons
• Suspicious Activity: Invalid tokens, IP changes, unusual patterns
• Token Reuse Attempts: Expired/invalid tokens reused
• Geographic Distribution: Validation requests by region

Reliability Metrics

• Service Availability: Uptime percentage
• Circuit Breaker Trips: How often applications fail over
• Cache Failures: Redis unavailability incidents
• Database Connection Pool: Utilization and wait times

Dashboards

Real-Time Operations Dashboard:

• Current validation rate (requests/second)
• Response time graph (last 60 minutes)
• Error rate (last 60 minutes)
• Active sessions count
• Cache hit rate

Security Monitoring Dashboard:

• Failed validation attempts by reason
• Geographic heat map of validation requests
• Anomalous patterns detected
• Top IPs with failed validations

Business Analytics Dashboard:

• Daily active users (by validations)
• Application usage breakdown
• Trial users nearing expiration
• Session duration distribution

Alerts

Related Use Cases

• UC-001: Trial User Self-Registration and Access - Initial user creation and credentials
• UC-002: Trial User Login and Session Management - Session creation process
• UC-004: Trial Expiration and Renewal - What happens when trials end
• UC-005: Administrator Trial User Management - Admin access revocation flows
• UC-006: Session Lifecycle Management - Session creation, renewal, invalidation
• UC-007: Application Registration and Configuration - How applications register for validation
• UC-008: Security Event Monitoring - Detection and response to validation anomalies

Integration Examples

Example 1: ASP.NET Core Middleware

public class RiptideAuthenticationMiddleware
{
    private readonly RequestDelegate _next;
    private readonly IValidationService _validationService;
    private readonly IDistributedCache _cache;

    public RiptideAuthenticationMiddleware(
        RequestDelegate next,
        IValidationService validationService,
        IDistributedCache cache)
    {
        _next = next;
        _validationService = validationService;
        _cache = cache;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Extract session token from request
        if (!context.Request.Headers.TryGetValue("Authorization", out var authHeader))
        {
            context.Response.StatusCode = 401;
            await context.Response.WriteAsJsonAsync(new { error = "Missing authorization header" });
            return;
        }

        var token = authHeader.ToString().Replace("Bearer ", "");
        var appId = "app-id-fee-manager"; // From configuration

        // Check cache first
        var cacheKey = $"session:{token}:{appId}";
        var cachedResult = await _cache.GetStringAsync(cacheKey);
        
        if (!string.IsNullOrEmpty(cachedResult))
        {
            var validation = JsonSerializer.Deserialize<ValidationResponse>(cachedResult);
            context.Items["UserContext"] = validation;
            await _next(context);
            return;
        }

        // Cache miss - validate with Application Manager
        var result = await _validationService.ValidateSessionAsync(token, appId);

        if (!result.IsValid)
        {
            context.Response.StatusCode = result.StatusCode;
            await context.Response.WriteAsJsonAsync(new 
            { 
                error = result.Reason,
                message = result.Message 
            });
            return;
        }

        // Cache successful validation
        var cacheOptions = new DistributedCacheEntryOptions
        {
            AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(60)
        };
        await _cache.SetStringAsync(cacheKey, JsonSerializer.Serialize(result), cacheOptions);

        // Store user context for downstream handlers
        context.Items["UserContext"] = result;

        await _next(context);
    }
}

Example 2: Node.js/Express Middleware

const axios = require('axios');
const redis = require('redis');

const redisClient = redis.createClient();
const APPLICATION_ID = process.env.APPLICATION_ID;
const APP_MANAGER_URL = process.env.APP_MANAGER_URL;

async function validateSession(req, res, next) {
  // Extract token
  const authHeader = req.headers.authorization;
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing or invalid authorization header' });
  }

  const token = authHeader.substring(7);
  const cacheKey = `session:${token}:${APPLICATION_ID}`;

  try {
    // Check cache
    const cachedResult = await redisClient.get(cacheKey);
    if (cachedResult) {
      req.userContext = JSON.parse(cachedResult);
      return next();
    }

    // Validate with Application Manager
    const response = await axios.post(
      `${APP_MANAGER_URL}/api/v1/sessions/validate`,
      {
        sessionToken: token,
        applicationId: APPLICATION_ID,
        clientIpAddress: req.ip,
        clientUserAgent: req.headers['user-agent']
      },
      {
        timeout: 5000,
        headers: {
          'X-Api-Key': process.env.APP_MANAGER_API_KEY
        }
      }
    );

    // Cache successful validation
    await redisClient.setEx(cacheKey, 60, JSON.stringify(response.data));
    
    req.userContext = response.data;
    next();

  } catch (error) {
    if (error.response) {
      // Application Manager returned error
      return res.status(error.response.status).json(error.response.data);
    } else {
      // Network error or timeout
      console.error('Validation service error:', error.message);
      return res.status(503).json({ error: 'Validation service unavailable' });
    }
  }
}

module.exports = validateSession;

Example 3: Python/FastAPI Dependency

from fastapi import Depends, HTTPException, Request
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
import httpx
import redis
import json
from typing import Optional

security = HTTPBearer()
redis_client = redis.Redis(host='localhost', port=6379, db=0)

APPLICATION_ID = "app-id-fee-manager"
APP_MANAGER_URL = "https://app-manager.example.com"

async def validate_session(
    request: Request,
    credentials: HTTPAuthorizationCredentials = Depends(security)
) -> dict:
    """Validate session token with Application Manager."""
    
    token = credentials.credentials
    cache_key = f"session:{token}:{APPLICATION_ID}"
    
    # Check cache
    cached = redis_client.get(cache_key)
    if cached:
        return json.loads(cached)
    
    # Validate with Application Manager
    async with httpx.AsyncClient(timeout=5.0) as client:
        try:
            response = await client.post(
                f"{APP_MANAGER_URL}/api/v1/sessions/validate",
                json={
                    "sessionToken": token,
                    "applicationId": APPLICATION_ID,
                    "clientIpAddress": request.client.host,
                    "clientUserAgent": request.headers.get("user-agent")
                },
                headers={
                    "X-Api-Key": "your-api-key-here"
                }
            )
            
            if response.status_code != 200:
                raise HTTPException(
                    status_code=response.status_code,
                    detail=response.json()
                )
            
            validation_result = response.json()
            
            # Cache successful validation
            redis_client.setex(
                cache_key, 
                60, 
                json.dumps(validation_result)
            )
            
            return validation_result
            
        except httpx.TimeoutException:
            raise HTTPException(
                status_code=503,
                detail="Validation service unavailable"
            )
        except httpx.RequestError as e:
            raise HTTPException(
                status_code=503,
                detail=f"Validation service error: {str(e)}"
            )

# Usage in endpoint
@app.get("/api/fees")
async def get_fees(user_context: dict = Depends(validate_session)):
    """Protected endpoint requiring valid session."""
    user_id = user_context["userId"]
    user_email = user_context["userEmail"]
    # ... process request with user context

Notes and Assumptions

1. Real-Time Validation: Every protected operation validates access; no long-lived permissions cache
2. Performance Critical: Validation must be sub-100ms; uses aggressive caching and optimization
3. Stateless Applications: Registered applications don't store user state; rely on Application Manager
4. Network Reliability: Assumes reliable network between applications and Application Manager
5. Single Sign-Out: Invalidating session in Application Manager immediately blocks all applications (post-cache expiry)
6. Trial-Only Scope: Current implementation focused on trial users; licensed users are future enhancement
7. Cache Consistency: 60-second cache window means access revocations have slight delay (acceptable trade-off)
8. Service-to-Service Trust: Applications trust Application Manager responses; no additional validation
9. Platform Agnostic: Application Manager is not limited to Riptide suite; supports any registered application including third-party and custom applications
10. No Operation-Level Permissions: Currently validates application access only; feature-level permissions are future enhancement
11. Synchronous Validation: Validation is synchronous blocking call; async validation not supported

Revision History

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