Back in 2019, I wrote “Using Time-Based One-Time Passwords for Two-Factor Authentication“, explaining how to allow a server written in C# to generate and verify codes in sync with authenticator apps. In this article, I’ll show how to do the same thing in Go.
How It Works
Logins that use Two-Factor Authentication (2FA) typically rely on the user’s password as the first factor, as well as a second factor that could be anything from an email/SMS to something biometric. Among all these options, the Time-Based One-Time Password (TOTP) protocol is a simple way to provide the benefits of 2FA without the disadvantages of other options (such as SMS gateways being unreliable and expensive, and biometrics being complex to implement).
The way TOTP works is that the client and server each generate a code, and these have to match. The codes are generated based on a shared secret and the current time, so as long as the client and server are using the same secret and generate the codes at roughly the same time, they will match.
The client usually takes the form of an authenticator app – such as Google Authenticator, Microsoft Authenticator, or Authy – on a mobile device. Once it acquires the shared secret from the server – typically by scanning a QR code – it then generates codes every 30 seconds. Usually the server will accept that code during these 30 seconds and also for an additional 30 seconds while the next code is displayed.
This might all sound a little abstract, but it will become clear shortly once we go through implementing TOTP on the server side and testing it out.
TOTP in Go – Getting Started
Before looking at TOTP, let’s first do the usual steps to create a simple program in Go:
- Create a new folder, e.g. go-otp
- Create a new file in it, e.g. main.go
- Run
go mod init main - Add a basic program stub:
package main
func main() {
}
In this article, we’ll be using the excellent otp library by Paul Querna. Install it as follows:
go get github.com/pquerna/otp
Now we can start adding code in that main() function.
Generating a Shared Secret (Server Side)
To generate a shared secret, you call totp.Generate(), passing in a totp.GenerateOpts object. The Issuer and AccountName are required, and you can set other options if you need to.
// generate shared secret
options := totp.GenerateOpts{
Issuer: "My Web Application",
AccountName: "me@example.com",
}
key, err := totp.Generate(options)
if err != nil {
fmt.Println("Failed to generate shared secret: ", err)
return
}
In order to do something with that key object, you have to convert it to base32, and you do that by simply calling its Secret() method:
secret := key.Secret()
fmt.Println(secret)
The output will change every time you run this, but the following is an example of what it looks like. In a real implementation, this would be saved in a database for each user.
QS4MXEE5AKT5NAIS74Z2AT3JPAGNDW7V
Generating QR Codes (Server Side)
The next step is to transmit the shared secret to the user. Normally, at some point during the registration process, the server generates the shared secret for the user, and sends it to the frontend, which displays it as a QR code. The user then scans the QR code with their authenticator app.
Although the server has no need to generate QR codes, it’s useful to do this for testing purposes, and it’s certainly faster than typing in the shared secret manually (which apps usually allow as a fallback option).
The otp library’s example code shows how to generate a QR code from the shared secret. Adapting this example a little, we get:
// generate QR code
var buf bytes.Buffer
img, err := key.Image(200, 200)
if err != nil {
fmt.Println("Failed to save QR code: ", err)
return
}
png.Encode(&buf, img)
os.WriteFile("qr-code.png", buf.Bytes(), 0644)
Running this code generates a neat little QR code:
Acquiring the Shared Secret (Client Side)
We can now pass the QR-encoded secret to the client. For this, we’ll need an authenticator app. Google Authenticator, Microsoft Authenticator and Authy should all work, but I personally prefer the latter because of its cloud backup feature, which is handy if your phone dies or goes missing.
Once the app is installed, locate the option to add a new account, after which you’ll be able to add a shared secret either by scanning a QR code or typing it manually. Excuse the quality of the next two pictures; none of these authenticator apps allow screenshots to be taken, so the closest thing I could do was take a photo with another phone.
Generating Authenticator Codes (Client Side)
Once your app has acquired the shared secret, it will automatically start generating 2FA codes, typically six digits long at 30-second intervals:
Alternatively, for testing purposes or if you need to develop a client with similar functionality, you can generate similar 2FA codes using the otp library itself. To do this, simply call totp.GenerateCode(), passing in the shared secret you generated earlier, and the current time:
// generate 2FA code
secondFactorCode, err := totp.GenerateCode(secret, time.Now())
if err != nil {
fmt.Println("Failed to generate 2FA code: ", err)
return
}
fmt.Println(secondFactorCode)
The output is the same kind of six-digit 2FA code that you’d get with an authenticator app, for instance:
605157
In fact, if you run this while you also have the authenticator app set up, you’ll see the exact same codes.
Validating 2FA Codes (Server Side)
To complete the second factor part of the login process, a user grabs a 2FA code from their authenticator app and enters it in the prompt in the web application’s frontend, essentially sending it over to the server. The server’s job is to ensure that the code is valid. The otp library allows us to do this validation using the totp.Validate() function, which takes the input 2FA code, and the shared secret from earlier.
In order to test how this behaves over a period of time, we can do a little infinite loop that requests 2FA codes from the user and then validates them:
for {
fmt.Print("Enter 2FA code: ")
var input2faCode string
fmt.Scanln(&input2faCode)
codeIsValid := totp.Validate(input2faCode, secret)
fmt.Println("Code is valid: ", codeIsValid)
}
While playing with this, you’ll notice that:
- Entering a code shown by the authenticator app returns true
- Entering the same code twice returns true
- Entering the same code still returns true within 30 seconds after it has stopped displaying in the authenticator app
- Entering the same code after that returns false
- Entering anything else (other than the current or previous code) returns false
In theory, you should prevent the application from accepting the same code twice, because they’re supposed to be one-time-passwords. To do this, you’ll need to add additional state and logic to your application. Or, you can accept the security tradeoff knowing that the 2FA codes are only valid for a minute, giving little opportunity for an attacker to exploit them.
Summary
My earlier article showed how easy it is to work with 2FA codes using a TOTP library in C#, and in Go it’s no different. After generating a secret from the otp library, you can either share it with your authenticator app (e.g. by generating a QR code) to generate 2FA codes, or use it to generate 2FA codes directly. The library also allows you to validate the generated 2FA codes, assuming they are valid for two 30-second windows.
In the interest of simplicity, I’ve only shown basic usage of the library. If you have more complex requirements, you can customise the generation of secrets, generation of 2FA codes, and also the validation of 2FA codes.
Finally, one thing to keep in mind is that 2FA becomes a major headache when one of the factors goes missing (e.g. phone is lost or stolen). So you’ll need to consider how to handle this situation (e.g. recovery codes, reset shared secret, etc.), and how to handle normal password resets (you may want to reset the shared secret too).
