Blog · · Kaabist
How to automate a login with 2FA: TOTP, email and SMS codes
How to automate a login protected by two-factor authentication: TOTP codes, email one-time codes, SMS codes, saved sessions, and scheduled jobs that pause for a code and resume.
Two-factor authentication is the most common reason browser automation stops working in production. A script that signs in reliably on a developer's machine fails on a server the first time the site requests a one-time code.
The right approach depends on where that code is delivered. Codes from an authenticator app can be generated programmatically from the shared secret. Codes sent by email can be retrieved from the mailbox. SMS codes, push notifications and banking-app approvals generally require the account holder, so the automation must pause, request the code and continue. In every case, persisting the authenticated session reduces how often a second factor is requested at all.
This guide covers each method with Playwright for Python, then sets out the requirements for running 2FA-protected logins as unattended, scheduled jobs.
Identifying the second factor
The second login screen determines the approach. Classify it before writing any code.
| Second factor | Delivered to | Fully automatable | Recommended approach |
|---|---|---|---|
| Authenticator app (TOTP) | A shared secret | Yes | Generate the code with a TOTP library |
| Email code or magic link | A mailbox | Yes, with mailbox access | Retrieve it over IMAP or the provider's API |
| SMS code | The account holder's phone | Rarely | Human-in-the-loop, or SMS forwarding for numbers you control |
| Push or banking-app approval | The account holder's device | No | Human-in-the-loop |
| CAPTCHA after sign-in | None | Not recommended | Human-in-the-loop, or an official API |
Where you control the account's 2FA configuration, choose an authenticator app. It is the only option that requires neither a person nor additional infrastructure.
Authenticator apps (TOTP)
TOTP codes (RFC 6238) are derived from a shared secret and the current time, in 30-second intervals. The secret is presented during enrolment, typically as a base32 string behind a "can't scan the QR code?" link. Store it in a secrets manager alongside the password: it grants the same level of access.
import os, time
import pyotp
from playwright.sync_api import sync_playwright, TimeoutError as PlaywrightTimeout
totp = pyotp.TOTP(os.environ["TOTP_SECRET"])
def submit_totp(page, attempts=2):
for attempt in range(attempts):
# Do not submit a code that is about to expire.
remaining = totp.interval - (time.time() % totp.interval)
if remaining < 5:
time.sleep(remaining + 1)
page.fill("#otp", totp.now())
page.click("button[type=submit]")
try:
page.wait_for_url("**/dashboard", timeout=10_000)
return
except PlaywrightTimeout:
if attempt == attempts - 1:
raise
time.sleep(totp.interval) # retry once, in the next window
with sync_playwright() as p:
browser = p.chromium.launch()
context = browser.new_context()
page = context.new_page()
page.goto("https://example.com/login")
page.fill("#email", os.environ["LOGIN_EMAIL"])
page.fill("#password", os.environ["LOGIN_PASSWORD"])
page.click("button[type=submit]")
page.wait_for_selector("#otp")
submit_totp(page)
context.storage_state(path="state.json")Three operational points apply. Keep the host clock synchronised with NTP, since servers reject codes outside a narrow tolerance. Cap retries, because repeated invalid codes can lock the account. Treat the selectors above as placeholders and replace them with stable attributes from the target site.
Email one-time codes
Record a timestamp immediately before triggering the email, and accept only messages received after it. This prevents an earlier code from being reused. Most providers require an app password or OAuth for IMAP access rather than the account password.
import imaplib, os, re, time
from email import message_from_bytes, policy
from email.utils import parsedate_to_datetime
CODE_PATTERN = re.compile(r"\b(\d{6})\b")
def wait_for_email_code(sender, sent_after, timeout=120, poll=5):
imap = imaplib.IMAP4_SSL(os.environ["IMAP_HOST"])
imap.login(os.environ["IMAP_USER"], os.environ["IMAP_APP_PASSWORD"])
try:
deadline = time.time() + timeout
while time.time() < deadline:
imap.select("INBOX")
_, data = imap.search(None, "FROM", f'"{sender}"')
for num in reversed(data[0].split()): # newest first
_, msg_data = imap.fetch(num, "(RFC822)")
msg = message_from_bytes(msg_data[0][1], policy=policy.default)
if parsedate_to_datetime(msg["Date"]).timestamp() < sent_after:
break # every remaining message is older
body = msg.get_body(preferencelist=("plain", "html"))
match = CODE_PATTERN.search(body.get_content() if body else "")
if match:
return match.group(1)
time.sleep(poll)
raise TimeoutError(f"No code from {sender} within {timeout}s")
finally:
imap.logout()Pass a sent_after value a few seconds earlier than the click to absorb clock differences between hosts. Enforce a hard timeout: a missing code should fail the run with a clear error rather than leave it waiting indefinitely. For magic links, extract the URL instead of the code and open it in the same browser context.
SMS, push and banking-app approvals
These factors are delivered to a device held by the account holder, outside the reach of the browser. Two approaches are viable.
- SMS forwarding. A virtual number with a webhook, or a device that forwards messages to an endpoint the job can read. This is suitable only for numbers you own, and many financial and government portals reject virtual numbers.
- Human-in-the-loop. The job detects the second-factor screen, requests the code from the account holder, waits for it and resumes.
Human-in-the-loop is the only approach that works across all sites and all account owners, including customer accounts. Interactive prompts such as input() are adequate for local development only: a scheduled job on a server has no terminal and no operator. The requirements for doing this in production are set out below.
Persisting the authenticated session
Every completed second-factor challenge should be reused for as long as the site allows. Playwright's storage_state captures cookies and local storage; later runs load it into a new browser context and skip the login entirely.
from playwright.sync_api import TimeoutError as PlaywrightTimeout
AUTH_MARKER = "[data-testid=account-menu]" # an element only signed-in users see
def is_authenticated(page):
try:
page.locator(AUTH_MARKER).wait_for(state="visible", timeout=5_000)
return True
except PlaywrightTimeout:
return False
context = browser.new_context(storage_state="state.json")
page = context.new_page()
page.goto("https://example.com/dashboard")
if not is_authenticated(page):
run_login_with_2fa(page) # the flow from the sections above
context.storage_state(path="state.json")Three practices keep session reuse reliable:
- Detect expiry explicitly. Session lifetimes range from hours to weeks. Check for an element only authenticated users see, rather than inferring state from the URL, and keep the re-login path tested.
- Keep the execution environment stable. Some sites bind a session to the device and network that created it. A session created on a workstation and replayed from a cloud region can trigger a new challenge or a security alert to the account holder.
- Protect the state file as a credential. It grants signed-in access. Encrypt it at rest, restrict who can read it, and keep it out of version control, logs and CI artefacts.
Running 2FA logins as scheduled jobs
The failure mode is predictable. A job scheduled for 08:00 finds its session expired, the site sends an SMS code, and the run fails at the second-factor screen. It is rerun manually hours later, and the cycle repeats the next time the session expires.
A production-grade implementation has to meet five requirements:
- Detect the challenge and stop deterministically, rather than failing on a timeout.
- Notify the account holder through a channel they already use, with a secure way to return the code.
- Wait for minutes or hours without holding a browser session open.
- Resume from the challenge, preserving completed work, without signing in again or triggering a second code.
- Protect side effects, so that steps which submit data are never executed twice after a resume.
Requirements 4 and 5 depend on durable execution state: a record of which steps have completed and what they produced. Building this reliably is the larger part of the work, and it is the problem Kaabist is designed to solve.
How Kaabist handles it
In Kaabist, the login is a sequence of ordinary steps within a program. Credentials are supplied as encrypted inputs at run time and are never written into the program. A checkpoint after the login stores the session, so subsequent jobs proceed directly to the data while the session is valid and authenticate again only once it has expired.
When a site requests a code, the job enters an awaiting_input state. Kaabist emails a secure link to the account holder, whether a colleague or a customer, and the program resumes from that step as soon as the code is entered. Completed steps are not repeated, and every step that submits data is fenced, so a resumed job never submits a form twice.
Teams that prefer to supply the code from their own systems can do so through the client libraries:
done = kaab.jobs.wait(
job.id,
timeout=600,
# awaiting_input: e.g. a 2FA code the account holder provides
on_input=lambda request, job: input(f"{request.prompt}: "),
)
if done.status == "succeeded":
print(done.data)Replacing input() with a lookup in your application, a chat integration or an SMS webhook makes the same job fully unattended. A complete walkthrough is available in Scrape a website that requires login.
Frequently asked questions
Can Playwright handle two-factor authentication?
Playwright can enter a code like any other form field, but it cannot obtain the code. Authenticator codes are generated with a TOTP library, email codes are retrieved from the mailbox, and SMS or push approvals usually require the account holder.
How can I avoid a 2FA challenge on every run?
Persist the session with storage_state after the first successful login and load it on subsequent runs. A new challenge is issued only when the session expires or the site no longer recognises the device.
Is automating a 2FA-protected login permitted?
Automating access to your own accounts, or accounts you are authorised to use, is common practice. Review the site's terms of service, and never apply these techniques to accounts you are not authorised to access.
What happens if a code is requested outside working hours?
A conventional script fails. A job that can pause, notify the account holder and resume from the challenge waits until the code is provided, then completes the remaining work.
Should I use an SMS-receiving service to remove the human step?
Only for numbers you own and sites that accept them. Many banks and public-sector portals block virtual numbers, and moving a customer's second factor to a number you control is rarely appropriate.