Permify

How to Implement Two-Factor Authentication (2FA) with TOTP in Golang

In this tutorial, we will explore Two-Factor Authentication (2FA) using TOTP by implementing it in a Golang app.

Authentication is crucial for ensuring security and passwords alone are no longer sufficient to protect against unauthorized access. That's where Two-Factor Authentication comes in. By requiring users to provide two forms of identification, such as a password and a temporary code, 2FA significantly reduces the risk of unauthorized access.

In this tutorial, we will explore how to implement Two-Factor Authentication (2FA) in Golang.

Table Of Contents

Prerequisites

Before you begin implementing Two-Factor Authentication (2FA) in your Golang web application, ensure you have the following prerequisites in place:

  • Basic knowledge of Golang programming language.
  • Go development environment set up on your machine.
  • Familiarity with web development concepts such as HTTP requests and HTML templates.
  • A text editor or integrated development environment (IDE) for writing and editing Go code.

Let's start with understanding the basics of Two-Factor Authentication and how it works.

Understanding Two-Factor Authentication (2FA)

How 2FA Works

Two-Factor Authentication (2FA) adds an additional layer of security to the traditional username and password login process. It requires users to provide two forms of identification before granting access to their accounts. Let's understand how it works with a real-life scenario:

Online Banking:

  1. Single-Factor Authentication: Imagine logging into your online banking account with just your username and password. While this provides some level of security, it's vulnerable to password theft or hacking.
  2. Two-Factor Authentication (2FA): Now, let's add an additional step. After entering your username and password, instead of immediately gaining access, you receive a one-time code on your smartphone via a text message or a dedicated authentication app.
    • Something You Know (Password): Your regular username and password.
    • Something You Have (One-Time Code): The one-time code sent to your smartphone.
    So, to access your account, you not only need to know your password but also have access to your smartphone to retrieve the one-time code. Even if someone knows your password, they can't log in without also having your smartphone.

What is Time-Based One-Time Passwords (TOTP) ?

Time-Based One-Time Passwords (TOTP) is a common method used for implementing 2FA. TOTP generates a temporary six-digit code that changes every 30 seconds, providing an additional layer of security.

Here's how TOTP works:

  • Shared Secret: A unique secret key is shared between the user's device and the authentication server.
  • Time Synchronization: Both the user's device and the server use the current time to generate the one-time password.
  • Algorithm: TOTP uses a cryptographic algorithm, typically HMAC-SHA1, to generate the one-time password.
  • Validity Period: Each one-time password is valid for a short period, typically 30 seconds.

For example, when setting up TOTP for a user:

  • The server generates a secret key and shares it with the user's device.
  • The user's device uses this secret key along with the current time to generate the six-digit code.
  • When logging in, the user provides both their regular password and the current six-digit code generated by their device.
  • The server verifies the code by using the shared secret key and checking its validity within the time window.

Now, that you have basic understanding of 2FA and TOTP. Let's start implementing it in a Golang Web App.

Setting Up Your Golang Environment

To set up your Golang environment for implementing 2FA, follow these steps:

  1. Install Golang: If you haven't already, download and install Golang from the official website: https://golang.org/.

  2. Set Up Your Workspace: Create a directory for your Golang projects. For example:

    mkdir go-2fa-demo
cd go-2fa-demo

  3. Clone the Example Project: Clone the example project provided in this tutorial or create a new Golang project structure similar to the one shown below:

    go-2fa-demo/
├── main.go
├── templates/
│   ├── dashboard.html
│   ├── index.html
│   ├── login.html
│   ├── qrcode.html
│   └── validate.html

  4. Install Dependencies: This project uses a third-party library for generating TOTP (Time-Based One-Time Passwords). Install the library using the following command:

    go get github.com/pquerna/otp/totp

  5. Verify Installation: Ensure that your Golang environment is set up correctly by running the example project. Execute the following command in the terminal:

    go run main.go

    You should see a message indicating that the server is starting at port 8080.

Once you've completed these steps, your Golang environment will be ready for implementing Two-Factor Authentication in your web application.

Implementing Two-Factor-Authentication in Golang

In this section, we'll walk you through the process of implementing Two-Factor Authentication (2FA) in your Golang web application.

The below project is only for demonstration purposes; in production, the application would require additional security measures and features. The complete code of the project is provided in this GitHub repository.

Step 1: Choosing a 2FA Method

Choosing the right Two-Factor Authentication (2FA) method is crucial for ensuring the security of your application. There are several 2FA methods available, each with its own advantages and considerations. In this tutorial, we'll focus on implementing Time-Based One-Time Passwords (TOTP) using the Google Authenticator app as the authenticator.

