Version: Next

Sessions, MFA & device trust

This module manages the security layer that protects user sessions after authentication. It covers active session tracking, multi-factor authentication enforcement, and device trust classification.

Foundation → Security (segment: foundation/security)

Sub-section	Path	Description
Sessions	`foundation/security/sessions`	Active session management
MFA	`foundation/security/mfa`	Multi-factor authentication
Device Trust	`foundation/security/devices`	Trusted device management

Security architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                          Security Layer                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                     Authentication Flow                          │    │
│  │                                                                   │    │
│  │  Login → MFA Challenge → Device Check → Session Created          │    │
│  │                                                                   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                          │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────────┐   │
│  │   Sessions   │    │     MFA      │    │      Device Trust        │   │
│  │              │    │              │    │                          │   │
│  │ • Active     │    │ • TOTP       │    │ • Fingerprint            │   │
│  │ • Suspended  │    │ • SMS        │    │ • Trust levels           │   │
│  │ • Terminated │    │ • Email      │    │ • Compromise detect      │   │
│  │ • Expired    │    │ • Backup     │    │ • Auto-revoke            │   │
│  │ • Revoked    │    │              │    │                          │   │
│  └──────────────┘    └──────────────┘    └──────────────────────────┘   │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                     Login Attempt Tracking                       │    │
│  │                                                                   │    │
│  │  IP Address • Device Info • Location • Success/Failure           │    │
│  │                                                                   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Part 1: Sessions

Sessions track authenticated user access and allow administrators to monitor and control active logins.

Session properties

Field	Type	Description
`id`	string	Session identifier
`userId`	string	User ID
`tenantId`	string	Tenant ID
`status`	enum	Current status
`deviceType`	enum	Device category
`deviceInfo`	object	Device details
`ipAddress`	string	Client IP
`userAgent`	string	Browser/app info
`location`	object	Geo-location
`createdAt`	datetime	Session start
`expiresAt`	datetime	Expiration time
`lastActivityAt`	datetime	Last activity
`terminatedAt`	datetime	End time
`terminatedBy`	string	Who ended session
`terminationReason`	string	Why ended
`isCurrent`	boolean	Current session
`mfaVerified`	boolean	MFA completed

Session statuses

Status	Description
`active`	Session is active and valid
`suspended`	Temporarily suspended
`terminated`	Manually ended by user/admin
`expired`	Automatically expired
`revoked`	Force-revoked due to security

Device types

Type	Description
`desktop`	Desktop computer
`mobile`	Mobile phone
`tablet`	Tablet device
`unknown`	Cannot determine

Session management actions

Action	Description	Use case
View sessions	List active sessions	Security review
Terminate session	End a single session	Logout remote device
Terminate all	End all sessions	Security incident
Suspend session	Pause session	Investigation
Resume session	Reactivate suspended	Clear investigation

Bulk session operations

Operation	Description
`terminate`	End multiple sessions
`suspend`	Suspend multiple sessions
`revoke`	Security revoke sessions
`extend`	Extend session expiry

Session filters

Filter	Options
Status	Active, suspended, terminated, expired, revoked
Device	Desktop, mobile, tablet
Date range	From/to dates
User	Specific user
IP address	Specific IP or range

Viewing active sessions

Navigate to Foundation → Security → Sessions
View session list with:
- User name and email
- Device type and browser
- IP address and location
- Session start time
- Last activity
Filter by status, device type, or date
Click session for details

Terminating sessions

Single session:

Find session in list
Click session row or ... menu
Select Terminate
Confirm termination

Multiple sessions:

Select sessions via checkboxes
Click Bulk Actions
Select Terminate
Confirm bulk termination

All sessions for user:

Navigate to user profile
Click Security tab
Click Terminate All Sessions
User must re-authenticate

Field	Type	Description
`id`	string	Attempt identifier
`userId`	string	Target user
`email`	string	Login email used
`ipAddress`	string	Client IP
`userAgent`	string	Browser info
`deviceInfo`	object	Device details
`location`	object	Geo-location
`successful`	boolean	Success/failure
`failureReason`	string	Why it failed
`mfaRequired`	boolean	MFA was needed
`mfaVerified`	boolean	MFA passed
`createdAt`	datetime	Attempt time

Failure reasons

Reason	Description
`invalid_credentials`	Wrong password
`account_locked`	Too many failures
`account_disabled`	Account deactivated
`mfa_failed`	MFA verification failed
`session_expired`	Token expired
`device_not_trusted`	Device blocked

Account lockout

Setting	Default	Description
Max attempts	5	Failures before lock
Lockout duration	30 min	How long locked
Reset window	15 min	Window for counting

When locked:

User sees "Account temporarily locked"
Admin can unlock in user profile
Auto-unlocks after duration

Part 3: Multi-factor authentication

MFA adds a second verification layer after password authentication.

MFA properties

