Two-Factor Authentication (2FA/TOTP)

Relevant source files

The following files were used as context for generating this wiki page:

• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/totp/AuthenticTOTPProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/tfa/TwoFactorAuthCommand.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/totp/TOTPProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/tfa/TwoFactorConfirmCommand.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/authorization/AuthenticAuthorizationProvider.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/totp/TOTPData.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java

# Two-Factor Authentication (2FA/TOTP)

NexAuth integrates Time-based One-Time Password (TOTP) as a two-factor authentication method, allowing players to secure their accounts using authenticator applications like Google Authenticator or Authy. This feature adds a critical layer of security by requiring a time-sensitive code in addition to the user's password.

The system is designed to be enabled and configured on a per-user basis through in-game commands. It leverages the dev.samstevens.totp library for handling the core TOTP logic, including secret generation, QR code creation, and code verification. The display of the QR code in-game requires the Protocolize plugin to be installed.

Sources: README.md, ConfigurationKeys.java:214-220, AuthenticTOTPProvider.java:16-29

Configuration

The 2FA/TOTP feature can be configured in the main config.yml file. The primary switch for the entire feature is totp.enabled. If this is set to false, the TOTP provider and related commands will not be initialized.

Sources: AuthenticNexAuth.java:260-268, ConfigurationKeys.java:214-220

Key	Type	Default	Description
totp.enabled	Boolean	true	Enables or disables the entire TOTP-based 2FA feature.
totp.label	String	"NexAuth Network"	The issuer label displayed in the authenticator app. This should be set to the server or network name.
totp.delay	Integer	1000	The delay in milliseconds before the QR code map is shown to the player. This can be increased if the map disappears too quickly.

Sources: ConfigurationKeys.java:222-237, ConfigurationKeys.java:310-315

Architecture and Core Components

The TOTP system is built upon a few key interfaces and classes that separate the API from the implementation.

• TOTPProvider (API): An interface that defines the contract for TOTP operations: generating TOTPData (for a new setup) and verifying a given code against a secret.
• AuthenticTOTPProvider (Implementation): The concrete implementation of TOTPProvider. It uses the dev.samstevens.totp library to perform its functions. It generates secrets, creates QR code data, and verifies codes.
• TOTPData (API): A simple record that holds the generated QR code as a BufferedImage and the associated secret String.
• AuthenticAuthorizationProvider: This class manages the 2FA state for players. It tracks which players are currently in the process of setting up 2FA using an awaiting2FA map, which stores the player and their generated secret.
• ImageProjector: An interface responsible for displaying images to players in-game. For TOTP, this is used to show the QR code. The system requires a concrete implementation (like one using Protocolize) to function.

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/totp/TOTPProvider.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/totp/AuthenticTOTPProvider.java, API/src/main/java/xyz/xreatlabs/nexauth/api/totp/TOTPData.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/authorization/AuthenticAuthorizationProvider.java:28-29, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:258-268

The following diagram illustrates the relationships between the main components of the TOTP system.

2FA Setup Flow (/2fa)

A player initiates the 2FA setup by running the /2fa command. This process generates a unique secret and a corresponding QR code for the player to scan.

1. The player must be authenticated (logged in) to start the setup.
2. The system checks that the player is not already in the middle of a 2FA setup.
3. A new secret and QR code are generated via TOTPProvider.generate().
4. The player's state is marked as awaiting2FA, and the secret is temporarily stored by the AuthenticAuthorizationProvider.
5. The player is moved to a limbo server to ensure they cannot interact with the main server during setup.
6. After a configured delay (totp.delay), the QR code is displayed to the player as a map in their inventory.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/tfa/TwoFactorAuthCommand.java:27-48, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/authorization/AuthenticAuthorizationProvider.java:166-176

The sequence diagram below details the setup flow.

2FA Confirmation Flow (/2faconfirm)

After scanning the QR code, the player must confirm the setup by entering a code from their authenticator app using the /2faconfirm command.

1. The player runs /2faconfirm <code>.
2. The system verifies that the player is in the awaiting2FA state.
3. The provided code is validated against the stored secret using TOTPProvider.verify().
4. If the code is correct, the secret is permanently saved to the player's user data in the database.
5. The player is kicked from the server with a message indicating that 2FA has been successfully enabled. They must then log in again, this time providing a TOTP code.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/tfa/TwoFactorConfirmCommand.java:25-47, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/authorization/AuthenticAuthorizationProvider.java:108-115

The confirmation flow is illustrated below.

Commands

The following commands are available for managing 2FA.

Command	Alias(es)	Permission	Description
/2fa	2fauth, 2fauthcode	nexauth.command.2fa (inferred)	Starts the 2FA setup process for the player. Generates and displays a QR code to be scanned.
/2faconfirm <code>		nexauth.command.2faconfirm (inferred)	Confirms the 2FA setup by verifying a code from the authenticator app.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/tfa/TwoFactorAuthCommand.java:16, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/tfa/TwoFactorConfirmCommand.java:16

Conclusion

The Two-Factor Authentication system in NexAuth provides a robust security enhancement for player accounts. By integrating a standard TOTP library and leveraging in-game commands, it offers a user-friendly way for players to enable 2FA. The functionality is dependent on both the dev.samstevens.totp library for backend logic and an image projection plugin like Protocolize for the in-game user interface, making it a well-integrated but modular feature.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/totp/AuthenticTOTPProvider.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:258-268