Why TOTP?

Time-Based One-Time Passwords (TOTP) is a popular 2FA method widely adopted by many online services. Here's why TOTP is a good choice:

  • Security: TOTP generates temporary codes that expire after a short period, making them less susceptible to replay attacks.
  • Offline Capability: TOTP does not require an internet connection for code generation, allowing users to authenticate even when offline.
  • Standardization: TOTP is standardized under RFC 6238, ensuring compatibility with various authentication apps and libraries.
  • User-Friendly: TOTP codes are easy to generate and enter, providing a seamless user experience.

Considerations

Before implementing TOTP in your application, consider the following:

  • User Adoption: Ensure that your users are familiar with TOTP and comfortable using authentication apps like Google Authenticator.
  • Backup Mechanism: Provide users with backup codes in case they lose access to their authentication device.
  • Security vs. Convenience: Strike a balance between security and convenience by implementing additional security measures like rate limiting without compromising user experience.

Once you find a 2FA method suitable to your need, you can easily intergrate it to your web app using a library.

Step 2: Integrating 2FA Library

After choosing a 2FA method, the next step is to integrate a third-party library that provides functionality for generating and validating TOTP codes. In our example project, we're using the github.com/pquerna/otp/totp library.

The github.com/pquerna/otp/totp library is a popular choice for implementing TOTP in Golang applications. Here's why it's a preferred option:

  • Feature-Rich: The library provides comprehensive support for TOTP generation, validation, and customization.
  • Well-Maintained: Developed and maintained by a reputable author, the library receives regular updates and bug fixes.
  • Community Support: Being widely used in the Golang ecosystem, the library benefits from a supportive community and extensive documentation.

Installation

To integrate the github.com/pquerna/otp/totp library into your Golang project, use the following command:

go get github.com/pquerna/otp/totp

This command will download and install the library and its dependencies, making it ready for use in your application. Now, we are ready to start implementing the 2FA in our application.

Step 3: Setting Up Routes

Now, the next thing we have to do is set up the routes in our web app to handle the incoming requests. Setting up routes in your Golang web application is crucial for handling different HTTP requests and directing users to the appropriate handlers. In this section, we'll demonstrate how to set up routes in your project using the net/http package.

Importing Required Packages

Before defining routes, ensure you import the necessary packages:

import (
    "net/http"
)

Defining Routes

In the main.go file of your project, define routes using the http.HandleFunc() function. Each route corresponds to a specific URL path and is associated with a handler function that processes requests to that path.

func main() {
    // Define routes
    http.HandleFunc("/", homeHandler)
    http.HandleFunc("/login", loginHandler)
    http.HandleFunc("/dashboard", dashboardHandler)
    http.HandleFunc("/generate-otp", generateOTPHandler)
    http.HandleFunc("/validate-otp", validateOTPHandler)

    // Start the server
    http.ListenAndServe(":8080", nil)
}

In the above code:

  • http.HandleFunc(): This function registers a handler function for the given pattern (URL path). It takes two arguments: the URL pattern and the handler function to execute when a request matches the pattern.
  • Routes:
    • /: Handles requests to the root URL and directs users to the homepage.
    • /login: Handles login requests and processes user authentication.
    • /dashboard: Handles requests to access the dashboard after successful authentication.
    • /generate-otp: Handles requests to generate a One-Time Password (OTP) for Two-Factor Authentication (2FA).
    • /validate-otp: Handles requests to validate the OTP entered by the user during the 2FA setup or login process.

Step 4: Creating Homepage

The homepage serves as the entry point to your web application, providing users with initial information and navigation options. In this section, we'll create the homepage for our Golang web application and set up the corresponding handler function.

Template File

First, create an HTML template file named index.html in the templates directory of your project. This file will define the structure and content of the homepage.

<!-- templates/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Go 2FA Demo</title>
    <link rel="stylesheet" href="<https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css>">
</head>
<body>
<div class="container mt-5">
    <h1 class="mb-3">Welcome to the Go 2FA Demo</h1>
    <a href="/login" class="btn btn-primary">Login</a>
</div>
</body>
</html>

Handler Function

Next, define a handler function named homeHandler in your main.go file to render the homepage when users access the root URL.

func homeHandler(w http.ResponseWriter, r *http.Request) {
    // Execute the index.html template
    err := templates.ExecuteTemplate(w, "index.html", nil)
    if err != nil {
        http.Error(w, "Internal Server Error", http.StatusInternalServerError)
        return
    }
}

