Skip to main content

Two-factor authentication (2FA)

2FA is mandatory for super admin users in the GovWifi admin site. It’s currrently optional for admin users.

We use the two_factor_authentication gem to integrate the Time-based One Time Password (TOTP) functionality with the existing Devise authentication modules.

2FA set up

The GovWifi admin site contains a custom set up step which differs from the presumptions of the two_factor_authentication gem.

Where 2FA is enforced for a user they will be presented with a set up step as they sign in.

A QR code will be generated for them. They need to scan this with an authenticator app.

Setting up 2FA

The Users::TwoFactorAuthenticationSetupController handles the generation of a QR code URI and saving the initial setup against the User model assuming they provide the correct TOTP.

For subsequent logins, when they have successfully entered the correct code the 2FA cookie is set to expire in 24 hours, meaning they will need to enter the relevant TOTP from the authenticator app again. This does not change the user session timeout set by Devise configuration, so authentication sessions will still expire after 1 hour.

Configuration options for 2FA

The two_factor_authentication gem comes with a number of configuration options which can be found in config/initializers/devise.rb.

config.max_login_attempts = 3  # Maximum second factor attempts count.
config.allowed_otp_drift_seconds = 30  # Allowed TOTP time drift between client and server.
config.otp_length = 6  # TOTP code length
config.remember_otp_session_for_seconds = 86400 # Time before browser has to perform 2fA again. Currently 24 hours.
config.otp_secret_encryption_key = ENV['OTP_SECRET_ENCRYPTION_KEY']
config.second_factor_resource_id = 'id' # Field or method name used to set value for 2fA remember cookie
config.delete_cookie_on_logout = false # Delete cookie when user signs out, to force 2fA again on login

OTP_SECRET_ENCRYPTION_KEY is configured via Terraform and different between staging and production environments, which means that different TOTP codes will be generated between environments.

Configuring how 2FA is enforced

The two_factor_authentication gem will enforce 2FA for all users by default. We control how 2FA is applied via the need_two_factor_authentication? method on the User model.
With this method we can include or exclude users from other organisations, it’s also possible to configure whether 2FA is necessary in specific environments.

Resetting 2FA

A super admin user can reset 2FA for any user, by going to that user’s organisation page and clicking on the ‘Reset 2FA’ button next to the user’s name under ‘Team’ section.

Admin users can reset 2FA for any user part of their own organisation, by going to ‘Team members’ page and clicking on the ‘Reset 2FA’ link next to the user’s name in the members listing.

The button or link to reset 2FA will only be shown against the names of users who have already configured 2FA.

This page was last reviewed on 10 January 2021. It needs to be reviewed again on 10 July 2021 by the page owner #govwifi .
This page was set to be reviewed before 10 July 2021 by the page owner #govwifi. This might mean the content is out of date.