# User preferences

# Purpose

User preferences are settings that any user can change to customize the behavior or appearance of 2FAuth. They can be set by the user from the Settings > Options section of 2FAuth. As the name implies, when a user edits a preference, it only affects their own use, not that of other users.

2FAuth comes with a set of default values for user preferences. These defaults are defined to provide a good starting experience for every user, but as an administrator, you may want to control them for a consistent, streamlined, or corporate user experience. 2FAuth supports 2 ways to accomplish this:

Custom defaults

2FAuth defaults are overridden with your default values.

When a preference's default is customized, the custom value is applied to all users who didn't already personalized the preference themselves from the Settings > Options page of 2FAuth. The preference can still be modified by user.

Preference locking

Preferences are locked for change to user.

Regardless of the value of the preference, no user can edit a locked preference from the Settings > Options section of 2FAuth. The applied value is the last one, according to this priority order:

By the user
The custom default (if defined)
The 2FAuth default

The two features can be combined for a complete control over the preferences:

Custom defaults + Preference locking

Your custom defaults are enforced for all users.

Regardless of the value of the preference, no user can edit a locked preference from the Settings > Options section of 2FAuth. The applied value is yours, for everybody.

Custom defaults and preference locking are done by setting up dedicated environment variables.
Read the Environment variables page to learn how to define them.

# How to

Configuration is done per preference. To customize or lock a user preference, add a new environment variable using the following format:

[PREFIX]__[NAME_OF_THE_USER_PREFERENCE]=[value]

Where [PREFIX] is to be replaced with the expected behavior, [NAME_OF_THE_USER_PREFERENCE] with the name of the user preference you want to impact and [value] with the required value. (see Available preferences to discover the available preferences and their supported values)

Note the separator between the prefix and the var name, it's a double underscore: __

The 2 possible values to replace [PREFIX] are USERPREF_DEFAULT__ for setting a custom default value and USERPREF_LOCKED__ for locking. You have to set an environment variable for each behavior you want to apply.

A locking environment variable is only relevant if you want to lock a preference. If you don't need to, just don't declare such a variable, or delete the existing one.

# Example

Say you want to hide one-time password's icons in 2FAuth. The corresponding user preference is named SHOW_ACCOUNTS_ICONS.
Here are the environment variables to set, depending on your needs:

For a custom default only

For pref locking only

For a locked & enforced pref

USERPREF_DEFAULT__SHOW_ACCOUNTS_ICONS=false

USERPREF_LOCKED__SHOW_ACCOUNTS_ICONS=true

USERPREF_DEFAULT__SHOW_ACCOUNTS_ICONS=false
USERPREF_LOCKED__SHOW_ACCOUNTS_ICONS=true

Here is another example to control the theme of 2FAuth, given that the 2FAuth default for this preference is system (See THEME)

For a custom default only

For pref locking only

For a locked & enforced pref

USERPREF_DEFAULT__THEME=dark

USERPREF_LOCKED__THEME=true

USERPREF_DEFAULT__THEME=dark
USERPREF_LOCKED__THEME=true

# Impact on running app

Because of the way 2FAuth is built, adding new environment variables to enforce user preferences may not have an immediate effect if your 2FAuth instance is running.

You must rebuild the configuration cache of the app for the new variables to be loaded or restart your container if you use one. See the Environment variables section for details.

Also, logged-in users won't see any changes until they reconnect or visit the Settings > Options page of 2FAuth.

# Available preferences

AUTO_CLOSE_TIMEOUT
AUTO_SAVE_QRCODED_ACCOUNT
CLEAR_SEARCH_ON_COPY
CLOSE_OTP_ON_COPY
COPY_OTP_ON_DISPLAY
DEFAULT_CAPTURE_MODE
DISPLAY_MODE
FORMAT_PASSWORD
FORMAT_PASSWORD_BY
GET_OFFICIAL_ICONS
GET_OTP_ON_REQUEST
KICK_USER_AFTER
LANG
NOTIFY_ON_FAILED_LOGIN

NOTIFY_ON_NEW_AUTH_DEVICE
REMEMBER_ACTIVE_GROUP
REVEAL_DOTTED_OTP
SHOW_ACCOUNTS_ICONS
SHOW_EMAIL_IN_FOOTER
SHOW_NEXT_OTP
SHOW_OTP_AS_DOT
SORT_CASE_SENSITIVE
THEME
TIMEZONE
USE_BASIC_QRCODE_READER
USE_DIRECT_CAPTURE
VIEW_DEFAULT_GROUP_ON_COPY

# AUTO_CLOSE_TIMEOUT

number since v5.3

Description

Time before the on-screen one-time password is automatically closed.

Only relevant when GET_OTP_ON_REQUEST is set to true.

Default value

2

Accepted values

0: Disables the auto-close feature, the popup containing the OTP will never be closed
1 , 2 , 5: Duration (in minutes) before the auto-close is triggered

# AUTO_SAVE_QRCODED_ACCOUNT

boolean since v5.2

Description: Enables automatic registering of a 2FA account after scanning or uploading a QR code
Default value: false

# CLEAR_SEARCH_ON_COPY

boolean since v5.1

Description: Clears the search field when a click/tap is done on a one-time password to copy it
Default value: false

# CLOSE_OTP_ON_COPY

boolean since v1.1