In the above code:

  • Template File: The index.html template defines the structure of the homepage using HTML markup. It includes a welcome message and a button to navigate to the login page.
  • Handler Function: The homeHandler function is responsible for handling requests to the root URL ("/"). It executes the index.html template and sends the rendered HTML content as the response.

Step 5: Creating Login Page

The login page is a crucial component of your web application, allowing users to authenticate and access protected resources. In this section, we'll create the login page for our Golang web application and set up the necessary handler function.

Template File

Begin by creating an HTML template file named login.html in the templates directory. This file will define the structure and content of the login page.

<!-- templates/login.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Login</title>
    <link rel="stylesheet" href="<https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css>">
</head>
<body>
<div class="container mt-5">
    <h1 class="mb-3">Login</h1>
    <form action="/login" method="post" class="needs-validation">
        <div class="form-group">
            <label for="username">Username:</label>
            <input type="text" id="username" name="username" class="form-control" required>
        </div>
        <div class="form-group">
            <label for="password">Password:</label>
            <input type="password" id="password" name="password" class="form-control" required>
        </div>
        <button type="submit" class="btn btn-success">Login</button>
    </form>
</div>
</body>
</html>

Handler Function

Next, define a handler function named loginHandler in your main.go file to render the login page and handle user authentication.

func loginHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method == "GET" {
        // Render the login.html template for GET requests
        err := templates.ExecuteTemplate(w, "login.html", nil)
        if err != nil {
            http.Error(w, "Internal Server Error", http.StatusInternalServerError)
            return
        }
        return
    }

    // Handle POST requests for user authentication
    // (Code for handling form submission and user authentication)
}

In the above code:

  • Template File: The login.html template defines the structure of the login page using HTML markup. It includes form fields for entering the username and password, along with a submit button for initiating the login process.
  • Handler Function: The loginHandler function is responsible for handling requests to the /login URL path. For GET requests, it renders the login.html template to display the login page. For POST requests, it will handle form submission and user authentication (to be implemented).

Step 6: Handling User Authentication

User authentication is a critical aspect of web applications, ensuring that only authorized users can access protected resources. In this section, we'll implement the logic for handling user authentication in our Golang web application.

Handler Function

In the loginHandler function of your main.go file, implement the logic to authenticate users based on the provided credentials.

func loginHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method == "GET" {
        // Render the login.html template for GET requests
        err := templates.ExecuteTemplate(w, "login.html", nil)
        if err != nil {
            http.Error(w, "Internal Server Error", http.StatusInternalServerError)
            return
        }
        return
    }

    // For POST requests, parse form data
    if err := r.ParseForm(); err != nil {
        http.Error(w, "Error parsing form", http.StatusBadRequest)
        return
    }

    // Retrieve username and password from the form data
    username := r.Form.Get("username")
    password := r.Form.Get("password")

    // Perform user authentication
    user, ok := users[username]
    if !ok || user.Password != password {
        // If authentication fails, redirect to the login page
        http.Redirect(w, r, "/login", http.StatusFound)
        return
    }

    // If authentication succeeds, redirect to the dashboard
    http.Redirect(w, r, "/dashboard", http.StatusFound)
}

In the above code:

  • Handler Function: The loginHandler function handles both GET and POST requests to the /login URL path. For GET requests, it renders the login page using the login.html template. For POST requests, it parses the form data to retrieve the username and password entered by the user.
  • User Authentication: Inside the POST request handling block, the function attempts to authenticate the user based on the provided credentials. It checks if the username exists in the users map and verifies that the password matches the stored password for the user. If authentication fails, the user is redirected back to the login page. If authentication succeeds, the user is redirected to the dashboard.

Step 7: Generating TOTP Secret

Generating a Time-Based One-Time Password (TOTP) secret is the initial step in setting up two-factor authentication (2FA) for your web application. In this section, we'll implement the functionality to generate a TOTP secret for each user.

Handler Function

Create a handler function named generateOTPHandler in your main.go file to handle the generation of TOTP secrets.

func generateOTPHandler(w http.ResponseWriter, r *http.Request) {
    // Retrieve username from the query parameters
    username := r.URL.Query().Get("username")

    // Retrieve user details from the in-memory "database"
    user, ok := users[username]
    if !ok {
        http.Redirect(w, r, "/", http.StatusFound)
        return
    }

    // Generate TOTP secret if not already generated
    if user.Secret == "" {
        secret, err := totp.Generate(totp.GenerateOpts{
            Issuer:      "Go2FADemo",
            AccountName: username,
        })
        if err != nil {
            http.Error(w, "Failed to generate TOTP secret.", http.StatusInternalServerError)
            return
        }
        user.Secret = secret.Secret()
    }

    // Construct the OTP URL for generating QR code
    otpURL := fmt.Sprintf("otpauth://totp/Go2FADemo:%s?secret=%s&issuer=Go2FADemo", username, user.Secret)

    // Prepare data to pass to the template
    data := struct {
        OTPURL   string
        Username string
    }{
        OTPURL:   otpURL,
        Username: username,
    }

    // Render the qrcode.html template with the OTP URL data
    err := templates.ExecuteTemplate(w, "qrcode.html", data)
    if err != nil {
        http.Error(w, "Internal Server Error", http.StatusInternalServerError)
        return
    }
}

