Configuring 2FA for Zimbra (Email)

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.


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 step 4 on that page, you will tap the "No Barcode?" button to enter the shared secret from Zimbra in the "Key" field.

In addition to the Duo Mobile app, the Zimbra email service is also compatible with Google Authenticator, Yubico Authenticator, or other TOTP applications.

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:

  1. Review the instructions on this page
  2. Install a TOTP authenticator app (e.g., Duo Mobile, Google Authenticator, or Yubico Authenticator) on your smartphone.
  3. "Inventory" the devices and applications you use to access CS email.
  4. 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 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 - 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.

Application specific passcode.png

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.

Application passcode.png


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.