Two Factor Authentication System Using Totp And Python — Complete Documentation & Simulation

Overview & System Context

Two Factor Authentication System Using Totp And Python: Comprehensive Web-Sourced Technical Investigation Exhaustive Research Dossier · Pure Web-Scraped Content: ~7409 Words · Real Software Screenshots: 1 1. Executive Overview & Technical Background Google Authenticator is a software-based authenticator by Google. It implements multi-factor authentication services using the time-based one-time password (TOTP; specified in RFC 6238) and HMAC-based one-time password (HOTP; specified in RFC 4226), for authenticating users of software applications. When logging into a site supporting Authenticator (including Google services) or using Authenticator-supporting third-party applications such as password managers or file hosting services, Authenticator generates a six- to eight-digit one-time password which users must enter in addition to their usual login details. Google provides Android, BlackBerry, and iOS versions of Authenticator. An official open source fork of the Android app is available on GitHub. However, this fork was archived in April 6, 2021 and is now read only. Current software releases are proprietary freeware.

The app is first installed on a smartphone to use Authenticator. It must be set up for each site with which it is to be used: the site provides a shared secret key to the user over a secure channel, to be stored in the Authenticator app. This secret key will be used for all future logins to the site. To log into a site or service that uses two-factor authentication and supports Authenticator, the user provides a username and password to the site. The site then computes (but does not display) the required six- to eight-digit one-time password and asks the user to enter it. The user runs the Authenticator app, which independently computes and displays the same password, which the user types in, authenticating their identity. With this kind of two-factor authentication, mere knowledge of username and password is insufficient to break into a user's account - the attacker also needs knowledge of the shared secret key or physical access to the device running the Authenticator app. An alternative route of attack is a man-in-the-middle attack: if the device used for the login process is compromised by malware, the credentials and one-time password can be intercepted by the malware, which then can initiate its login session to the site, or monitor and modify the communication between the user and the site.

The number of 30-second periods since the Unix epoch (TOTP) as 64-bit big endian integer; or A counter that is incremented with each new code (HOTP). A portion of the HMAC is extracted and displayed to the user as a six- to eight-digit code; The last nibble (4 bits) of the result is used as a pointer, to a 32-bit integer, in the result byte array, and masks out the 31st bit. "This open source project allows you to download the code that powered version 2.21 of the application. Subsequent versions contain Google-specific workflows that are not part of the project." The latest open-source release was in 2020.

Figure 1: Figure 1: Verified System Architecture & Pipeline Workflow privacyIDEA is a two factor authentication system which is multi-tenency- and multi-instance-capable. It is open source, written in Python and hosted at GitHub. privacyIDEA is a LinOTP's fork from 2014. LinOTP is Linux-based software to manage authentication devices for two-factor authentication with one time passwords. It is implemented as a web service based on the python framework Pylons. Thus it requires a web server to run in. LinOTP is mainly developed by the German company KeyIdentity GmbH. Its core components are licensed under the Affero General Public License. It is an open source authentication server certified by the OATH initiative for open authentication for its 2.4 version.

Get a head start on your coding projects with our Python Code Generator . Perfect for those times when you need a quick solution. Don't wait, try it today! In this tutorial, you’ll learn how to implement 2FA (Two-Factor Authentication) using the very able Python. 2FA is a security mechanism that requires users to provide two different authentication factors to verify their identity. This adds an extra layer of security beyond the traditional username and password combination.

To ensure secure access to a system, you can be authenticated using three major factors: So, using any two of these three factors is 2FA. And yes, using all three ensures more security. Using all three is known as MFA (Multi-Factor Authentication). In this tutorial, you will learn how to add OTPs as an extra layer of security to whatever authentication a system may be using.

To achieve this in Python, we'll use the pyotp library. We’ll also use the qrcode library to generate QR Codes for our OTP keys. pyotp is a Python library that provides support for generating and validating OTPs (One-Time Passwords) based on the TOTP (Time-based One-Time Password) and HOTP (HMAC-based One-Time Password) algorithms.

TOTP generates one-time passwords based on the current time, while HOTP generates them based on a counter value. TOTP is more secure as it nullifies an OTP once its time frame (typically 30 seconds) has passed. Also, HOTP is vulnerable to brute force attacks due to its static nature. We'll see how to implement both. While the tutorial here leverages the pyotp library for generating OTPs based on TOTP and HOTP algorithms, it's important to recognize that in the broader ecosystem of two-factor authentication, OTPs delivered via SMS or email predominantly follow the TOTP model due to their expiration characteristics. However, system architectures can vary, and some may implement a more HOTP-like mechanism, especially for email-based OTPs, where the sequence or event, rather than strictly time, dictates the OTP's validity.

Starting with TOTP, open up a new file and name it meaningfully, like totp.py , and include the following code: In this very basic code, which is intended to show you how TOTP works, we are basically generating an OTP with a key and displaying it. After 30 seconds, the key becomes useless. Feel free to try it out: That's my result after entering the OTP within the time frame. If I had entered it after 30 seconds, I would have gotten False as my output.

In this code, we generate and verify HMAC-based one-time passwords (HOTP) with a predefined key , incrementing the counter for each generated OTP and prompting the user to enter the OTP for verification. Also, notice that now our key wasn’t randomly generated; it was defined. You can go either way! The major difference is that with HOTP, as long as the key is the same, you’ll get the same OTP - It is not time-based. So, there are no prizes for guessing that you must use a strong, secret password. Let's run it: When testing, enter all OTPs sequentially. Notice I got False when I entered a wrong OTP.

Now that we know what OTPs are, and how to use them in Python, let’s build a simple script that integrates with Google Authenticator - We'll be able to view our OTPs using Google Authenticator. However, feel free to test with any Authenticator that lets you scan a QR code! We’re going to be writing two programs. The first one will generate our key and QR code for us, while the other will do the verification.

So for the first, name it meaningfully like otp_qrcode_and_key.py and insert the following code: In this code, we generate a random TOTP key, display it to the user, save it to a file for reference, and generate a QR code for TOTP setup with the account name "Muhammad" and issuer name " CodingFleet.com ," saving the QR code as totp_qr.png . After running this code, you should see a 2fa.txt file containing your key and a totp_qr.png . which is your QR code in your directory.

Please use your Google Authenticator or whatever authentication app you use to scan the QR code. After scanning, your OTPs will now be available on the authenticator app, like so: This means that to verify my login to my CodingFleet account, I need to enter that OTP. Now, for the verification program, open another file and name it otp_verification.py : This code simulates the authentication process using the TOTP key (generated in Program 1). It prompts the user to enter a code from their Google Authenticator app, verifies its correctness, and displays the authentication result. We're reading from the 2fa.txt file generated in the first program, let's run it: Notice that I tried using the key in the image of the Authenticator App above, which failed. That’s because that key had already expired (After 30 seconds). So I tried another one, which was still in its validity period, and it worked.

The OTP (One-Time Password) mechanism, when integrated with Google Authenticator (or any authenticator app), works on the principle of TOTP. Even after a significant amount of time has passed, the OTPs generated by the authenticator app remain in sync with the code (or potentially, your server) because both the server and the app use the same secret key and the current time as inputs to generate OTPs. The TOTP algorithm generates new codes at fixed intervals (usually every 30 seconds), ensuring that the code on the user's app matches the server's expected code within the same time frame. This method maintains synchronization between the server and the app, ensuring a secure and dynamic method of authentication that is challenging to compromise.

There you have it. That’s how you can ensure 2FA using OTP in your applications. You can get all the code snippets for this tutorial here . Also, if you want to learn more about cybersecurity and cryptography, check out our Cryptography with Python eBook . Take the stress out of learning Python. Meet our Python Code Assistant – your new coding buddy. Give it a whirl! Learn how to build a fork bomb with os and multiprocessing modules in Python, a program that consumes the target computer's resources and potentially freezes it.

Master IP spoofing with Python: Dive into crafting fake IP addresses to test network security. Utilize Scapy and Faker in a hands-on tutorial to send spoofed ICMP packets, complete with practical examples and step-by-step instructions. Learn to protect your downloads from corruption and cyberattacks. This guide teaches you how to verify file integrity using Python, ensuring that your files remain authentic and untampered.

Got a coding query or need some guidance before you comment? Check out this Python Code Assistant for expert advice and handy tips. It's like having a coding tutor right in your fingertips! Two-factor authentication (2FA) has become essential for securing user accounts in modern applications. Among the various 2FA methods available, Time-Based One-Time Passwords (TOTP) offer an excellent balance of security and user experience.

In this guide, I'll walk you through implementing TOTP authentication in Python using PyOTP , a powerful library that seamlessly integrates with popular authenticator apps like Google Authenticator and Authy. We'll build a complete authentication system that generates temporary passwords expiring every 30-240 seconds. PyOTP is a Python library specifically designed for generating and verifying one-time passwords. It enables you to implement robust two-factor or multi-factor authentication methods in web applications and other systems requiring secure user login.

The beauty of TOTP lies in its time-based nature - passwords are generated using a combination of a shared secret key and the current timestamp, ensuring each code is unique and expires quickly. Now that we have our core methods, let's understand the complete authentication workflow: When a user registers for an account on your application, you'll store their hashed password securely in the database, just as you would with any regular password-based authentication system. Additionally, generate a Base32 secret using secret_key_gen() to enable TOTP for the user, and save this in your users table.