Field	Type	Description
`id`	string	MFA config ID
`userId`	string	User ID
`methodType`	enum	MFA method
`status`	enum	Method status
`deviceName`	string	Device label
`phoneNumber`	string	For SMS method
`email`	string	For email method
`secret`	string	TOTP secret
`lastUsedAt`	datetime	Last verification
`createdAt`	datetime	Setup date

MFA method types

Type	Description	Use case
`totp`	Time-based one-time password	Most secure, recommended
`sms`	SMS code to phone	Convenient, less secure
`email`	Code sent to email	Fallback option
`backup_codes`	One-time recovery codes	Emergency access

MFA device statuses

Status	Description
`pending`	Setup not complete
`active`	Ready for use
`suspended`	Temporarily disabled
`revoked`	Permanently disabled

MFA setup flow

TOTP (Authenticator app):

1. User initiates MFA setup
          │
          ▼
2. System generates secret
          │
          ▼
3. Display QR code
   ┌─────────────┐
   │ ▄▄▄ ▄ ▄ ▄▄▄ │
   │ ▄ ▄ ▄▄▄ ▄ ▄ │  ← Scan with app
   │ ▄▄▄ ▄ ▄ ▄▄▄ │
   └─────────────┘
          │
          ▼
4. User scans with authenticator
          │
          ▼
5. User enters 6-digit code
          │
          ▼
6. System verifies code
          │
          ▼
7. MFA enabled ✓

SMS/Email:

1. User initiates setup
          │
          ▼
2. Enter phone/email
          │
          ▼
3. System sends code
          │
          ▼
4. User enters code
          │
          ▼
5. MFA enabled ✓

MFA setup response

Field	Description
`mfaId`	Configuration ID
`method`	Method type
`qrCode`	QR code data URI (TOTP)
`secret`	Manual entry secret
`backupCodes`	Recovery codes

Setting up TOTP

Navigate to Profile → Security or Users → [User] → Security
Click Enable MFA or Add Method
Select Authenticator App
Scan QR code with:
- Google Authenticator
- Microsoft Authenticator
- Authy
- 1Password
Enter 6-digit code from app
Save backup codes securely
MFA is now active

Setting up SMS

Navigate to Profile → Security
Click Enable MFA
Select SMS
Enter phone number
Click Send Code
Enter received code
MFA is now active

Backup codes

Backup codes are one-time recovery codes generated during MFA setup:

10 codes generated by default
Each code can only be used once
Store securely offline
Regenerate if compromised

Using backup code:

At MFA prompt, click Use backup code
Enter one of your codes
Code is consumed
Check remaining codes

MFA verification flow

Login with password
        │
        ▼
  MFA Required?──── No ────→ Session Created
        │
       Yes
        │
        ▼
  Select Method
        │
        ▼
 ┌──────┴──────┐
 │             │
TOTP      SMS/Email
 │             │
 ▼             ▼
Enter code  Send code
from app    to device
 │             │
 └──────┬──────┘
        │
        ▼
  Verify Code
        │
        ▼
 Session Created

Admin MFA management

Administrators can:

Action	Description
View status	See user's MFA methods
Reset MFA	Remove all MFA methods
Generate codes	Issue new backup codes
Require MFA	Enforce MFA for user

Part 4: Device trust

Device trust classifies devices based on security posture and allows restricting access to trusted devices only.

Trusted device properties

Field	Type	Description
`id`	string	Device ID
`userId`	string	Owner user
`tenantId`	string	Tenant ID
`name`	string	Device name
`fingerprint`	object	Device fingerprint
`trustLevel`	number	Trust score (1-3)
`status`	enum	Device status
`lastUsedAt`	datetime	Last access
`lastLocation`	object	Last location
`isPrimary`	boolean	Primary device
`compromised`	boolean	Flagged as compromised
`compromisedAt`	datetime	When flagged
`compromisedReason`	string	Why flagged

Trust levels

Level	Name	Description
1	Low	New/unverified device
2	Medium	Verified but not fully trusted
3	High	Fully trusted device

Device fingerprint components

Component	Description
`userAgent`	Browser/OS string
`screenResolution`	Screen dimensions
`timezone`	Device timezone
`language`	Browser language
`platform`	OS platform
`hardwareConcurrency`	CPU cores
`deviceMemory`	Available memory
`touchSupport`	Touch capabilities

Device statuses

Status	Description
`active`	Device is active
`suspended`	Temporarily blocked
`revoked`	Permanently removed

Device management actions

Action	Description
View devices	List all trusted devices
Trust device	Add to trusted list
Revoke device	Remove from trusted
Set trust level	Change trust score
Flag compromised	Mark as compromised

Managing trusted devices

Navigate to Profile → Security → Devices or Foundation → Security → Device Trust
View list of devices:
- Device name/type
- Trust level badge
- Last used time
- Location
Actions available:
- Trust new device
- Revoke device
- Set as primary

Trusting a new device

When logging in from new device:

Login from new device
         │
         ▼
 Device fingerprint captured
         │
         ▼
    Trust check
         │
    ┌────┴────┐
    │         │
 Known     Unknown
 device     device
    │         │
    ▼         ▼
 Continue   Prompt:
            "Trust this device?"
                  │
          ┌───────┴───────┐
          │               │
         Yes             No
          │               │
          ▼               ▼
     Add to list     One-time
     Trust = 1        access

Compromise detection

Devices can be flagged as compromised:

Automatic detection:

Login from unusual location
Multiple failed MFA attempts
Suspicious activity patterns

Manual flagging:

Admin marks device
User reports device lost/stolen

When compromised:

All sessions from device terminated
Device blocked from new logins
Alert sent to user and admins

Device trust policies

Organizations can enforce:

Policy	Description
Require trusted device	Only allow trusted devices
Minimum trust level	Require level 2+ for sensitive ops
Max devices per user	Limit concurrent devices
Auto-revoke inactive	Remove unused devices

Security dashboard

The security module provides a dashboard view:

Overview metrics

Metric	Description
Active sessions	Current logged-in users
MFA adoption	% users with MFA enabled
Failed logins	Recent failures (24h)
Locked accounts	Currently locked users
Trusted devices	Total trusted devices
Compromised devices	Flagged devices

Recent activity

Recent login attempts
Session terminations
MFA changes
Device trust changes

Permissions required

Action	Required permission
View own sessions	(Self-service)
Terminate own session	(Self-service)
View all sessions	`sessions.view`
Terminate any session	`sessions.terminate`
View own MFA	(Self-service)
Manage own MFA	(Self-service)
View user MFA	`mfa.view`
Reset user MFA	`mfa.manage`
View own devices	(Self-service)
Manage own devices	(Self-service)
View all devices	`devices.view`
Manage devices	`devices.manage`

Best practices

Session security

Set appropriate session timeouts
Enable idle timeout
Review active sessions regularly
Terminate sessions on role change

MFA enforcement

Require MFA for all admin accounts
Encourage TOTP over SMS
Store backup codes securely
Review MFA status quarterly

Device trust

Limit devices per user
Require re-verification periodically
Remove inactive devices
Respond to compromise alerts promptly

Troubleshooting

Session terminated unexpectedly

Causes:

Idle timeout reached
Admin terminated session
Security policy triggered
Token refresh failed

Fix:

Re-authenticate
Check security settings
Contact admin if recurring

MFA code not working

Causes:

Clock out of sync (TOTP)
Code expired
Wrong method selected
Device time incorrect

Fix:

Sync device time
Wait for new code
Try backup code
Contact admin for reset

Device not recognized

Causes:

Browser updated
Cookies cleared
Incognito mode
VPN changed location

Fix:

Trust device when prompted
Don't use incognito for regular access
Maintain consistent VPN usage

Cannot add MFA method

Causes:

Method already configured
Phone number invalid
Email not verified

Fix:

Remove existing method first
Verify phone format
Verify email address

Identity & access management — Users, roles, permissions
Audit & compliance — Activity logging
Security overview — Security architecture

Navigation path​

Security architecture​

Part 1: Sessions​

Session properties​

Session statuses​

Device types​

Session management actions​

Bulk session operations​

Session filters​

Viewing active sessions​

Terminating sessions​

Part 2: Login attempts​

Login attempt properties​

Failure reasons​

Account lockout​

Part 3: Multi-factor authentication​

MFA properties​

MFA method types​

MFA device statuses​

MFA setup flow​

MFA setup response​

Setting up TOTP​

Setting up SMS​

Backup codes​

MFA verification flow​

Admin MFA management​

Part 4: Device trust​

Trusted device properties​

Trust levels​

Device fingerprint components​

Device statuses​

Device management actions​

Managing trusted devices​

Trusting a new device​

Compromise detection​

Device trust policies​

Security dashboard​

Overview metrics​

Recent activity​

Permissions required​

Best practices​

Session security​

MFA enforcement​

Device trust​

Troubleshooting​

Session terminated unexpectedly​

MFA code not working​

Device not recognized​

Cannot add MFA method​

Related documentation​

Navigation path

Security architecture

Part 1: Sessions

Session properties

Session statuses

Device types

Session management actions

Bulk session operations

Session filters

Viewing active sessions

Terminating sessions

Part 2: Login attempts

Login attempt properties

Failure reasons

Account lockout

Part 3: Multi-factor authentication

MFA properties

MFA method types

MFA device statuses

MFA setup flow

MFA setup response

Setting up TOTP

Setting up SMS

Backup codes

MFA verification flow

Admin MFA management

Part 4: Device trust

Trusted device properties

Trust levels

Device fingerprint components

Device statuses

Device management actions

Managing trusted devices

Trusting a new device

Compromise detection

Device trust policies

Security dashboard

Overview metrics

Recent activity

Permissions required

Best practices

Session security

MFA enforcement

Device trust

Troubleshooting

Session terminated unexpectedly

MFA code not working

Device not recognized

Cannot add MFA method

Related documentation