Two-Factor Authentication
Two-Factor Authentication (2FA) is an additional layer of security used to ensure that individuals trying to gain access to an online account are who they say they are. It typically involves combining two out of three types of credentials: something you know, such as an additional password, a PIN, or the answer to a security question; something you have, such as a physical device like a smartphone, security token, or smart card; and something you are, which involves biometric verification such as a fingerprint, retina scan, or voice recognition.
Stalwart Mail Server supports Two-Factor Authentication using Time-based One-Time Password (TOTP). TOTP is a form of 2FA where the second factor is a time-sensitive code generated by an application on a user's device. When setting up 2FA with TOTP, the Stalwart Mail Server and your authentication app share a secret key, which is used to generate TOTP codes. The authentication app generates a new, unique code every 30 seconds using the shared secret and the current time. Upon logging in, after entering your username and password, you’ll be prompted to enter the current TOTP code from your app. The server verifies this code using the same shared secret and the current time.
Using TOTP with Stalwart Mail Server significantly enhances the security of your email account, protecting your data from unauthorized access even if your password is compromised. TOTP is compatible with popular authentication apps like Google Authenticator and Authy, making it easy to use.
Enabling 2FA
Users can enable Two-Factor Authentication (2FA) on their email accounts by logging into the self-service portal. Once logged in, they need to click on the Two-factor Authentication link where the option to enable 2FA is available. A TOTP QR code will be presented, which users should scan using an authenticator app such as Google Authenticator or Authy. This process links the email account to the authenticator app, allowing users to generate the necessary codes for 2FA.
Administrators can enable 2FA on a user account by accessing the Manage Account section of the webadmin interface. Within the account configuration, administrators need to enter the OTPAuth URL. After configuring the OTPAuth URL, the administrator must share the TOTP code with the user so they can add it to their authentication app. This ensures that the user can generate the necessary codes for 2FA.
Both users and administrators should ensure that the authenticator app is properly set up and tested to avoid any access issues. Enabling 2FA significantly enhances the security of email accounts, providing robust protection against unauthorized access.
Two-factor authentication can only be managed from the self-service portal or the webadmin interface when Stalwart Mail Server is configured to use the internal directory. If the server is set up to use an external directory, such as LDAP or SQL, administrators need to manually add the OTP Auth URL as one of the account secrets to enable 2FA for user accounts.
Using 2FA
Two-factor authentication (2FA) can only be used with mail clients that support OAuth authentication and the OAUTHBEARER SASL mechanism. This is because, without OAuth, users would need to enter a new TOTP code each time they retrieve or send a message, which is impractical and in some cases impossible.
When using an OAuth authentication flow, the user is prompted for their password and a TOTP code during the initial setup. Once authentication is successful, an OAuth token is granted. This token can be automatically refreshed by the client, allowing continuous access without needing to re-enter a new TOTP code each time.
Legacy Applications
Application Passwords
For users with 2FA enabled, it is still possible to use legacy mail clients that do not support OAUTHBEARER by creating Application Passwords. An Application Password is a unique password that can be used in place of the user’s regular password. It allows access to the email account while maintaining the security benefits of 2FA.
Concatenated Passwords
Stalwarts offers a second alternative to access accounts protected by two-factor authentication. This method combines the user's password and TOTP code into a single string, allowing seamless integration with older systems.
To employ this technique, users simply concatenate their password and the current TOTP code, using a dollar sign ($) as a delimiter. For instance, if a user's password is "mysecret" and their authenticator app generates the TOTP code "976544," they would enter "mysecret$976544" in the password field.
This approach bridges the gap between modern security practices and legacy software, ensuring that users can maintain robust account protection without sacrificing compatibility with older applications.
Internal Storage
The settings for Two-Factor Authentication (2FA) using Time-based One-Time Password (TOTP) are securely stored within the user's account as one of the account's secrets. These settings are encapsulated in an OTP Auth URL, which provides all the necessary information for generating TOTP codes.
An OTP Auth URL is a standardized format used to represent the secret key and configuration required by TOTP authenticator apps. It contains the following components:
- Secret Key: The unique key shared between the server and the authenticator app, used to generate time-based one-time passwords.
- Issuer: The service or organization that issues the OTP, typically the name of the email service or domain.
- Account Name: The user’s account identifier, often the email address.
- Algorithm: The hashing algorithm used, usually HMAC-SHA1.
- Digits: The number of digits in the generated OTP, typically six.
- Period: The time period for which the OTP is valid, commonly 30 seconds.
The OTP Auth URL is formatted as a URI, starting with "otpauth://totp/" followed by the issuer, account name, and query parameters containing the secret key and other settings. For example, an OTP Auth URL might look like this: otpauth://totp/issuer:accountname?secret=SECRETKEY&issuer=issuer&algorithm=SHA1&digits=6&period=30.
By storing the TOTP settings as an OTP Auth URL, Stalwart Mail Server ensures that all necessary information is securely and conveniently encapsulated. This approach simplifies the process of setting up and managing Two-Factor Authentication, providing users with a seamless and secure experience.