 » System » Configure 2FA TOTP & Google Authen!

cator

Configure 2FA TOTP & Google

Authenticator
This how-to will show you how to setup a One-!me Password 2 Factor
Authen!ca!on using OPNsense and Google’s Authen!cator. All services of
OPNsense can be used with this 2FA solu!on.

 Note

To use the same feature with any !me based one-!me password token
just enter the seed into the field in step 3 instead of crea!ng a new seed.
The seed needs to be in base32 format.

Step 1 - Add New Authentication Server

To add a TOTP server go to System ‣ Access ‣ Servers and press Add server
in the top right corner. Then fill in the form as follows:

https://docs.opnsense.org/manual/how-tos/two_factor.html 17/03/2024 07 22
Page 1 sur 10
:
 Descrip!ve name TOTP Server Choose a server name

Type Local+Timebased One Time Password Select the TOTP server Type

Token length 6 6 for Google Authen!cator

Time window Leave Empty for Google Authen!ca

Grace period Leave Empty for Google Authen!ca

Step 2 - Install Google Authenticator

Go to the App Store of your pla"orm and search for Google Authen!cator.
Install using the normal procedure for your device.

Step 3 - Add or modify user

For this example we will create a new user, go to System ‣ Access ‣ Users and
click on the plus sign in the lower right corner.

Enter a Username and Password and fill in the other fields just as you would
do for any other user. Then select the Generate new (160bit) secret under
OTP seed.

When done press Save.

Step 4 - Activate Authenticator for this OTP

seed
To ac!vate your new OTP seed on the Google Authen!cator, first reopen the
user you just created by clicking on the pencil icon.

https://docs.opnsense.org/manual/how-tos/two_factor.html 17/03/2024 07 22
Page 2 sur 10
:
 Now it will show a QR code:

 Warning

Be very careful with the seed or QR code as this is the only thing you
need to calculate the token. KEEP YOUR SEED/QR CODE SAFE !

Now open your Google Authen!cator compa!ble applica!on and select the
op!on to start the configura!on and then scan the QR code or alterna!vely
enter the seed directly.

In case of SailOTP the configura!on works like this:

https://docs.opnsense.org/manual/how-tos/two_factor.html 17/03/2024 07 22
Page 3 sur 10
:
 Pull down to open the applica!on menu and choose the entry to add a new
Token.

https://docs.opnsense.org/manual/how-tos/two_factor.html 17/03/2024 07 22
Page 4 sur 10
:
https://docs.opnsense.org/manual/how-tos/two_factor.html 17/03/2024 07 22
Page 5 sur 10
:
 In the next step, you have to scan the previously created QR code by clicking
on the screen.

https://docs.opnsense.org/manual/how-tos/two_factor.html 17/03/2024 07 22
Page 6 sur 10
:
 When the QR code is scanned, a new view will open where you can see the
details of the result. This view can be used to check if the generated key and
OTP se#ngs of the scan results do match your se#ngs. Confirm if
everything is ok by clicking “Add”.

A$er this step, you will be back on the home screen of the app and will get a
Token for 30 Seconds.

Please note that there are many apps to generate the token. Some well
known are:

Name Pla"orm URL

FreeOTP Android, iOS h&ps://freeotp.github.io/

Google Authen!cator Android, iOS h&ps://www.google.com/landing/2step/

Step 5 - Test the token

For tes!ng the user authen!ca!on, OPNsense offers a simple tester. Go to
System ‣ Access ‣ Tester

Select the Authen!ca!on server you have configured, and enter the user
name. Then enter the *token + password, remember the order is token and
then password in the same field.

 Note

https://docs.opnsense.org/manual/how-tos/two_factor.html 17/03/2024 07 22
Page 7 sur 10
:
 Password field should be used to enter both token and your password,
like: Password: 123456PASSWORD when the default configura!on is
used. The OTP authen!ca!on server can also be configured to have it in
the reverse order like PASSWORD123456.

Hit the test bu&on and if all goes well you should see successfully
authen!cated.

Step 6 - Enable authentication server

Per default the system validates user creden!als against the “Local
Database”. In System ‣ Se#ngs ‣ Administra!on, sec!on Authen!ca!on you
should change this to your newly added authen!ca!on server to make sure
no local user can gain access without 2FA.

Note: Make sure you’ve tested your token!

https://docs.opnsense.org/manual/how-tos/two_factor.html 17/03/2024 07 22
Page 8 sur 10
:
 Step 7 - Using the token
To use the token in any applica!on/service that you have configured, just
open the Google Authen!cator and add the created token/key before your
regular password.

 Warning

Remember, you need to enter the token before or a#er you password
(depending on your configura!on)! And the password field should be used
to enter both token and your password, like: Password:
123456PASSWORD

The code will change every 30 seconds. Sample code:

https://docs.opnsense.org/manual/how-tos/two_factor.html 17/03/2024 07 22
Page 9 sur 10
:
https://docs.opnsense.org/manual/how-tos/two_factor.html 17/03/2024 07 22
Page 10 sur 10
: