Unix Server Tech Knowledge Base

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== TOTP Authentication in OPNSense ======

Time based One Time Password authentication [[https://en.wikipedia.org/wiki/Time-based_one-time_password|Wikipedia]] has become more commonly used in Multi-Factor Authentication (MFA) for additional security in various areas. Generally used by authenticators such as [[https://freeotp.github.io/|FreeOTP]], [[https://www.microsoft.com/en/security/mobile-authenticator-app|Microsoft Authenticator]], [[https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2|Google Authenticator]] and many more. My preference is FreeOTP due to the ability to back up the configuration without having to use a proprietary system.

OPNSense has supported TOTP for several years, and we will discuss how to set it up. I will be using [[https://opnsense.org/|OPNSense]] v25.01.12, and offering a script we wrote to deploy the QR Codes most authenticators prefer.

We are mainly focused on using MFA, using TOTP with an authentication for Road Warrior VPN access.

===== Set up authentication in OPNSense =====

  - Log into your OPNSense router as a user with administrative permissions
  - Go to System | Access | Users
    - For each user
      - Edit Account
      - Scroll down to OTP seed
      - Click "Show" (older versions did not require this step)
      - Click the gear box to (re)generate an OTP Seed
      - Click Save
  - Go to System | Access | Users
    - Select a user you know the password to
    - Click "Show" on the OTP seed
    - Scan the displayed QR Code into the authenticator app on your device
  - Go to System | Access | Servers
    - Click plus sign to create new server
    - Descriptive Name: Something that readily identifies this, such as TOTP
    - Type: Local+Timebased One Time Password
    - Token length: 6 (Microsoft compatible)
    - Time Window: 30
      - this is the default, but I like to see what the value is, so I enter it
      - This defines what the window is. So, if your authenticator changes numbers in the middle of you typing it in, this defines if you have to reenter it
    - Grace period: 10 (same as above, it is the default)
      - this is the default, but I like to see what the value is, so I enter it
      - Again, this is kind of like Time Window, but appears to be the difference in time between your authenticator and the server. Increasing this is less secure, but allows for an easier match
    - Click Save
  - Go to System | Access | Tester
    - Authentication Server: Select the one you just created
    - Username: enter the username for an account
    - Get a code from your authenticator
    - Password: ######password
      - ###### is the six (or eight, if you chose that) digit code given by the authenticator
      - password is the normal password
    - Click Test

===== Implement TOTP in test mode =====

Assuming all is good, you have set up authentication. Now, you need to implement it.

  - Go to System | Settings | Administration
  - Near bottom, set Server to both your Local Database and the one you created earlier
  - (Optional) Set User OTP seed to the groups who should be able to request a new OTP seed
  - Click Save

Attempt to log in from a second session. If it all works, you are now authenticating with and without TOTP. Try logging in with just the password, and with the TOTP Authenticator token preceding the password (//######password//)

===== Full Testing =====

<WRAP center round important 60%>
The QR Code is sensitive information. Anyone with access to the OTP Seed can use any Authenticator app to calculate the correct TOTP code. Treat this as the same level of sensitivity as you would passwords.
</WRAP>
Ensure all of your users have their TOTP Authenticator working. There is no simple way I have found to get the QR Code to everyone. For just a few people, you can simply go to System | Access | Users, right click on their QR Code and put it where they can scan it into their Authenticator app.

For larger numbers of end users, I wrote a pair of scripts that will scan an OPNSense configuration file and create the QR Codes for each user. The user accesses the web page, enters their OPNSense username and password, and the QR Code is displayed for them.

Be aware of the security concerns if you use this script. Read the README.md file. The scripts can be downloaded via Subversion at
<code bash>
svn co http://svn.dailydata.net/svn/web_pages/trunk/totp_opnsense
</code>
The README.md file contains full instructions on usage.

===== Deployment =====

<WRAP center round alert 60%>
Warning: Once this step is done, you will not be able to access VPN or the WebUI without TOTP Authentication. You will, however, be able to ssh into the router and recover the previous configuration file.
</WRAP>


To deploy, simply remove (uncheck) Local Database for the Authentication Server.
  - Open System | Settings | Administration
  - Scroll to Authentication | Server
  - Click the server dropdown
  - uncheck //Local Database//
  - Click Save

===== Usage =====

Some VPN clients have configurations for TOTP, but each is different. All it does is prepend the TOTP code you enter to the password, so if your client does not have a separate field, you can simply prepend the six digit TOTP to your normal password. Once I have tested more, I may update this document for various OpenVPN clients.