Repository navigation
User Manual
version 0.3.3
EasyAuth is a desktop application that helps you authenticate with a website or online service that uses two-factor authentication. EasyAuth stores the secret keys that websites provide when you enroll in two-factor authentication and then generates the one-time passcodes that you use to verify your identity.
Two-factor authentication has two phases:
- Setup - enabling the use of secret keys
- Authentication - verifying your identity during login with the use of a one-time passcode.
EasyAuth helps with step 1 by scanning the QR code that website provides during setup and saving the secret key in an encrypted file called the "vault."
EasyAuth helps with step 2 by generating a time-base one-time passcode (TOTP) that you paste into the verification page during login.
This illustration shows the interaction between EasyAuth and the website.
During Setup of 2FA:
- The website setup 2FA page shows a QR code.
- The user clicks "Scan QR code" and EasyAuth finds the QR code and extracts the secret key.
- The secret key is stored in the vault.
During Login:
- EasyAuth retrieves the secret key from the vault.
- A time-based one-time passcode (TOTP) is generated.
- The user clicks on the TOTP which copies it to the clipboard.
- The user pastes the TOTP into the login verification page.
As with any form of two-factor authentication, if the second-factor is compromised (e.g., your phone is lost or stolen) you may lose access to your online entries unless you have saved the recover codes you were issued initially. This software is issued with no guarantee. There is a risk of data loss, including loss of your secret keys.
EasyAuth simplifies two-factor authentication in two ways. During setup EasyAuth automatically scans the QR code and retrieves the secret key. It's not necessary to use your phone's camera to scan the QR code, EasyAuth can automatically find the QR code in your browser window. During authentication you simply click the TOTP to copy it and then paste it into the website. You don't have to get out your phone to read a text message or check your email for a verification code. Quick and hassle-free.
- Stores your secret keys encrypted in a vault on your local machine (doesn't rely on third-party cloud services).
- Automatically finds QR codes displayed on the screen. No need to scan QR codes with your phone.
- Generates Time-based One-time Passwords from your secret keys.
- Accounts are displayed in a scrollable list with a search feature.
- Website icons are displayed for easily identifying each entry.
- The list can be sorted alphabetically, by usage frequency, or by most recently used.
- The list can be manually reordered to achieve a custom ordering.
- Vault entries can be displayed as QR codes for migration to other applications.
- Export and Import vault to plain-text JSON file or otpauth URI format.
- QR codes can be read from an image file.
- Familiar easy-to-navigate desktop GUI.
- GUI includes light and dark themes.
- Preferences dialog has useful customization settings.
- Linux or Windows OS (tested on Linux Mint and Windows 10)
- 3.8 <= Python < 3.13
Simply download a binary executable file from the Releases page.
The first time you launch EasyAuth the application appears as shown here:
The message indicates that no entries have been created.
To create an entry follow the brief instructions in
the Quick Start Guide
or see section 3.1 below - Setting up two-factor authentication.
The EasyAuth main window looks like this:
At the top is the menu bar.
Below the menu bar is a toolbar with a button for scanning a QR code, a search fields, and a countdown timer. The countdown timer refreshes the passcodes every thirty seconds.
The central area of the window is the list of entries in your vault. Each row displays the name of the website and the email address or username that identifies you on that site. On the right side of the display is a button with the time-based one-time password (TOTP) in blue. Clicking on the passcode copies it to the clipboard.
2.4.1 File menu
- New Vault Entry - Create a new entry in your vault. There are three submenus:
- Scan QR code - Automatically locates a QR code on the display screen and uses it to create a new vault entry.
- Open QR image file - Displays a file chooser dialog for you to select an image file that contains a QR code.
- Enter manually - Opens a dialog with a form in which you enter the data supplied by the website.
- Export / Import - Export your vault to a plain-text file or import a file into your vault.
- Preferences - Customize certain features of EasyAuth to suit your preferred workflow.
2.4.1 Tools menu The Tools menu provides several features that are useful utilities.
-
Reorder vault entries - Drag and drop items in your list of entries to customize the order in which they are displayed.
-
Sort entries - Organize the list of entries by a predefined ordering: alphabetical, recently used, or usage count.
-
Provider search - Search or browse a list of known 2FA providers. This feature is not used during a normal workflow but is available as a reference. It displays a list of many common 2FA providers and their favorite icon. Selecting an item copies it to the clipboard from where it can be pasted into the Provider name field in the Add Vault Entry dialog.
2.4.2 Help Menu
- Quick Start - a brief one-page summary of the essential steps of using EasyAuth.
- User Manual - a link to this user manual
- About - a dialog displaying the version number and build date and a link to the website.
When setting up two-factor authentication a website will provide a secret key that gets stored in your vault.
During the setup process most websites display a QR code that contains the secret key.
The easiest way to store the secret key is to let EasyAuth scan the QR code.
In the EasyAuth main window, click the "Scan QR code" button (or use the keyboard shortcut, Alt+S).
(If your vault is empty EasyAuth will prompt for permission to scan the code from your screen.)
If the QR code is visible on the screen EasyAuth will find it
and create a new vault entry.
A brief notification popup will be displayed with the message "QR code found!"
The new vault entry will appear at the top of the list in the main window.
Each entry in the vault appears on a separate row that displays:
- Provider name (website or online service)
- Username or email address that identifies you on the website. (This field is not required for verification but is simply an aid in remembering which login this entry is associated with.)
- The one-time passcode (TOTP) for verifying your identity.
Another way to create a vault entry is to read a QR code from an image file. This is most useful when transferring a secret key from another authenticator app. After taking a photo of the QR code on another device you can transfer the photo to your desktop. EasyAuth can open the photo and read the QR code. From the File menu choose "New Vault Entry > Open QR image". A file chooser dialog appears from which you can select the desired image file to be opened. The QR code will be read and a new vault entry created as described in the previous section.
A new vault entry can be created by manually entering the shared secret key into a form.
- In the main menu, select "File > New Vault Entry > Enter manually" (or use the keyboard shortcut, Alt+A).
- The Add Vault Entry dialog will appear.
- Complete the three fields in the dialog form:
- Provider: Enter the name of the website or online service provider (e.g., Google, GitHub). This field provides an autocomplete feature to aid in locating the provider name. When enough characters are present to uniquely identify the provider you can press the tab key to complete the field and move to the next one.
-
User: Enter a label for the entry. This is usually your username or email associated with the entry.
If you have multiple logins on the same website this field distinguishes between them. -
Secret Key: Enter the secret key provided by the service provider. (E.g., LQNV 5JKC MWY2 TROB)
This key is used to generate the passcodes you will use to authenticate with the website.
Notice that the Save button is disabled until all three fields are completed.
- Click the Save button.
The vault entry will be created and the dialog will close. In the main window the new vault entry is displayed at the top of the list. The provider and user fields are shown on the left and on the right is the TOTP code.
- Click the 6-digit TOTP code to copy it to the clipboard. (Note the seconds timer indicates how much time remains for the displayed TOTP to be active. When the timer reaches zero a new TOTP is automatically generated.)
- Complete the setup process on the website by pasting the TOTP code into the verify field in your browser. The website will authenticate you and confirm that 2FA has been enabled.
EasyAuth makes the process of authenticating yourself to a website fast and easy. When you login to a website you will provide your username and password as usual, and then you will be prompted for a verification code.
- Open EasyAuth and in the main window locate the entry for the website requesting verification.
(The search field can be used for finding a desired entry.)
The TOTP code is the 6-digit number on the right side of the row.
- Click the 6-digit TOTP code to copy it to the clipboard. A brief popup will announce "Copied" to acknowledge the operation.
- Return to the website verification form and paste the six-digit code into the verification field. That's all there is to it. The website will authenticate you and finish the login process.
- If you are delayed in completing the copy-and-paste operation the 30-second activation period may expire and the website will decline to verify you. Simply click the next TOTP code that appears in the main window and try again.
It's possible to modify a vault entry to update the details for the provider or user. In most cases this option is not needed as the information obtained from the QR code during entry creation is the most accurate and reliable. However, should you desire to customize your vault entry, this dialog provides the mechanism for doing so.
-
Viewing a vault entry:
- In the main window, locate the entry you want to edit.
- Note the provider name is underlined, indicating it can be clicked. When the mouse hovers over the provider name the name turns color and the mouse cursor becomes a hand.
- Click the provider name and the View Vault Entry dialog will appear.
-
Update Details:
- Click the "Edit" button. The editable fields become enabled and the dialog title changes to "Edit Vault Entry"
- Two fields can be modified:
- Provider: Enter the desired name of the website or service provider.
- User: Enter the desired identifier for the entry. This is usually your username or email address associated with the entry.
-
Save Changes:
- Once you have updated the necessary details, click the "Save" button.
- The changes will be saved, and the dialog will close.
- After saving, the updated entry will appear in the list in the main window.
-
Entry Details:
The lower portion of the dialog displays details about the entry.
- Last Used: The date and time when the TOTP code was copied to the clipboard.
- Usage Count: The number of times the TOTP code has been used.
- "Show QR code" button will reveal the QR code for this entry which can be used to import this entry into another application.
Deleting an entry removes the secret key from your vault. This action is not reversible should be used with caution. When you delete the entry you lose the secret key from which TOTP codes are generated and you lose the ability to authenticate with the website. You will no longer be able to login to the site. The only way to regain access to the website will be to use a recover code that was provided when you enabled two-factor authentication. EasyAuth does not store recover codes. It's your responsibility to save recover codes in a secure location.
- In the main window, locate the entry you want to delete.
- Click the Provider name. This will open the View Vault Entry dialog.
- Click the "Edit" button, which will enable the "Delete" button. Click the "Delete" button.
- A confirmation dialog will appear, asking you to confirm the deletion.
- If you are certain you are deleting the proper entry, click "Yes" in the confirmation dialog.
- The entry will be deleted, and the dialog will close. After deleting, the entry no longer appears in the list in the main window.
- Backup: Before deleting an entry, consider making a backup of the entry details by using the Export feature or by saving the QR code.
- Confirmation: Always double-check the entry details before confirming the deletion to avoid accidental removal of the wrong entry.
Exporting the vault in EasyAuth allows you to create a backup of your entry details in a file. This file can be used to restore your entries later or transfer them to another device. Be aware that when exporting your entries your secret keys will be exported in plain-text (not encrypted). You should take appropriate precautions to secure the exported files.
-
Open the Export Dialog:
- In the main window, navigate to the "File" menu.
- Select "Export/Import" from the dropdown menu. This will open the Export/Import Dialog.
-
Choose Export Format:
- In the Export Dialog, you will be prompted to choose the export format. EasyAuth supports the following formats:
- JSON: Exports the entries in JSON format.
- URI: Exports the entries as URIs. This is the format used by FreeOTP+ and other authenticators.
- In the Export Dialog, you will be prompted to choose the export format. EasyAuth supports the following formats:
-
Select Export Location:
- Click the "Choose export file" button to choose the location where you want to save the export file.
- A file chooser dialog will open.
- Navigate to the desired directory and enter a name for the export file.
- Click "Save".
- Once the export is complete, an acknowledgement message will appear. Click OK to return to the main window.
-
(Optional) Verify Export:
- Navigate to the directory where you saved the export file.
- Verify that the file has been created and contains the expected entry details.
- Regular Backups: Regularly export your entries to ensure you have an up-to-date backup.
- Secure Storage: Store the export file in a secure location to protect your entry details.
Importing entries in EasyAuth allows you to restore entry details from a previously exported file. This is useful for recovering entries or migrating them from a different device. Note: Import will merge items from the selected file into your current vault. Duplicates will be ignored and conflicts flagged with an exclamation point.
-
Open the Import Dialog:
- In the main window, navigate to the "File" menu.
- Select "Export/Import" from the dropdown menu. This will open the Export/Import Dialog.
-
Select Import File:
- Click the "Choose import file" button to choose the file you want to import.
- A file chooser dialog will open.
- Navigate to the directory containing the import file and select it.
- Click "Open"
-
Preview Imported Items:
- A confirmation message will appear with a information message: "Import will merge these items with your current vault."
- The message includes a preview of the entries to be imported.
- Review the entry details to ensure they represent the desired entries to be imported.
-
Start Import:
- Click "Yes" to start the import process.
- Once the export is complete, an acknowledgement message will appear. Click OK to return to the main window.
-
(Optional) Verify Import:
- The imported entries should now appear in the list of entries in the main window.
- Verify that the entry details have been restored correctly.
- A merge conflict can occur if an entry has the same provider and user but a different secret key. In this case both items appear in the vault with the merged item displaying an exclamation point after the provider name.
- Check File Format: Ensure that the import file is in the correct format (JSON or URI) supported by EasyAuth.
- Backup Before Importing: Consider exporting your current entries before importing new ones to avoid data loss.
If you install EasyAuth on multiple devices, the way to migrate your vault is to use Export/Import. Export the vault from the original device (which yields an unencrypted plain text file) and then Import this file to the destination device. See section 5.1.
Note that simply doing a file copy of a vault to a different device doesn't work. If you attempt this EasyAuth will report the vault as empty and the console log will show an error "Invalid vault format" because the vault is cryptographically tied to a specific device.
The Preferences Dialog allows you to customize various aspects of EasyAuth's behavior and appearance.
-
Open the Preferences Dialog:
- In the main window, navigate to the "File" menu.
- Select "Preferences" from the dropdown menu. This will open the Preferences Dialog.
-
Select desired preferences:
- Turn on a preference by checking the checkbox next to an item, or turn it off by unchecking the checkbox.
- Click "Apply" to apply the settings immediately without closing the dialog.
- Click "OK" to apply the settings and close the dialog.
- The "Restore Defaults" button will reset the preferences to their original settings.
- Display provider favicons. (Default)
The entry list in the main window will include the favorite icon for each provider (or a single initial if the provider is not found in the provider list.) Displaying the icons makes it easier to identify providers. - Secret key initially hidden when dialog opens
This preference displays dots in the "Secret Key" field when the View Vault Details dialog opens. - Allowed to scan screen for QR code
Gives permission to EasyAuth to scan the display for QR code which is the fastest and simplest way to store secret keys in the vault. Revoking this permission will require manually entering the secret key which is tedious and error-prone. - Hide window during QR code scan
The EasyAuth window will momentarily disappear during QR code scan in order to reveal a QR code that may be partially obscured by EasyAuth itself. - Minimize application after TOTP copy to clipboard
Once a TOTP has been copied to the clipboard a typical workflow no longer needs EasyAuth to be displayed. This preference will minimize EasyAuth so you can proceed with logging in. - Theme.
Theme determines the color scheme used for the appearance of the user interface, light or dark. Light is the default, with dark text on a light background. The dark option presents light text on a dark background.
EasyAuth manages three external files:
- the "vault": the stored secret keys and associated information.
- configuration file: preference settings
- window config file: application window size and position
The vault is stored in a JSON formatted file. All the data is in plain-text except for the secret key which is encrypted. An example entry might look like this:
{
"issuer": "PayPal",
"label": "steve@gmail.com",
"secret": "gAAAAABnlFRLI45-j3RzwJZrOH7x_YMIScNsBt-ZYhjnnEZ3uAi-YR5alta_SDcQv
0Bsq9rW3vi3OK7ZWP72cIEIfPHruW8NIEC81OVuZRwxa3eZJM2NprU=",
"last_used": "2025-01-26 14:48:41",
"used_frequency": 2,
"favorite": false,
"icon": null
}
The default location for the vault is revealed in the About box. On Linux the default is:
~/.var/app/org.redpoint.EasyAuth/data/vault.json
It is possible to specify an alternate location by changing a value in the config file (see below)
The Export function decrypts the secret keys and the exported file stores all fields as plain-text.
The user's preference settings are saved in a config file that uses standard .ini format. The default settings are as follows:
[Settings]
display_favicons = True
secret_key_hidden = False
scan_permission = False
minimize_after_copy = False
minimize_during_qr_search = False
language = English
theme_name = light
[System]
alt_id =
win_data_dir = /home/<user>/Roaming/org.redpoint.EasyAuth/data
linux_data_dir = /home/<user>/.var/app/org.redpoint.EasyAuth/data
log_level = 20
The default location for the config file is: ~/.config/EasyAuth/config.ini
During startup EasyAuth looks for the config file in the default location and if it isn't found will create it with default settings.
The config file has two sections: 'Settings' is for settings the user can manager via the Preferences dialog. 'System' are "hidden" settings that are not available in the Preferences dialog but can be modified by advanced users via a text editor.
Hidden settings should be modified with caution as mis-configuration may cause the application to fail.
log_level = 20
The setting describes the logging level for output of log messages. There are four choices: 10,20,30,40.
10 = DEBUG
20 = INFO
30 = WARNING
40 = ERROR
Read more about Python logging.
win_data_dir = /home/<user>/AppData/Roaming/org.redpoint.EasyAuth/data
linux_data_dir = /home/<user>/.var/app/org.redpoint.EasyAuth/data
These settings specify the vault location on Windows and Linux, respectively. Modify this setting if it is desirable to save the vault in another location.
The application main window position and size are saved in a separate file when the application closes so it can be opened in the same place on next launch. This file is named window.conf and located in the EasyAuth config folder ~/.config/EasyAuth.
usage: easyauth [-h] [-c CONFIG_FILE]
A 2FA authenticator to hold your secret keys and generate one-time passwords.
options:
-h, --help show this help message and exit
-c CONFIG_FILE, --config_file CONFIG_FILE
(Optional) The complete (absolute) path to the config
file to be used for Preferences by the application.
Most users can ignore this as the preferred mode of
operation is to let the application use a default
location.
Advanced users may want to sometimes use EasyAuth with different settings. By specifying an alternate config file on the command line the application can be started with customized settings.