Description

Closes the on-screen one-time password after a click/tap is done on it to copy it.

Only relevant when GET_OTP_ON_REQUEST is set to true.

Default value

false

# COPY_OTP_ON_DISPLAY

boolean since v3.4

Description

Triggers OTP copy to clipboard when the OTP is displayed.

Only relevant when GET_OTP_ON_REQUEST is set to true.

Default value

false

# DEFAULT_CAPTURE_MODE

string since v2.0

Description

Default input mode to use when Direct capture is enabled

Only relevant when USE_DIRECT_CAPTURE is set to true.

Default value

livescan

Accepted values

livescan: Launches the device camera for flashing QR codes
upload: Prompt to upload a file from the device
advancedForm: Opens the advanced form

# DISPLAY_MODE

string since v1.2

Description: The 2FA accounts display mode
Default value: list

Accepted values

list: Show 2FA accounts as a list
grid: Show 2FA accounts as a grid

# FORMAT_PASSWORD

boolean since v4.0

Description

Applies a digit formatting to one-time password display.

Additional preferences have to be set to refine this behavior:

FORMAT_PASSWORD_BY

Default value

true

# FORMAT_PASSWORD_BY

number since v4.0

Description

Formatting pattern applied to one-time password display.

Only relevant when FORMAT_PASSWORD is set to true.

Default value

0.5

Accepted values

0.5: Groups password digits by half, like #### ####
2: Groups password digits by pair, like ## ## ##
3: Groups password digits by trio, like ### ###

# GET_OFFICIAL_ICONS

boolean since v3.3

Description: Allows 2FAuth to fetch the web for official icons when registering a new 2FA account
Default value: true

# GET_OTP_ON_REQUEST

boolean since v4.1

Description

Generates and displays one-time passwords in a dedicated popup, only when the user requests them by clicking on 2FA account titles.

When disabled, OTPs are always visible on the main screen, no action is required to generate or rotate them.

Additional preferences may be set to refine this behavior:

CLOSE_OTP_ON_COPY
AUTO_CLOSE_TIMEOUT
COPY_OTP_ON_DISPLAY

Default value

true

# KICK_USER_AFTER

number since v1.3

Description: Action or inactivity time span that triggers the automatic disconnection of the user, aka Auto-lock
Default value: 15

Accepted values

0: Disables the auto-lock feature, the user will never be logged out
-1: Triggers user logout when a click/tap is done on a one-time password to copy it
1 , 5 , 10 , 15 , 30 , 60 , 1440: Time (in minutes) before the user is automatically disconnected

# LANG

string since v4.0

Description: The language used to translate the 2FAuth user interface
Default value: browser

Accepted values

browser: Uses the preferred language setting of the browser used to visit 2FAuth.
Any supported language code: The language code of any supported translation, for example fr, en or ja.
See the Crowdin project page for the full list.

# NOTIFY_ON_FAILED_LOGIN

boolean since v5.2

Description: Enables email notification of failed login attempts
Default value: false

# NOTIFY_ON_NEW_AUTH_DEVICE

boolean since v5.2

Description: Enables email notification of successful logon from a new device
Default value: false

# REMEMBER_ACTIVE_GROUP

boolean

Description: Saves the last group filter applied and restores it on your next visit
Default value: true

# REVEAL_DOTTED_OTP

boolean since v5.0

Description

Displays a button to make the OTP readable while it is obfuscated.

Only relevant when SHOW_OTP_AS_DOT is set to true.

Default value

false

# SHOW_ACCOUNTS_ICONS

boolean since v1.3

Description: Show/Hide the icons that depict 2FA accounts
Default value: true

# SHOW_EMAIL_IN_FOOTER

boolean since v5.4

Description: Switch between the old footer layout and the new one that displays the email address of the currently logged in user
Default value: true

# SHOW_NEXT_OTP

boolean since v5.5

Description: Previews the next OTP near the current valid OTP
Default value: false

# SHOW_OTP_AS_DOT

boolean since v1.1

Description

Obfuscates OTPs by replacing digits with dots.

Additional preferences may be set to refine this behavior:

REVEAL_DOTTED_OTP

Default value

false

# SORT_CASE_SENSITIVE

boolean since v3.3

Description: Applies case-sensitive sorting when reordering 2FA accounts
Default value: false

# THEME

string since v4.0

Description: The theme applied to the app pages
Default value: system

Accepted values

system: Uses the website appareance setting of the browser used to visit 2FAuth
light: Uses a light theme for backgrounds and page content
dark: Uses a dark theme for backgrounds and page content

# TIMEZONE

string since v5.2

Description: The time zone applied to all dates and times displayed in the 2FAuth user interface
Default value: UTC
Accepted values: Any timezone identifier, for example Africa/Asmara.
See List of TZ database time zones

# USE_BASIC_QRCODE_READER

boolean since v1.2

Description: Switches to an alternative QR code reader
Default value: false

# USE_DIRECT_CAPTURE

boolean since v2.0

Description

Skips the input mode selection screen.

Additional preferences have to be set to refine this behavior:

DEFAULT_CAPTURE_MODE

Default value

false

# VIEW_DEFAULT_GROUP_ON_COPY

boolean since v5.1

Description: Always return to the default group filter when a click/tap is done on a one-time password to copy it
Default value: false