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.

---

Navigation path

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

---

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

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

Terminating sessions

Single session:

1. Find session in list
2. Click session row or ... menu
3. Select Terminate
4. Confirm termination

Multiple sessions:

1. Select sessions via checkboxes
2. Click Bulk Actions
3. Select Terminate
4. Confirm bulk termination

All sessions for user:

1. Navigate to user profile
2. Click Security tab
3. Click Terminate All Sessions
4. User must re-authenticate

---

Part 2: Login attempts

Login attempts track authentication events for security monitoring and account protection.

Login attempt properties

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):

SMS/Email:

1. User initiates setup
          |
          v
2. Enter phone/email
          |
          v
3. System sends code
          |
          v
4. User enters code
          |
          v
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

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

Setting up SMS

1. Navigate to Profile -> Security
2. Click Enable MFA
3. Select SMS
4. Enter phone number
5. Click Send Code
6. Enter received code
7. 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:

1. At MFA prompt, click Use backup code
2. Enter one of your codes
3. Code is consumed
4. Check remaining codes

MFA verification flow

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

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

Trusting a new device

When logging in from new device:

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:

1. Re-authenticate
2. Check security settings
3. Contact admin if recurring

MFA code not working

Causes:

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

Fix:

1. Sync device time
2. Wait for new code
3. Try backup code
4. Contact admin for reset

Device not recognized

Causes:

• Browser updated
• Cookies cleared
• Incognito mode
• VPN changed location

Fix:

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

Cannot add MFA method

Causes:

• Method already configured
• Phone number invalid
• Email not verified

Fix:

1. Remove existing method first
2. Verify phone format
3. Verify email address

---

Related documentation

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