Multi-factor authentication

The Multi-factor Authentication (MFA) modules require you to solve a second challenge after you provide your password.

A password can be compromised in a number of ways, for example, it can be guessed if it is a simple password. MFA provides a second level of defense by requiring:

something you know, like your username and password, and
something you have, like a one-time password sent to your phone.

You can use MFA with any of the other authentication providers. If more than one MFA module is enabled, you can choose one when you log in.

You can turn MFA on and off in the profile page for your user account.

Available MFA modules

Time-based One-Time Password MFA module

Time-based One-Time Password (TOTP) is widely adopted in modern authentication systems.

Open Peer Power generates a secret key which is synchronized with an app on your phone. Every thirty seconds or so the phone app generates a random six digit number. Because Open Peer Power knows the secret key, it knows which number will be generated. If you enter the correct digits, then you’re in.

Setting up TOTP

Enable TOTP in your configuration.yaml like this:

openpeerpower:
  auth_mfa_modules:
    - type: totp

If no auth_mfa_modules configuration section is defined in configuration.yaml a TOTP module named “Authenticator app” will be autoloaded.

You will need an authenticator app on your phone. We recommend either Google Authenticator or Authy. Both are available for iOS or Android.

After restarting Open Peer Power, go to your profile page and there should be a “Multi-factor Authentication Modules” section.

Click Enable and a new secret key will be generated. Go to your phone app and enter the key, either by scanning the QR code or typing in the key below the QR code manually.

Screenshot of setting up multi-factor authentication

Please treat the secret key like a password - never expose it to others.

Your phone app will now start generating a different six-digit code every thirty seconds or so. Enter one of these into Open Peer Power under the QR code where it asks for a Code. Open Peer Power and your phone app are now in sync and you can now use the code displayed in the app to log in.

Using TOTP

Once TOTP is enabled, Open Peer Power requires the latest code from your phone app before you can log in.

TOTP is _time based_ so it relies on your Open Peer Power clock being accurate. If the verification keeps failing, make sure the clock on Open Peer Power is correct.

Notify multi-factor authentication module

The Notify MFA module uses the notify component to send you an HMAC-based One-Time Password. It is typically sent to your phone, but can be sent to any destination supported by a notify service. You use this password to log in.

Setting up MFA notify

Add Notify MFA to your configuration.yaml file like this:

# Example configuration, with a message template.
openpeerpower:
  auth_mfa_modules:
    - type: totp
      name: Authenticator app
    - type: notify
      message: 'I almost forget, to get into my clubhouse, you need to say {}'

After restarting Open Peer Power, go to your profile page and there should be a “Multi-factor Authentication Modules” section. Click Enable on the Notify One-Time Password option.

Try logging out, then logging in again. You will be asked for the six-digit one-time password that was sent to your notify service. Enter the password to log in.

If the validation failed, a new one-time password will be sent again.

The Notify MFA module can't tell if the one-time password was delivered successfully. If you don't get the notification, you won't be able to log in. You can disable the Notify MFA module by editing or removing the file `[your_config_dir]/.storage/auth_module.notify`.