Two-Factor Authentication (2FA)

Introduction

Two-Factor Authentication (2FA) using Time-based One-Time Password (TOTP) enhances login security for Eyeglass by requiring users to verify their identity using a second authentication factor. This feature significantly reduces the risk of unauthorized access resulting from compromised credentials while maintaining a simple and user-friendly login experience.

2FA strengthens enterprise-grade security by:

• Preventing unauthorized access from compromised credentials
• Improving customer trust and meeting compliance requirements
• Providing audit trails for security events
• Supporting industry-standard authenticator applications

Prerequisites

Supported Authenticator Applications

The 2FA implementation uses TOTP (Time-based One-Time Password) and supports the following authenticator application:

• Google Authenticator: Industry-standard TOTP authenticator app available for iOS and Android devices

User Prerequisites

Before enabling 2FA, ensure the following prerequisites are met:

• Active Directory Configuration: AD users should have a valid email address or UPN (User Principal Naming) configured that matches their email
• Mail Server Configuration: You must configure a mail server in Eyeglass for sending 2FA enrollment emails
• Authenticator App: Users must install Google Authenticator on their mobile device or workstation

System Prerequisites

• TOTP Library: The required TOTP validation library is installed automatically during system updates
• Encryption: 2FA secrets are stored encrypted at all times for security

User Exclusions

The following user types are automatically excluded from 2FA verification regardless of system configuration:

• Local Users: System-level local accounts are exempt from 2FA
• Administrator Role: Users with the Administrator role are excluded from 2FA requirements

info

This exclusion ensures that administrative access remains available even if 2FA systems experience issues, preventing lockout scenarios.

Configuration

Enable or Disable 2FA Globally

Use the igls command-line interface to manage the global 2FA status. By default, 2FA is enabled on the system.

Check 2FA Status

igls auth 2fa --command status

Enable 2FA

igls auth 2fa --command enable

Disable 2FA

igls auth 2fa --command disable

warning

Disabling 2FA reduces security by removing the second authentication factor. Only disable 2FA if absolutely necessary for troubleshooting or during maintenance windows.

Enforce 2FA for All Logins

By default, 2FA is not enforced, allowing users to opt-in to enrollment. When enforcement is enabled, all eligible users (excluding local and administrator accounts) must complete 2FA enrollment before accessing the system.

Enable 2FA Enforcement

igls auth 2fa --command enforce

Disable 2FA Enforcement

igls auth 2fa --command no-enforce

User Enrollment

Self-Service Enrollment

Users can enroll in 2FA during the login process if they have not yet configured their authenticator app.

Enrollment Workflow

1. Navigate to Login Page: Access the Eyeglass web interface login page.
2. Enter Credentials: Provide username and password.
3. Credential Validation: The system validates credentials against Active Directory or local authentication.
4. 2FA Prompt: If 2FA is enabled and not yet enrolled, the user sees an enrollment option.
5. Request Enrollment: Select 2FA Enrollment.
6. Email Delivery: The system sends an enrollment email with instructions and a QR code.
7. Configure Authenticator: Follow the email instructions to scan the QR code or enter the manual setup key.
8. Complete Login: Return to the login page and enter the TOTP code from the authenticator app.

Enrollment Email

The enrollment email contains:

• QR Code: Scan with Google Authenticator for automatic configuration.
• Manual Setup Key: Alternative text-based setup code for manual entry.
• Instructions: Step-by-step guidance for configuring the authenticator app.

tip

If the enrollment email fails to send, an error message is displayed. Users should contact their administrator for assistance with enrollment.

Administrator-Assisted Enrollment

Administrators can initiate 2FA enrollment for users who experience issues with self-service enrollment.

igls auth 2fa --command enroll --user <username> --mail <userEmail>

Parameters:

• --user <username>: The username of the user to enroll (required).
• --mail <userEmail>: The email address where enrollment instructions will be sent (required).

Upon successful enrollment:

Letter with enrollment has been sent to <userEmail>

If the email cannot be sent, an error message is displayed:

Failed to send enrollment email: <error details>
Postponed sent failure. If non-existed <userEmail> was used for enrollment or MailServers has some issues sending mail, administrator would get corresponded e-mail to the account registered with the mail server
Please troubleshoot mail server configuration or contact support

Login Workflow

2FA Disabled

1. User submits credentials (username and password).
2. If credentials are valid, access is granted without a 2FA prompt. If invalid, access is denied.

2FA Enabled (Not Enforced)

1. User submits credentials.
2. If credentials are invalid, access is denied. If valid, the system checks the user type.
3. A local user or Administrator role is granted access without a 2FA prompt. An Active Directory user's enrollment status is checked next.
4. If the user is not enrolled, they can request an enrollment email or skip enrollment (access is granted, since 2FA is not enforced).
5. If the user is enrolled, they're prompted for a TOTP code. A valid code grants access; an invalid code denies it.

2FA Enabled and Enforced

1. User submits credentials.
2. If credentials are invalid, access is denied. If valid, the system checks the user type.
3. A local user or Administrator role is granted access without a 2FA prompt. An Active Directory user sees the 2FA pop-up window.
4. If the user is not enrolled, they must complete the enrollment workflow — access is denied until enrollment is complete.
5. If the user is enrolled, they're prompted for a TOTP code. A valid code grants access; an invalid code denies it.