PyOTP works seamlessly with Google Authenticator, Authy, and other OTP apps. The library includes the ability to generate provisioning URIs for use with QR code scanners built into these MFA client apps. The gen_qr() method handles this by using the qrcode module to generate a scannable QR code that users can add to their authenticator app. The TOTP algorithm uses HMAC-SHA1 (Hash-based Message Authentication Code with SHA-1) to generate one-time passwords. The algorithm takes the secret key and the current timestamp as input, producing a unique, time-based OTP that changes every 30 seconds.

2. System Architecture & Core Working Principles When users attempt to log in, they provide both their regular password and the current one-time password from their authenticator app. The server uses the stored secret key associated with the user's account and the current time to calculate the expected OTP, then compares it with the entered OTP for authentication.

To account for slight variations in time between the server and the user's device, a small grace period is typically allowed during OTP verification. If the current OTP is not accepted, the server may check the OTPs for the previous and next time steps as well, accommodating minor time differences. As a developer, you should implement a backup mechanism for users to regain access if they lose their TOTP device. This could include: These backup options ensure users aren't permanently locked out of their accounts while maintaining security standards.

Most developers reach for a library when they need TOTP. That's fine for production — but if you don't understand what's underneath, you'll misconfigure the time window, miss the replay-attack problem, or ship without recovery codes. This article builds TOTP from the RFC spec so you know what every line is doing. TOTP (Time-based One-Time Password, RFC 6238) is an extension of HOTP (RFC 4226). HOTP generates a code from an HMAC-SHA1 of a shared secret and an incrementing counter. TOTP replaces the counter with a time step derived from the current Unix timestamp: The shared secret is a random byte string encoded in base32. Both the server and the authenticator app perform these steps independently and compare the result — no secret travels over the wire after enrollment.

Here's a complete implementation using only Python's standard library — no external dependencies: Users provision TOTP by scanning a QR code that encodes an otpauth:// URI. The format is standardized across Google Authenticator, Aegis, Bitwarden, and every RFC 6238-compatible app: A minimal REST API with two routes — enroll and verify. The important addition here is the replay-attack guard: without it, a valid code intercepted by a man-in-the-middle can be reused within the same 30-second window.

Note the two layers of protection: the TOTP algorithm itself (valid for at most 90 seconds with window=1 ) plus the explicit per-code deduplication that blocks within-window replay. No enrollment confirmation. Store the secret only after the user successfully verifies their first code. This catches QR scan errors before you commit a broken secret to the database and lock the user out immediately.

No recovery codes. If a device is lost, the user needs a way back in. Generate 8–10 single-use recovery codes at enrollment, store them bcrypt-hashed (not SHA-256 — short codes need a slow hash), and let users redeem them one at a time. Logging TOTP codes. Short-lived credentials still qualify as credentials. Make sure your request logging middleware strips the code field before it reaches your log aggregator or error tracker.

Storing secrets in plaintext. TOTP secrets deserve the same treatment as passwords: encrypt at rest with a key managed separately from the database, such as envelope encryption via a KMS. For a structured checklist covering TOTP enrollment flows, brute-force lockout, session binding, and secure logout, the free security hardening checklists at AYI NEDJIMI Consultants are a solid starting point.

The TOTP algorithm itself is about 30 lines of Python. The security properties come from the surrounding decisions: constant-time comparison, replay prevention, proper entropy for secrets, and recovery paths for lost devices. Using a library like pyotp in production is reasonable — it's well-tested and saves maintenance overhead. But having walked through the spec, you'll recognize when a configuration option actually matters and when a tutorial is quietly skipping the parts that get users locked out.

I run AYI NEDJIMI Consultants , a cybersecurity consulting firm. We publish free security hardening checklists — PDF and Excel. Two-Factor Authentication, or 2FA, is like having an extra lock on the door to your online accounts. Instead of just using a password, 2FA adds another layer of security. It's a bit like needing both a key and a special code to open a vault.

Think of it as a shield for your accounts. Passwords can sometimes be guessed or stolen, but with 2FA, even if someone gets your password, they'd still need that extra code or device to get in. It's an extra step that makes your accounts much harder for hackers to break into. So, let's explore how to set up this extra layer of protection using PyOTP and Google Authenticator in your Flask app.

PyOTP is a Python library that's incredibly handy for generating Time-based One-Time Passwords (TOTP) and HMAC-based One-Time Passwords (HOTP). Its primary role revolves around creating these unique, time-sensitive codes that add an extra layer of security to user accounts. By integrating PyOTP into your Flask application, you can easily implement Two-Factor Authentication (2FA) by generating and verifying these OTPs.

