Google Authenticator (MFA/2FA)

EmpireAI makes use of the Google Authenticator PAM module to enable multi-factor/two-factor authentication. This requires users to provide two factors during the authentication process by requiring a one-time use code to be entered during authentication.

Registering a Google Authenticator

Current Process

When a user logs in via SSH a profile script is run that checks if the user has already configured the Google Authenticator for their account. If the user has not the script then runs the google_authenticator command with some pre-selected flags to add extra security and standardize the process by removing yes/no questions from the process.

A QR code will be printed on the screen for the user to scan, after which they will be prompted to enter the code displayed in their authenticator app. Any OTP app can work, such as Duo, Microsoft Authenticator, Google Authenticator, and many more.

Pending Changes

During February 2025 the use of multi-factor authentication to access Empire AI will be required rather than optional. It is strongly encouraged that new users complete the process to add an authenticator to their account before it is required.

Known Issues

• Users who answered the question "Do you want authentication tokens to be time-based?" question will almost certainly have problems using the authenticator. This changes the mode of the authenticator to be very confusing as codes can only be used in the order they are generated. Because of this the command to register an authenticator will not prompt users for this question.
• Authentication on Empire AI is two-step. When a SSH session is initiated the user will first be prompted for the authentication code, and will then prompted separately for their password. Some SSH clients or configurations will not properly handle this two-step process well. The main offender is MobaXTerm, which in some configurations will not prompt for the authenticator code and only prompt for a password. If you have registered an authenticator for your account and are not being prompted for a code please try another SSH client before sending in an email for support.