TOTP Code Validation

• Format: 6-digit numeric code.
• Time Window: Code is valid for 30 seconds (standard TOTP interval).
• Synchronization: System clock must be synchronized for accurate validation.

Reasons a code may be rejected:

• Incorrect Code: User entered wrong digits.
• Expired Code: Code is older than 30 seconds.
• Clock Skew: Time difference between authenticator device and Eyeglass system.
• Setup Error: Authenticator app not properly configured during enrollment.

warning

Multiple failed TOTP attempts may indicate a security issue. Contact your administrator if you consistently experience validation failures.

Audit Logging

All 2FA-related events are logged in a dedicated log file for security auditing and compliance purposes.

Logged Events

Event Code	Description	When Logged
2FA_SETUP_COMPLETE	User successfully completed 2FA enrollment	User successfully configured authenticator and verified first TOTP code
2FA_FAILED_SETUP	Enrollment process failed	Email delivery failed or setup process encountered errors
2FA_LOGIN_SUCCESS	Successful login with valid TOTP code	User successfully authenticated using 2FA
2FA_LOGIN_FAILED	Failed login attempt with invalid TOTP code	User provided incorrect or expired TOTP code

Log File Location

/opt/data/superna/sca/logs/apiaudit.log

Each log entry includes a timestamp, event code, username, source IP address (if applicable), result, and any additional error details or context.

Example Log Entries

2025-10-15T18:06:11,702 2FA_SETUP_COMPLETE user=jdoe@domain.com result=success
2025-10-10 14:45:22,567 2FA_LOGIN_FAILED user=jsmith@domain.com result=invalid_code
2025-10-10 15:01:45,163 2FA_LOGIN_SUCCESS user=bjones@domain.com result=success

Troubleshooting

Email Not Received

1. Verify the mail server is configured in Eyeglass.
2. Check the user's email address or UPN in Active Directory.
3. Verify the email is not in a spam or junk folder.
4. Contact an administrator for manual enrollment assistance.

TOTP Code Rejected

1. Verify system time on the Eyeglass appliance and user device are synchronized.
2. Ensure the temporary login session hasn't expired — refresh the page and re-submit credentials.
3. Ensure the user is entering the current code (not an expired one).
4. Try waiting for the next code cycle (30 seconds).
5. If the issue persists, re-enroll using administrator-assisted enrollment.

User Excluded from 2FA

1. Verify the user is not a local account (excluded by design).
2. Check if the user has the Administrator role (excluded by design).
3. Confirm 2FA is enabled globally using igls auth 2fa --command status.

Clock Skew Issues

1. Verify the Eyeglass appliance's system time using the date command.
2. Check NTP configuration for time synchronization.
3. Verify the user's device time is accurate.
4. TOTP validation typically tolerates ±1 time window of clock skew.

Best Practices

• Ensure all systems use NTP for accurate time synchronization.
• Provide clear documentation and training for users on 2FA usage.
• Test 2FA in a non-production environment before enforcing in production.
• Regularly review 2FA audit logs for suspicious activity.
• Ensure the mail server has high availability for the enrollment process.

Security Considerations

2FA is a supplement to, not a replacement for, strong password policies — maintain existing password complexity requirements and don't relax them once 2FA is enabled.

Users should secure their authenticator devices with a lock screen (PIN, biometric, etc.), keep the app updated, avoid sharing devices with 2FA configured, and report lost or stolen devices immediately.

2FA helps meet various compliance requirements, including NIST 800-63B, PCI DSS, HIPAA, SOX, and ISO 27001.

Technical Implementation

The 2FA implementation follows RFC 6238 (TOTP: Time-Based One-Time Password Algorithm):

• Algorithm: HMAC-SHA1 (configurable to SHA256/SHA512)
• Time Step: 30 seconds (standard interval)
• Code Length: 6 digits
• Window: Typically allows ±1 time step for clock skew tolerance

Secret keys are generated using user-specific data (username, email, unique identifier) combined with cryptographically secure random data, multiple encoding passes, and AES encryption for storage — ensuring secrets cannot be reconstructed or predicted.

Migration and Adoption

For organizations deploying 2FA for the first time, a gradual rollout is recommended:

1. Testing: Enable 2FA in a non-production environment. Test the enrollment workflow, verify authenticator app compatibility, and validate logging and audit capabilities.
2. Opt-In: Enable 2FA without enforcement in production. Allow users to voluntarily enroll, gather feedback, and monitor adoption rates.
3. Communication: Educate users before enforcement. Provide training materials, offer hands-on assistance, and set a clear enforcement date.
4. Enforcement: Enable 2FA enforcement. Require all eligible users to enroll, monitor for enrollment issues, and provide helpdesk support for user questions.

Summary

Two-Factor Authentication using TOTP significantly enhances the security of Eyeglass by requiring a second authentication factor beyond username and password. The implementation:

• Supports Google Authenticator for TOTP code generation
• Provides flexible configuration via the igls command-line interface
• Offers both self-service and administrator-assisted enrollment
• Enables comprehensive audit logging for compliance
• Excludes local and administrator accounts to prevent lockout scenarios