If you're new to PyOTP or would like a refresher on its functionalities, I recommend reviewing my previous guide on PyOTP . This understanding will be beneficial as we get into the integration of PyOTP within your Flask application for Two-Factor Authentication (2FA). Google Authenticator, on the other hand, stands out as one of the most widely used OTP generator apps available. It functions as a secure platform for generating time-based OTPs, compatible with various services and applications supporting 2FA. Users can easily set up Google Authenticator on their devices to generate these time-sensitive codes, adding an extra level of security to their accounts.

This seamless back-and-forth between passwords, authenticator apps, and unique codes ensures that only the rightful account owner can access the precious content behind the digital doors of your website. If you also enjoy visual learning, here's a fancy video showing how the app does its thing. Before you get started with the tutorial, make sure you have the following requirements satisfied: You'll need a few external libraries for this project. Let's learn more about them and install them one by one.

We are going to create a virtual environment using venv . Python now ships with a pre-installed venv library. So, to create a virtual environment, you can use the below command: The above command will create a virtual environment named env. Now, we need to activate the environment using this command: To verify if the environment has been activated or not, you can see (env) in your terminal. Now, we can install the libraries.

In the above script, we created a Flask app called app . We use the __name__ argument to indicate the app's module or package so that Flask knows where to find other files such as templates. We also set the configuration of the app using an environment variable called APP_SETTINGS . We'll export it later. To use Flask-Bcrypt, Flask-SQLAlchemy, and Flask-Migrate in our application, we just need to create objects of the Bcrypt , SQLAlchemy and Migrate classes from the flask_bcrypt , flask_sqlalchemy and, flask_migrate libraries, respectively.

We've also registered blueprints called accounts_bp and core_bp in the application. We'll define them later in the tutorial. In the root directory of the project (that is, outside the src directory), create a file called config.py . We'll store the configurations for the project in this file. Within the file, add the following content: In the above script, we have created a Config class and defined various attributes inside that. Also, we have created different child classes (as per different stages of development) that inherit the Config class.

Notice that we're using a few environment variables like SECRET_KEY , DATABASE_URL , and APP_NAME . Create a file named .env in the root directory and add the following content there: Apart from the SECRET_KEY , DATABASE_URL and APP_NAME , we've also exported APP_SETTINGS , DEBUG , FLASK_APP , and FLASK_DEBUG .

The APP_SETTINGS refers to one of the classes we created in the config.py file. We set it to the current stage of the project. The value of FLASK_APP is the name of the package we have created. Since the app is in the development stage, you can set the values of DEBUG and FLASK_DEBUG to True and 1 , respectively. Next, we'll create a CLI application of the app so that we can later add custom commands if required.

Create a manage.py file in the root directory of the application and add the following code: As mentioned earlier, you'll use the concepts of blueprints in the project. Let's create two blueprints – accounts_bp and core_bp – in this section. Next, add an empty __init__.py file to covert it into a Python package. Now, create a views.py file inside the package where you'll store all your routes related to user authentication.

3. Software Implementation, Frameworks & Protocols In the above script, you have created a blueprint called accounts_bp for the accounts package. Similarly, you can create a core package in the root directory, and add a views.py file. Note: If you're new to Flask Blueprints, make sure you go through this tutorial to learn more about how it works.

In the above code, you created a User model by inheriting the db.Model class. The User model consists of the following fields: The constructor initializes the User object upon instantiation by accepting username and password parameters. It hashes the provided password using bcrypt.generate_password_hash(password) , records the current timestamp as the created_at value, and generates a unique secret_token using pyotp.random_base32() for 2FA setup.

The get_authentication_setup_uri() method generates a setup URI used by authenticator apps like Google Authenticator. It constructs a URI containing the user's username and the application's name ( Config.APP_NAME ) necessary for setting up two-factor authentication. The basic format of the URI is: where, alice@google.com is the username of the user and Example is the application's name.

Next up, the is_otp_valid() method verifies the one-time password (OTP) entered by the user during login. It parses the setup URI generated earlier, checks the validity of the provided OTP ( user_otp ), and returns True if the OTP matches, ensuring secure authentication. Finally, the __repr__ method provides a string representation of the User object, displaying the associated username when an instance of the class is printed or represented as a string.

The most important part of Flask-Login is the LoginManager class that lets your application and Flask-Login work together. Next, we need to provide a user_loader callback. This callback is used to reload the user object from the user ID stored in the session. It should take the ID of a user, and return the corresponding user object. Now, we don't need to implement these explicitly. Instead, the Flask-Login provides a UserMixin class that contains the default implementations for all of these properties and methods. We just need to inherit it in the following way: The name of the login view can be set as LoginManager.login_view . The value refers to the function name that will handle the login process.

