Two-factor authentication (2FA)
2FA is mandatory for admin users when signing into GovWifi admin.
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
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.
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
two_factor_authentication gem comes with a number of configuration options which can be found in
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
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.
Admins can reset 2FA for other admins who are part of their organisation.
If an admin user needs to reset their 2FA:
- The admin user can ask a team member to do it for them.
- The team member needs to sign into their GovWifi admin account, go to the ‘Team members’ section’ and select ‘Reset 2FA’ next to the user’s name.
- The admin user can then follow the link in the email they receive, and follow the instructions to set up 2FA again.
If this does not work, or if the admin does not have a team member who can do this for them, we have a manual process. This involves the GovWifi team setting up a video call with the admin and asking to see some ID. This is to be sure it’s really them trying to access GovWifi admin.
There’s a macro in Zendesk that you can use if an admin asks how to reset their 2FA.