Emmie

Appearance

Two-factor Authentication ​

Emmie allows both users and clients to apply two-factor authentication (or 2FA) to logging in, to further secure their accounts.

Setting up 2FA ​

The current flow for a user setting up 2FA is as follows:

  1. A user chooses to set up two-factor authentication
  2. A modal shows up: Register2FALoggedInUser.vue, prompting the user to choose between setting up an Authentication-app or a YubiKey.
  • A private key is automatically generated (or when one is already present from an earlier attempt, it will be fetched here) and saved in user_key_setups in the database. These keys are valid for 30 minutes before automatically being removed.
  1. Choosing a method.
  • Option A: The user chooses the Authentication-app. A QR code appears in the modal, the user scans this code with the the authenticator-app on their phone, and they copy the provided code from their phone to the input on screen. Their private key is sent in the request.
  • Option B: The user chooses the YubiKey. They insert their YubiKey into the computer they're logged in from, touch the key, then enter the code that appears on screen.
  1. If the code entered is correct, 2FA will be successfully set up. The next time the user logs in, they will need to use their chosen 2FA method to continue logging in. The authentication keys are stored in user_keys in the database.

Whenever the user attempts to log in, unless the global settings disabled 2FA entirely, the server will check user_keys for an active 2FA key. If one is present the user will be prompted to verify using their authentication method to complete log in.

Client 2FA ​

For clients the flow of setting up 2FA is the same, but with slightly different component names. The private keys are stored in client_key_setups and the connected authentication keys in client_keys.

Global settings ​

A customer may choose to require 2FA for every user account. When this is enabled, users who have not yet added a 2FA option to their account will be prompted to do so during login or when they activate their user account. The flow for this is the same as above. When the settings are set to 'optional', users can change this in their user profile. When 2FA is disabled entirely, users will not be able to set up their 2FA, nor will they be prompted to use it to log in. These settings do not affect client logins.

Known issues ​

There is a known issue with 2FA using the Authenticator-app when the system time does not match the used device's time. If you encounter this issue with running Emmie locally, make sure your system time is either set automatically with the correct timezone, or disable automatic date-time and sync the time with your phone manually. Since most phones sync their times automatically, the server time should also be set automatically, although sometimes the system time can be wrong by a few minutes. As long as the system time and the 2FA device time is the same, the problem should go away.