In the above code:

  • Handler Function: The generateOTPHandler function handles requests to generate TOTP secrets for users. It retrieves the username from the query parameters, then checks if the user exists in the in-memory "database". If the user exists, it generates a TOTP secret using the totp.Generate function from the otp/totp package. The generated secret is stored in the user's data structure. If the secret is successfully generated, the function constructs an OTP URL for generating a QR code. Finally, it renders the qrcode.html template with the OTP URL data.

Step 8: Displaying QR Code

Displaying a QR code is a convenient way to enable users to set up two-factor authentication (2FA) using authenticator apps. We will create a seperate HTML file to display the QR code in our app.

Template File

Create an HTML template file named qrcode.html in the templates directory. This file will define the structure and content for displaying the QR code.

<!-- templates/qrcode.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>QR Code</title>
    <link rel="stylesheet" href="<https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css>">
</head>
<body>
<div class="container mt-5 text-center">
    <h1 class="mb-3">Scan QR Code with Authenticator App</h1>
    <img src="<https://chart.googleapis.com/chart?cht=qr&chl={{.OTPURL}>}&chs=180x180&choe=UTF-8&chld=L|2" class="img-fluid mb-3" alt="QR Code">
    <form action="/validate-otp" method="get">
        <input type="hidden" name="username" value="{{.Username}}">
        <button type="submit" class="btn btn-primary">I've Scanned the QR Code</button>
    </form>
</div>
</body>
</html>

In the above code:

  • Template File: The qrcode.html template defines the structure of the page for displaying the QR code. It includes an <img> tag to display the QR code image generated using the Google Chart API. Additionally, it provides a button for users to indicate that they have scanned the QR code with their authenticator app.

Step 9: Validating TOTP Code

Validating the Time-Based One-Time Password (TOTP) code submitted by users is important for ensuring the security of the two-factor authentication (2FA) process. In this section, we'll implement the functionality to validate the TOTP code entered by users.

Handler Function

Create a handler function named validateOTPHandler in your main.go file to handle the validation of TOTP codes.

func validateOTPHandler(w http.ResponseWriter, r *http.Request) {
    switch r.Method {
    case "GET":
        // Retrieve the username from the query parameters
        username := r.URL.Query().Get("username")

        // Render the validate.html template, passing the username to it
        err := templates.ExecuteTemplate(w, "validate.html", struct{ Username string }{Username: username})
        if err != nil {
            http.Error(w, "Internal Server Error", http.StatusInternalServerError)
        }

    case "POST":
        // Parse form data
        if err := r.ParseForm();

    err != nil {
            http.Error(w, "Error parsing form", http.StatusBadRequest)
            return
        }

    // Retrieve username and TOTP code from form data
    username := r.FormValue("username")
    otpCode := r.FormValue("otpCode")

    // Retrieve user details from the in-memory "database"
    user, exists := users[username]
    if !exists {
        http.Error(w, "User does not exist", http.StatusBadRequest)
        return
    }

    // Validate the TOTP code using the TOTP library
    isValid := totp.Validate(otpCode, user.Secret)
    if !isValid {
        // If validation fails, redirect back to the validation page
        http.Redirect(w, r, fmt.Sprintf("/validate-otp?username=%s", username), http.StatusTemporaryRedirect)
        return
    }

    // If validation succeeds, set a session cookie and redirect to the dashboard
    http.SetCookie(w, &http.Cookie{
        Name:   "authenticatedUser",
        Value:  "true",
        Path:   "/",
        MaxAge: 3600, // 1 hour for example
    })
    http.Redirect(w, r, "/dashboard", http.StatusSeeOther)

    default:
        http.Error(w, "Method Not Allowed", http.StatusMethodNotAllowed)
    }
}