Let's also create the basic templates inside the src/templates folder. Create a _base.html file and add the following code: The _base.html is the parent HTML file that will be inherited by the other templates. We have added Bootstrap 5 support in the above file. We are also making use of Flask Flashes to show Bootstrap alerts in the app. In this section, we'll first create a view function for the homepage inside the core/views.py file. Add the following code there: Notice that we have used the blueprint to add the route. We also added a @login_required middleware to prevent access for unauthenticated users.

Next, let's create an index.html file inside the templates/core folder, and add the following code: First of all, we'll create a registration form using Flask-WTF. Create a forms.py file inside the accounts package and add the following code: The RegisterForm extends the FlaskForm class and contains three fields – username , password , and confirm . We have added different validators such as DataRequired , Length , Email , and EqualTo to the respective fields.

We also defined a validate() method which is automatically called when the form is submitted. Inside the method, we first perform the initial validation provided by FlaskForm. If that is successful, we perform our custom validation such as checking whether user is already registered, and matching the password with the confirmed password. If there are any errors, we append the error message in the respective fields.

Now, let's use this form inside the HTML file. Create an accounts directory inside the templates folder and add a new file called register.html inside it. Add the following code: In the above Jinja template, we make use of the form that we created, and add relevant error handling logic checks for validation errors in each field. Users can submit the form by clicking the "Sign up" button, and a link below the form allows already registered users to navigate to the login page for authentication.

Next, let's use this form in the views.py to create a function to handle the registration process. The route begins by checking if the current user is already authenticated. If so, it verifies whether 2FA is enabled for the user. If 2FA is already enabled, a message informs the user that they're already registered, redirecting them to the home URL. However, if the user is authenticated but 2FA is not enabled, a flash message prompts the user to enable 2FA first before logging in, redirecting them to the 2FA setup URL.

If the user is not authenticated or has not yet registered 2FA, the code initializes a registration form and proceeds to validate the form data on submission. Upon successful form validation, we create a new User object with the provided username and password and save it to the database. Upon successful user registration, the newly registered user is logged in. A success message flashes, notifying the user of successful registration and prompting them to enable 2FA before logging in. Subsequently, the user is redirected to the 2FA setup URL to enable 2FA.

The form is similar to the registration form but it has only two fields – username and password . Now, let's use this form inside new HTML file called login.html created inside the templates/accounts directory. Add the following code: The above HTML file is also similar to the register.html file but with just two fields for the username and password.

Next, let's create a view function to handle the login process inside the accounts/views.py file: The route starts by checking if the current user is already authenticated. If the user is authenticated and 2FA is enabled, a message informs the user they're already logged in, redirecting them to the home URL. If the user is authenticated but 2FA isn't enabled, a flash message prompts the user to enable 2FA before logging in, redirecting them to the 2FA setup URL.

If the user isn't authenticated, the code initializes a login form and validates the form data upon submission. Upon successful validation, it queries the database to find a user matching the provided username. If the user exists and the password matches the hashed password stored in the database, the user is logged in. Additionally, if 2FA isn't enabled for the current user after successful login, a flash message prompts the user to enable 2FA before proceeding, redirecting them to the 2FA setup URL. If the login is successful and 2FA is enabled, the user is redirected to the 2FA verification URL.

If the user isn't registered, a flash message informs them to register. If there's a mismatch in the provided username or password, another flash message notifies the user of invalid credentials. Logging out the user is a very simple process. You just need to create a view function for it inside the accounts/views.py file: The Flask-Login library contains a logout_user method that removes the user from the session. We used the @login_required decorator so that only authenticated users can logout.

Up until now, we have been redirecting the users to the setup 2FA page whenever the 2FA is not enabled in their accounts, but we haven't implemented it yet. Let's do that in this section. The route, created inside accounts/views.py , ensures that only authenticated users can access it using the @login_required decorator.

Upon accessing this route, the function retrieves the current user's secret_token for 2FA setup and generates a URI through current_user.get_authentication_setup_uri() to configure an authenticator app like Google Authenticator. It also uses get_b64encoded_qr_image(uri) to obtain a Base64-encoded QR code image representing this setup URI. We will define it below.

Finally, it renders the setup-2fa.html template, passing the user's secret_token and the Base64-encoded QR image to the template for users to scan it. Next, create a utils.py file in the src directory and add the following code to generate the QR : Remember the qrcode library we installed in the beginning of the tutorial? This is where we're going to use it.

