Feature: Enhance GraphAPI Authentication Session and Token Management

[jonnybottles]

What problem would this feature solve?

Currently, Hawk lacks robust session and token management, particularly for Microsoft Graph authentication. This leads to potential failures during long-running operations and requires manual intervention when sessions expire. A comprehensive session management system would eliminate these issues and improve reliability.

Proposed Solution

Implement an intelligent session/token management system that:

• Proactively monitors token expiration
• Automatically refreshes sessions before timeout
• Handles different timeout windows for various services
• Provides seamless recovery from connection issues

Key Session/Token Windows

Microsoft Graph Access Tokens

• Default expiration: 1 hour (3600 seconds)
• Cannot be configured by application
• Most critical for Hawk's operation

Exchange Online PowerShell (EXO V3)

• Default session timeout: 4 hours
• Can be extended up to 24 hours with SessionOption
• Auto-reconnection handled by module

Refresh Tokens

• Default expiration: 90 days
• Can be revoked via Azure AD
• Cannot be extended

Technical Requirements

Token Monitoring

• Track Microsoft Graph token expiration (1-hour window)
• Monitor EXO session state (4-hour timeout)
• Handle refresh token lifecycle (90-day expiration)

Session Management

• Pre-emptive token refresh before expiration
• Automatic session recovery
• Graceful error handling
• State persistence across operations

Connection Handling

• Unified connection testing
• Retry logic for transient failures
• Cross-service session coordination

Implementation Approach

Session Tracking

• Implement centralized session state monitoring
• Create token lifecycle management system
• Develop service-specific connection handlers

Authentication Flow

• Update connection testing logic
• Implement token refresh mechanisms
• Create session recovery procedures

Integration

• Update existing cmdlets to use new session management
• Implement backward compatibility layer
• Add telemetry for session events

Acceptance Criteria

• Automatic token refresh before expiration
• Seamless session recovery after disconnection
• Proper handling of long-running operations
• Clear logging of session state changes
• Graceful error handling for all timeout scenarios
• Support for all authentication service timeouts
• Updated documentation reflecting new behavior
• Successful testing across various timeout scenarios

[jonnybottles]

Useful token expiration details:

Access tokens: The default lifetime of an access token is variable. When issued, an access token's default lifetime is assigned a random value ranging between 60-90 minutes (75 minutes on average).

read more at: https://learn.microsoft.com/en-us/entra/identity-platform/configurable-token-lifetimes

ID Tokens: Default time is set to expire in 60 minutes

read more at: https://learn.microsoft.com/en-us/entra/identity-platform/id-tokens

[jonnybottles]

Re-prioritizing this as a low priority. In speaking with @T0pCyber this is not currently an problem / need, as the data pulled from the Graph shouldn't exceed an hour (default access token expiration in MSGraph). If this does end up being a need, highly recommned migrating from Graph authentication to MSAL auth, as MSAL is a libary that handles token / session management / refreshes. Documentation for this is located on the Hawk Confluence > Documentation > Current Research > Graph Authentication & Session Management Research.