In the above code:

  • Handler Function: The validateOTPHandler function handles both GET and POST requests. When a GET request is received, it retrieves the username from the query parameters and renders the validate.html template, passing the username to it.
  • When a POST request is received, it parses the form data to retrieve the username and the TOTP code submitted by the user. It then validates the TOTP code using the TOTP library. If the code is valid, it sets a session cookie to indicate successful authentication and redirects the user to the dashboard. If the code is invalid, it redirects the user back to the validation page for another attempt.

Step 10: Dashboard Handler

The dashboard handler is responsible for rendering the dashboard page once a user has successfully authenticated.

Handler Function

Create a handler function named dashboardHandler in your main.go file to handle dashboard requests.

func dashboardHandler(w http.ResponseWriter, r *http.Request) {
    // Retrieve the authenticated user's username from the session cookie
    username, err := r.Cookie("authenticatedUser")
    if err != nil || username.Value == "" {
        // If user is not authenticated, redirect to the homepage
        http.Redirect(w, r, "/", http.StatusFound)
        return
    }

    // Render the dashboard.html template
    err = templates.ExecuteTemplate(w, "dashboard.html", nil)
    if err != nil {
        http.Error(w, "Internal Server Error", http.StatusInternalServerError)
    }
}

In the above code:

  • Handler Function: The dashboardHandler function retrieves the authenticated user's username from the session cookie. If the user is not authenticated (i.e., the session cookie is not present or expired), it redirects the user to the homepage. If the user is authenticated, it renders the dashboard.html template to display the dashboard page.

Testing Your Two-Factor Authentication (2FA) Implementation

Testing your two-factor authentication (2FA) implementation is essential to ensure its robustness and effectiveness in enhancing security.

Running the Application and Testing

To run the application and test the 2FA implementation, follow these steps:

  1. Run the Application: Start the web server by running the main Go file using the go run command:

    cd go-2fa-demo
go run main.go

  2. Access the Application: Open a web browser and navigate to http://localhost:8080/ to access the application.

image-1-2fa

  1. Login: Click on the "Login" button to initiate the authentication process.

  2. Enter Credentials: Enter the username and password (e.g., "john" and "password") to proceed.

image-2-2fa

  1. Generate QR Code: After successful login, a QR code will be generated for TOTP setup. image-3-2fa

  2. Scan QR Code: Use a TOTP-compatible authenticator app, such as Google Authenticator, to scan the QR code and set up 2FA for the user account.

  3. Test Authentication: Enter the TOTP code generated by the authenticator app to verify successful authentication.

image-4-2fa

Google Authenticator

Google Authenticator is a widely used authenticator app that generates TOTP codes for 2FA authentication. It securely stores secrets and generates time-based codes, enhancing security for user accounts.

To set up Google Authenticator:

  1. Install the App: Download and install the Google Authenticator app from the App Store (iOS) or Google Play Store (Android).
  2. Add an Account: Open the app and select "Scan a QR code" or "Manual entry" to add a new account.
  3. Scan QR Code: Use the device's camera to scan the QR code displayed on the application's login page.
  4. Verify Setup: Once scanned, the app will display a six-digit TOTP code that refreshes every 30 seconds. Enter this code into the application to verify the setup.

Best Practices for Two-Factor Authentication (2FA)

Implementing two-factor authentication (2FA) in your Golang web application is an important step towards enhancing security. However, to ensure its effectiveness and usability, it's essential to follow best practices. In this section, we'll discuss key best practices for implementing 2FA.

1. Inform Users About Backup Codes

Educate users about the importance of backup codes and provide mechanisms for generating and securely storing them. Backup codes serve as a fallback option in case primary authentication methods are unavailable.

2. Rate Limiting Authentication Attempts

Implement rate-limiting mechanisms to prevent brute-force attacks and unauthorized access attempts. Limit the number of login attempts within a specific time frame to mitigate the risk of credential stuffing attacks.

3. User Experience Considerations

Prioritize user experience during the 2FA setup and authentication process. Design intuitive interfaces, provide clear instructions, and minimize friction to encourage users to adopt 2FA without frustration.

4. Secure Storage of Secrets

Ensure the secure storage of user secrets and sensitive information related to 2FA. Implement robust encryption and hashing techniques to protect user data from unauthorized access or disclosure.

Conclusion

In this tutorial, we've explored the implementation of two-factor authentication (2FA) in Golang web applications. We started by understanding the concept of 2FA and its significance in enhancing security for web applications.

We discussed the prerequisites for implementing 2FA and provided step-by-step guidance on setting up the Golang environment and integrating a 2FA library into the project. We covered various aspects of 2FA implementation, including generating and storing secrets, handling user authentication, and validating TOTP codes.

Now, you are ready to easily add 2FA in your Golang Web Application. You can find the complete project code in this GitHub Repo.