Upon receiving data as input, representing the content to be embedded within the QR code, the function initializes a QRCode object using the qrcode library. It adds the provided data to this QR code instance and generates the QR code. The code then converts this QR code into an image representation. 4. Practical Deployment, Analysis & Case Studies Using a BytesIO object, it stores this image in memory. The function proceeds to encode the content of this in-memory buffer, representing the QR code image, into Base64 format. Finally, it returns this Base64-encoded string, encapsulating the QR code image, ready for transmission or display in various applications.

Next, let's create the setup-2fa.html page inside the templates/accounts folder, and add the following content: We add some instructions in the page for the users to follow. These instructions provide clear steps for users to enable 2FA: directing them to download the Google Authenticator app via a link, guiding the setup process within the app, and prompting users to proceed by clicking a link after scanning the displayed QR code.

Displaying the QR code is central to the setup process. The template embeds the QR code image using an tag with its source set to a Base64-encoded string ( {{ qr_image }} ). This image represents the secret key essential for 2FA setup. We also show the secret key in read-only mode, allowing users to view the key without being able to modify it. We have added a copy button to make it easier for the users to copy the key.

Moreover, we have added a link to the 2FA verification page guiding users to proceed with the setup process after scanning the QR code. We will implement this functionality in the next section. In this section, let's implement the 2FA verification. To start with, we will require an OTP form where users can enter their OTP. Add the following content in the accounts/forms.py file: Now, let's use this form in the verify-2fa.html file inside the templates/accounts folder: The Jinja template essentially contains a form with one field for OTP and a verify button.

Let's create the route which handles the submission of this form inside the accounts/views.py file: The route starts by initializing a form ( TwoFactorForm ) meant for 2FA verification using the data obtained from the request. Upon form submission, the code proceeds with several conditional checks to validate the OTP entered by the user. Once the form has been successfully submitted and validated, the code verifies the authenticity of the OTP using current_user.is_otp_valid(form.otp.data) , which checks if the entered OTP is valid for the current user. If the OTP is valid, the code executes the following logic: Furthermore, if the OTP entered by the user is invalid, the code flashes an error message indicating an invalid OTP and redirects the user back to the 2FA verification URL to retry the verification process.

Now that our application is ready, you can first migrate the database, and then run the app. Since this is the first time we're running our app, you'll need to run all the above commands. Later, whenever you make changes to the database, you'll just need to run the last two commands. Since we have completed the development, here's how your file structure should look like: In this tutorial, you learned how to set up two-factor authentication in your Flask app using PyOTP.

Here's the link to the GitHub repository . Feel free to check it out whenever you're stuck. Here are some other tutorials I wrote about authentication, email verification, and OTPs that you might enjoy: Thank you for reading. I hope you found this article useful. You can follow me on Twitter . Software Engineer at OpenText passionate about building scalable web applications and backend systems. I work mainly with Java, Spring Boot, Python, and modern web technologies. I enjoy creating things for the internet, exploring new tech, and sharing what I learn along the way.

Learn to code for free. freeCodeCamp's open source curriculum has helped more than 40,000 people get jobs as developers. Get started How does your authenticator app generate a fresh code every 30 seconds with no network call? Pure math — and fewer than 15 lines of Python.

Passwords are broken. They get phished, leaked in data breaches, brute-forced, and reused across dozens of services. The answer the industry landed on is a second factor — something that proves you have a physical device in addition to knowing a password. The most common form of software-based 2FA is TOTP : a 6-digit code that rotates every 30 seconds. You’ve seen it in Google Authenticator, Authy, Bitwarden, 1Password, and countless others. You scan a QR code once, and your authenticator app produces a fresh code every half-minute, in sync with the server, without ever making a network request.

The magic is that both sides — your phone and the server — are computing the same code independently, from a shared secret and the current time. There’s no communication, no challenge/response, just math. That math is entirely public. It’s specified in RFC 6238 and fits in fewer than 15 lines of Python. TOTP is built on top of an older standard — HOTP (HMAC-based One-Time Password, RFC 4226 ).

HOTP generates a code from a shared secret and an incrementing counter . Each time you generate a code, the counter ticks up. The problem: if the client and server counters drift, codes stop working. TOTP solves this elegantly. Instead of a persistent counter, it derives the counter from the current Unix time : counter = I T now T step I \text{counter} = \left\lfloor \frac{T_{\text{now}}}{T_{\text{step}}} \right\rfloor counter = I T step I T now I I I Where T step T_{\text{step}} T step I is 30 seconds by default. Both sides floor the Unix timestamp to the same 30-second window and get the same counter — no synchronization needed. The only requirement is that clocks are reasonably accurate, which is trivially guaranteed by NTP.

