You can replace Microsoft Authenticator with oathtool on Linux or macOS to generate Time-based One-Time Passwords (TOTP) for two-factor authentication. This approach offers greater privacy and control, as the secret keys remain local rather than stored in a cloud-linked mobile application. By using command-line utilities, you avoid proprietary software dependencies while maintaining robust security standards for your accounts.
Understanding TOTP and oathtool
Two-Factor Authentication (2FA) often relies on the Time-based One-Time Password (TOTP) algorithm defined in RFC 6238. Most modern services, including GitHub, Google, and various enterprise platforms, use this standard. While Microsoft Authenticator is convenient, it ties your security credentials to a specific vendor’s ecosystem and requires a smartphone.
oathtool is an open-source utility that implements this same algorithm locally. It allows you to generate the six-digit codes required for login directly from your terminal or script. This method is particularly useful for servers, headless systems, or users who prefer minimalistic tools over full-featured mobile apps.
Installing oathtool
Before you can begin generating codes, you must install the utility on your operating system. The installation process varies slightly depending on whether you are using Debian-based Linux distributions, Red Hat variants, or macOS.
For Ubuntu, Debian, or Mint users, open your terminal and run:
sudo apt update
sudo apt install libqrencode-tools oathtool
The
libqrencode-tools package is optional but recommended if you wish to generate QR codes directly from secret keys within the terminal.
On Fedora, RHEL, or CentOS systems, use the following commands:
sudo dnf install oathtool
If you are using macOS with Homebrew, install it via:
brew install oathtool
After installation, verify that the tool is working by checking its version:
oathtool --version
This should return the installed version number, confirming that the binary is accessible in your system path.
Importing Your Secret Key
To use oathtool, you need the base32-encoded secret key associated with your account. You typically obtain this when setting up 2FA on a new service. Instead of scanning a QR code with a phone app, you will manually enter this string into oathtool. Many services provide the secret key in text format alongside the QR code image during setup. If you only have a QR code, you can decode it using online tools or the
zbarimg utility if installed, but manual entry of the base32 string is the most reliable method for direct integration.
Let us assume your secret key is
JBSWY3DPEHPK3PXP. This is a common test key, but the process remains identical for real production secrets. You do not need to save this key to a file unless you plan to automate the process. For immediate use, you can pass the key directly to the command line.
Generating the TOTP Code
Once installed and armed with your secret, generating a code is straightforward. The basic command structure requires the
--totp flag to specify the time-based algorithm and the
-s flag followed by your secret key.
Run the following command:
oathtool --totp -s JBSWY3DPEHPK3PXP
The output will be a six-digit number, such as
123456. This code is valid for 30 seconds. If you wait too long, the server will reject it because the time window has shifted. To see the remaining time for the current code, you can add the
--time-step option, though
oathtool defaults to the standard 30-second interval used by almost all providers.
For debugging purposes, you might want to see the raw HMAC hash or the exact time step being used. Use the
--verbose flag for detailed output:
oathtool --totp -v -s JBSWY3DPEHPK3PXP
This helps confirm that your local clock is synchronized correctly, which is critical for TOTP success. If your system time is off by more than a few seconds, the generated codes will fail validation.
Automating and Security Considerations
While manual generation is fine for occasional logins, automation is where oathtool shines. You can integrate it into scripts for CI/CD pipelines or automated testing environments. However, storing secret keys in plain text scripts poses a security risk. A better practice is to store the secret in an environment variable or a restricted permission file (e.g., mode 600).
For example, you can export the secret in your shell profile:
export MY_SECRET="JBSWY3DPEHPK3PXP"
oathtool --totp -s $MY_SECRET
This keeps the secret out of your command history and allows easy rotation without changing multiple scripts. Always ensure that your terminal history does not expose these secrets by using
set +o histexpand before entering sensitive data if necessary.
Additionally, consider the trade-offs between convenience and security. Mobile authenticators offer backup options through cloud sync (in some cases) or device transfer features. With oathtool, losing access to your machine means losing your 2FA capability unless you have exported the secrets securely elsewhere. Therefore, maintain a secure offline backup of your base32 secrets, perhaps printed on paper or stored in an encrypted password manager, to prevent lockouts.
For those managing large-scale deployments, auditing how these tools interact with enterprise identity providers is crucial. Understanding the broader context of authentication management ensures that switching to command-line tools does not create gaps in your security posture. For more information on managing authenticator usage in enterprise environments, you may find
Auditing Microsoft Authenticator usage across Azure helpful for understanding the administrative side of 2FA.
Frequently Asked Questions
Does oathtool work on Windows?
Native support for oathtool is limited to Unix-like systems. However, you can run it on Windows using WSL (Windows Subsystem for Linux) or Cygwin. Alternatively, Windows users can use other CLI tools like
authy or PowerShell scripts that implement the TOTP algorithm locally.
What if my generated code is rejected?
The most common cause is clock drift. Ensure your system time is synchronized with an NTP server. If the time is off by more than 30 seconds, the server will reject the code. You can also try generating a code slightly earlier or later to cover the boundary period.
Can I use oathtool for HOTP instead of TOTP?
Yes, by replacing the
--totp flag with
--hotp and providing a counter value. This is useful for event-based one-time passwords, though time-based tokens are far more common in modern web services.
Is it safe to share my secret key with others?
Never share your base32 secret key. Anyone with the key can generate valid codes and bypass your second factor. Treat the secret with the same caution as your primary password.
How do I handle multiple accounts with oathtool?
You can manage multiple secrets by creating separate environment variables or aliasing different oathtool calls. For example, define
export GITHUB_SECRET="..." and
export GOOGLE_SECRET="...", then call oathtool with the respective variable for each service.