This page describes the process to configure and use Two-Factor Authentication (2FA) with the CS Department's Zimbra email service (which includes webmail, IMAP, POP, and ActiveSync access methods). The use of 2FA is important in limiting the negative impacts of compromised passwords.
Heads-Up! Possible inconvenience and account lock-out ahead!It is important to complete this process with all of your email clients in one pass, especially if you are adding 2FA to an account that has been in use for a while. Once 2FA is enabled for your account, your regular account password will no longer work for sending or receiving email through most email clients. If you forget to reconfigure one or more clients, and those clients continue to try to use your regular password, they are likely to be temporarily banned from communicating with the mail servers. This ban uses your IP address, so it is possible you could see broader impacts if, for instance, your home internet service NATs all of your devices behind a single IP. In this case, you might see an IP ban block access even for devices that you already reconfigured. If you get started on this process and find that your clients are no longer able to communicate with the mail servers, the first thing you should do is repeat your inventory of devices and make sure you have found everything that might be using your email account. Disable the email clients on all of those devices, then wait 60 minutes before continuing the process. This should allow time for the IP bans to clear, at which point you should reconfigure, and only then, enable each client one-at-a-time. |
Overview
When you configure your CS Zimbra account to use 2FA, the way you access your email will change. That said, other than the steps to reconfigure your account, we expect your day-to-day experience will change very little.
Access to the Zimbra webmail interface from your desktop or laptop (to read/write email, use the Zimbra calendar, or manage your account's configuration) will continue to require your regular CS password but will also require a 6-digit code generated by an "authenticator" application. For most CS users, a compatible authenticator app already exists on their smartphone. When you login to the webmail interface, a long-lived cookie is saved by your browser so that you will not need to re-enter a code for a few weeks (up to 30 days). The standard for generating the 6-digit code, TOTP: Time-Based One-Time Password Algorithm, is specified in RFC 6238.
Access to CS email from applications such as Thunderbird, Mac Mail, Outlook, iPhone Mail, Android Mail, etc. will use the same configuration except you will not use your regular CS password. Instead, each of your applications or devices will get its own distinct "application passcode" that is generated by Zimbra. You will need to update the configuration of each of your applications and devices; however, most will simply note that the old password is not working and prompt you for the new one. The key to the enhanced security is that you do not commit these application passcodes to memory; rather, you use the "remember password" feature of the application or device. (If a person doesn't know their password, they cannot inadvertantly disclose it to a phishing site.) In the event that a given device is lost or compromised, the associated application passcode can be disabled without you having to change all your passwords on all your devices. Keen-eyed readers will note that using application passcodes does not constitute 2FA. This is true; however, this approach is a distinct improvement over using a single, universal password. Additionally, to generate new application passcodes or otherwise manage one's account requires using the webmail interface which does require 2FA.
While this page generically refers to CS email, it also includes access to the Zimbra calendar via CalDAV. If you are using the calendar feature on applications or devices outside of webmail, the CalDAV access method also uses application passcodes.
Authenticator Applications
As part of setting up 2FA on your Zimbra account, you will need a smartphone application to generate the 6-digit codes mentioned above. The codes are calculated based on the current time and a shared secret specific to your account generated by the Zimbra server and then stored in your smartphone. Often, the shared secret is represented by a QR code that the app scans. In the case of Zimbra, no QR code is generated -- Zimbra provides the shared secret as text that you enter "manually" into your authenticator app.
If you already have the Duo Mobile app installed on your smartphone (as many Princeton folks do), it has the ability to generate these TOTP codes. It should be noted that Zimbra is not integrated with Duo as it is elsewhere on campus -- this means that you will not receive a push notification that you can simply "accept." Instead, you will need to enter the 6-digit code manually when prompted by Zimbra during a login to webmail. See the Duo Mobile app documentation on Third-Party Accounts and note that in steps 4 & 5 on that page, you will select the "Add other account" button, then "Use activation code", and enter the shared secret from Zimbra in the following screen.
In addition to the Duo Mobile app, the Zimbra email service is also compatible with Google Authenticator, Yubico Authenticator, or other TOTP applications, including password manager applications such as LastPass.
Ready, Set, Go!
While the process to enable your CS email account for 2FA is straightforward, it is best done in one sitting. Before starting, we recommend that you:
- Review the instructions on this page
- Install a TOTP authenticator app (e.g., Duo Mobile, Google Authenticator, or Yubico Authenticator) on your smartphone.
- "Inventory" the devices and applications you use to access CS email.
- Determine how many application passcodes you will need to establish initially. For example, if you access email from your iPhone, from your desktop computer with Thunderbird, and from your laptop with Thunderbird, you will end up needing 3 application passcodes.
With the above completed, follow the steps in the Detailed Instructions section below to enable 2FA in Zimbra, provision your initial application passcodes, and update the passwords in your email applications to use the corresponding application passcode. We recommend that you update your email applications (e.g., iPhone, Thunderbird, etc.) in the same sitting otherwise those devices may repeatedly attempt (and subsequently fail) to connect. If you have more than one or two clients, we strongly recommend that you disable all clients before starting this process and only re-enable them after they have been properly configured with 2FA or Application Passcodes as appropriate.
If you have any questions about the process, please contact CS Staff.
That's it! Enjoy the improved security of your email account but, as always, remain vigilant.
Detailed Instructions
These instructions are taken almost verbatim from the Zimbra Wiki, where you can look for more information or details.
PLEASE NOTE: Users of email clients such as Thunderbird, MS Outlook, (al)Pine, Mac Mail, iPhone or Android Mail, or others are very likely to require Application Passcodes to allow these applications to access your account after configuring 2FA. This is normal and expected. Please see the relevant section of this page after configuring 2FA and reconfigure the password in your application appropriately.
How to enable two-factor authentication feature (User Web Client)
First, login to https://webmail.cs.princeton.edu/ - navigate to Preferences > Accounts.
In the Primary Account Settings block, scroll to Account Security and click on Setup two-step authentication
The first step shows a brief description about two-step authentication. Click on Begin Setup.
You will be asked to provide your password to confirm setup of 2FA. After typing your password, click on Next.
The next step is to configure your 2FA application. The Two Factor authentication wizard will show a Wiki link with the OTP Apps Zimbra recommends to use, but you should able to use any TOTP-compatible authenticator application.
The 2FA wizard will show a unique key that you must enter in your smartphone TOTP app. Do not leave this screen without recording the key in your TOTP app.
Finishing the configuration in the Web Client
Once your TOTP app is configured and showing rotating 6 digit codes, click Next and enter a code in the confirmation prompt.
The 2FA feature is now enabled, and you will be prompted for a code in each new browser, smartphone, computer, or app where your account is accessed.
Under Preferences > Accounts > Account Security, you will see more options, including one-time codes, Trusted Devices, and Application Passcodes.
One Time Codes
In the event your TOTP applications stops working, or you lose access to your smartphone with the authenticator application on it, a small number of pre-generated codes are available for emergency access. You can click on the One-time codes View option to see the codes. Obviously, this should be done before you need emergency access. These codes must be kept secure (written somewhere, in another device, etc.) and not used for any other purpose. As their name implies, each of these codes can only be used once to login.
Application Passcodes
IMAP or ActiveSync clients often do not support the UI flow needed for TOTP authentication. For these applications, you will need to generate an application passcode. These are essentially passwords used for a single purpose, such as connecting your iPhone to your email. Application passcodes must never be reused for any other purpose, and it is preferable if you do not even know or remember them after configuring them, so that they cannot be phished.
Application passcodes are randomly generated and can be given a custom label and revoked by their label.
How to create an application passcode
You can create an application passcode by navigating to Preferences > Accounts > Applications and selecting the Add Application Code button. Enter the application name in the Add Application Code dialog and click Next. An application passcode will be generated which can be used to sign in to your account.
Note that once you enable 2FA on your account, you will also no longer authenticate to the SMTP server with your normal password. Any mail clients which require SMTP (most) should use the same Application Passcode that you configured for the IMAP connection. You can, of course, use a separate Application Passcode for SMTP if you wish.
How to revoke an application passcode
Once an application passcode is generated, you can revoke it by navigating to Preferences > Accounts > Applications. Select the appropriate code from the list, and click Revoke Code.
I am logged in to Zimbra, but under Preferences -> Accounts, why don't I see an option to enable 2FA?
I just enabled 2FA and now my email on my smartphone (or other mail client) doesn't work. What should I do?
This is usually because the client in question does not support the 2FA authentication workflow. Don't worry; this is normal and expected. What you need is to generate an Application Passcode for that client and use that passcode as your password only for that client.
After enabling 2FA, how can I continue to use pine/alpine without memorizing an Application Passcode?
As implied by the question, and noted in the main page body, pine/alpine does not support the required workflow for 2FA login. You will need to generate an Application Passcode for pine/alpine. However, since it is not recommended to memorize an application passcode (in order to make it impossible for someone to phish it from you), you should configure alpine to remember the passcode for you. To do this, in your home directory type:
echo "" > .alpine.passfile
..before starting alpine. The next time you run alpine, you will be prompted to configure a master password for the encryption on that file. Once that is configured, generate an Application Passcode for alpine, enter it as the IMAP login password, and allow alpine to save it. Next, send yourself an email using the same passcode to authenticate to the SMTP server, and again allow alpine to save it. For future runs of alpine, you will be asked for your master password to decrypt the password store file and your IMAP and SMTP connections will automatically use the saved passcode.
If, at some point, you revoke the application passcode you used for alpine, remember to empty the .alpine.passfile file in order to avoid failed logins to the mail service.
After enabling 2FA, I can read email, but can no longer send email. The SMTP server just hangs or rejects my connection.
Once you enable 2FA on your account, you will no longer be able to authenticate to the SMTP server with your normal password. Any mail clients which require SMTP (most) will need to use the same Application Passcode that you configured for the IMAP connection. You can, of course, use a separate Application Passcode for SMTP if you wish.
If you are using an iOS or Android device, you might opt to configure it using Activesync, which will still require an application passcode, but you'll only need to enter it once.