When you scan a QR code to set up 2FA, you’re importing a shared secret — a random byte sequence known only to you and the server. It’s stored as a Base32-encoded string, which looks like: Base32 uses only uppercase letters A–Z and digits 2–7. It’s URL-safe, easy to type manually, and avoids ambiguous characters.

The casefold=True parameter accepts lowercase input too, which matters for secrets copied from apps or entered by hand. With the secret decoded, we need the counter — a 64-bit big-endian integer representing which 30-second window we’re in: counter = I 1776081600 30 I = 59202720 \text{counter} = \left\lfloor \frac{1776081600}{30} \right\rfloor = 59202720 counter = I 30 1776081600 I I = 59202720 Both the server and the authenticator app perform this same calculation. As long as their clocks agree to within a few seconds, they land in the same window and produce the same code.

This is the cryptographic core. We compute an HMAC-SHA1 of the counter bytes, using the shared secret as the key: HMAC (Hash-based Message Authentication Code) takes a key and a message and produces a fixed-length tag. Unlike a raw hash, it’s resistant to length-extension attacks, and its security depends on the key being secret. SHA-1 produces 20 bytes (160 bits). While SHA-1 is broken for collision resistance (think forged certificates), that vulnerability is irrelevant here — we’re not comparing hashes, we’re using HMAC as a PRF (Pseudo-Random Function). HMAC-SHA1 remains cryptographically sound for this use case, which is why RFC 4226 specifies it.

The result is a 20-byte array that looks like random noise. Next, we extract a 6-digit number from it. We can’t use all 20 bytes — that’d be a 40-character hex code, not a 6-digit number. RFC 4226 defines Dynamic Truncation to extract 4 bytes from the hash in a deterministic but unpredictable way: The offset is derived from the hash itself, so it varies with every counter value. This is what makes the truncation “dynamic” — an attacker observing outputs can’t predict which bytes will be extracted next.

The last step is simple: take the 31-bit integer and produce a 6-digit code by taking it modulo 10 6 10^6 1 0 6 , then zero-padding to ensure exactly 6 digits: The modulo discards all but the last 6 decimal digits. zfill(6) pads with leading zeros so codes like 48271 become 048271 — important because 048271 and 48271 are different 6-character strings.

5. Performance Evaluation & Extended Technical Observations Here’s the complete TOTP function — no third-party library, just the Python standard library: That’s the entire algorithm. 15 lines. You can verify it produces the same output as Google Authenticator or Authy for the same secret — they all implement the same RFC.

You can also swap in hashlib.sha256 or hashlib.sha512 for stronger hash algorithms. Some services (like Steam) use a different number of digits or a different time step; those are just parameters. The main loop only redraws when the 30-second window changes (avoiding flicker), and remaining_time = time_step - (current_time % time_step) drives a progress bar that counts down to the next rotation. The table uses Unicode box-drawing characters for a clean look in any modern terminal. Here’s the complete script: Here’s the full script — a self-contained terminal authenticator with no TOTP library dependency: Secrets are sensitive. The Base32 secret is equivalent to your password. Anyone who obtains it can generate valid codes forever. Don’t hardcode secrets in scripts you commit to version control — use a secrets manager, an encrypted store, or at minimum environment variables.

TOTP doesn’t prevent phishing. A real-time phishing proxy can relay your code to the target site before it expires. TOTP protects against static password theft, not active relay attacks. Passkeys / FIDO2 hardware tokens solve this by binding authentication to the origin domain. Clock skew matters. Most servers accept codes from the previous and next window (±30 seconds) to handle small clock differences. If your clock is off by more than a minute, codes will fail. NTP keeps this trivially in check.

TOTP is a beautiful piece of applied cryptography: simple enough to fit in 15 lines of Python, yet secure enough to protect millions of accounts. The key insight is replacing a stateful counter with a stateless time window — both sides independently compute the same value with no communication. Next time you open your authenticator app, you’re looking at the output of five simple operations on a shared secret and the current time. No magic, no network call — just math.

A Python-based two-factor authentication project implementing Time-Based One-Time Passwords (TOTP) using PyOTP and QR-code based authenticator enrolment. This project demonstrates how two-factor authentication can strengthen an authentication process by requiring a temporary verification code generated by an authenticator application.

The application generates a temporary TOTP secret, creates an enrolment QR code, and verifies a six-digit one-time password entered by the user. The same randomly generated secret is used for both QR-code enrolment and OTP verification. The screenshot above demonstrates a successful authentication attempt using a temporary TOTP credential.

TOTP secrets and enrolment QR codes should be treated as sensitive authentication material. A TOTP QR code contains information that can allow another party to generate valid authentication codes. Python TOTP two-factor authentication system using PyOTP and QR-code authenticator enrolment. In this article, we will explore what TOTP actually is, see it in action during a security breach, and then dismantle the clock-based mathematics that makes it work.

TOTP stands for Time-based One-Time Password . It is an algorithm that generates a temporary, unique password which is valid only for a short period (typically 30 seconds). Unlike traditional passwords, which are static (they remain the same until you change them), TOTP is dynamic . It relies on two fundamental factors working in harmony: The Shared Secret: A unique key exchanged between you and the server during setup (usually via that QR code).

The Current Time: A universal clock that both your device and the server can access independently. This combination creates a "rotational" security layer. Even if a hacker intercepts your code right now, that code will be useless in half a minute. To truly understand the value of TOTP, let's look at a classic "Phishing Attack" scenario. Imagine you receive a convincing email looking like a security alert from GitHub, leading you to a fake login page.

The Attack: You enter your username and password on the fake site. The hacker captures them. The Execution: The hacker immediately takes these credentials to the real GitHub login page. The Execution: They navigate to the real GitHub login page and enter your credentials. The Second Barrier: The system pauses. It recognizes 2FA is enabled and asks: "Please enter the 6-digit code from your authenticator app." The Failure: The hacker is stuck. They have your "Knowledge" (password), but they do not have your "Possession" (the physical phone generating the current code).

This is the technical "magic." How do your phone and the server agree on the code without communicating? They use Unix Epoch Time and Integer Division . The algorithm divides time into fixed windows (usually 30 seconds). The formula looks like this: Floor Function ( $\lfloor ... \rfloor$ ): This rounds the result down to the nearest whole number.

At Time = 915s: $915 / 30 = 30.5$. The floor function drops the decimal. The counter is still 30 . Because the "Counter" input remains constant for 30 seconds, the resulting hash (the 6-digit code) remains constant. TOTP is a perfect example of elegant system design. By combining a shared secret with a quantized version of universal time, we create a security layer that is robust, offline-capable, and incredibly difficult to bypass.

PyOTP is a Python library for generating and verifying one-time passwords. It can be used to implement two-factor (2FA) or multi-factor (MFA) authentication methods in web applications and in other systems that require users to log in. Open MFA standards are defined in RFC 4226 (HOTP: An HMAC-Based One-Time Password Algorithm) and in RFC 6238 (TOTP: Time-Based One-Time Password Algorithm). PyOTP implements server-side support for both of these standards.

Client-side support can be enabled by sending authentication codes to users over SMS or email (HOTP) or, for TOTP, by instructing users to use Google Authenticator , Authy , or another compatible app. Users can set up auth tokens in their apps easily by using their phone camera to scan otpauth:// QR codes provided by PyOTP. Implementers should read and follow the HOTP security requirements and TOTP security considerations sections of the relevant RFCs. At minimum, application implementers should follow this checklist: We also recommend that implementers read the OWASP Authentication Cheat Sheet and NIST SP 800-63-3: Digital Authentication Guideline for a high level overview of authentication best practices.

A helper function is provided to generate a 32-character base32 secret, compatible with Google Authenticator and other OTP apps: PyOTP works with the Google Authenticator iPhone and Android app, as well as other OTP apps like Authy. PyOTP includes the ability to generate provisioning URIs for use with the QR Code scanner built into these MFA client apps: pyotp.totp.TOTP('JBSWY3DPEHPK3PXP').provisioning_uri( name='alice@google.com ', issuer_name='Secure App') pyotp.hotp.HOTP('JBSWY3DPEHPK3PXP').provisioning_uri(name=" alice@google.com ", issuer_name="Secure App", initial_count=0) This URL can then be rendered as a QR Code (for example, using https://github.com/soldair/node-qrcode ) which can then be scanned and added to the users list of OTP credentials.

pyotp.parse_uri('otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App ') pyotp.parse_uri('otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20Ap p&counter=0' Harvested Online Documentation & Reference Sources • https://en.wikipedia.org/wiki/Google%20Authenticator • https://en.wikipedia.org/wiki/PrivacyIDEA • https://en.wikipedia.org/wiki/LinOTP • https://thepythoncode.com/article/implement-2fa-in-python • https://shav.dev/blog/implementing-totp-authentication-in-python-using-pyotp • https://dev.to/ayinedjimi-consultants/implementing-totp-two-factor-authentication-from-scratch-in-python-4j9 • https://www.freecodecamp.org/news/how-to-implement-two-factor-authentication-in-your-flask-app/ • https://arijitk.in/posts/totp-how-two-factor-auth-works/ • https://github.com/azelthong/two-factor-authentication • https://softdevs.hashnode.dev/what-is-totp-understanding-time-based-security