Zimbra Two-factor authentication

Zimbra Two-factor authentication

   KB 22531        Last updated on 2018-01-18  

(0 votes)

Coming with Zimbra Collaboration 8.7 (only in Network Edition) is an exciting new feature: two-factor authentication (also known as 2FA). Two-factor authentication is a technology that provides identification of users with the combination of two different components. These components may be something that the user knows (like a password, UserID, etc) and something that the user possesses (a good example can be a smartphone, or USB-key, etc.)


How it works

The use of two-factor authentication to prove your users’ identity is based on the premise that an unauthorized actor is unlikely to be able to supply both factors required for access. If, in an authentication attempt, at least one of the components is missing or incorrect, the user’s identity is not established with sufficient certainty and access to the user Zimbra Mailbox being protected by two-factor authentication remains blocked.

(source: Wikipedia)

How to enable it

Note: Bug 105056 noted a problem that can occur during a rolling upgrade if two factor authentication is enabled before all mailbox servers have been upgraded to 8.7. In particular, pre-8.7 mailbox servers are not compatible with 2FA.

Accordingly, it is recommended that 2FA is not enabled until all mailbox servers have been upgraded to 8.7.

Two-factor authentication Requires A License Key

To see if your Zimbra server has the two-factor authentication enabled, you can check from the CLI. If you want this feature and currently do not have it as a part of your license, please contact your regional sales manager, so you can get a new license issued, with the feature enabled. - Please note the related bugs posted below.

zmlicense -p | egrep -i 'Twofactor'

If you need to install the new license, you should do the following after installing the license to get the two-factor authentication working:

zmprov fc license

Or a full Zimbra Collaboration restart :

zmcontrol restart

Admin Console

The two-factor authentication feature must be enabled in the Admin Console, and it can be enabled at User or Class-of-service level. This allows precise control over the users Security. Therefore, you can enable this feature just for the most critical Mailboxes in the environment, to all users, etc.

To enable it in the Admin Console: Home > Configure > Class of service > yourCOSname > Advanced > Two Factor Authentication

Use the check-boxes to:

  • Enable two-factor authentication: enable or disable the two-factor authentication feature. User will have to setup two-factor authentication using Web Client after enable step.
  • Require two-step authentication: all users will need to configure the 2FA
  • Number of one-time codes to generate (per each user)
  • Enable application passcodes: for legacy applications that don’t support 2FA. You can generate exceptions codes for them.


How to enable two-factor authentication feature (User Web Client)

Once the Admin has been enabled and configured the 2FA, users will see a new option under Preferences > Accounts > Account Security, called Setup two-step authentication


If the user clicks on the Setup two-step authentication link, the configuration process will begin.

The first step shows a brief description about two-step authentication. The user must click on Begin Setup.


Next step will be introduce the user current password, if you remember the theory of 2FA, this will be “the component the user knows”. Once the user wrote the password, click on Next.


The next step retrieves the other component the user must have, in this case an app in the smartphone. The Two Factor authentication wizard will show a Wiki link with the OTP Apps Zimbra recommends to use.


Once the user has installed the App, the 2FA wizard will show a unique key that the user must enter in the Smartphone OTP App.


How to Install and Configure an OTP smartphone app

In this example, I will use Google authenticator, but please visit our Wiki where you can find other options. In the App Store or Play Store, search by Google authenticator, then click Install.


Once the app is installed, open it, and click Begin Setup.


The app will ask if you want to configure a Manual entry or Scan a barcode. Zimbra Collaboration 8.7 supports only manual entry for now. However, keep in mind the next Bug where it is being discussed to add the option to support barcodes.


To configure the App, the users must add an email address and the unique Key from the Zimbra Web Client.


All done! Now the app is configured and will show a 6-digit code that changes after 15 seconds.


Finishing the configuration in the Web Client

Once the user has the App configured and showing the 6 digit code, the user can enter the Code in the wizard window and click Next.


The two-step authentication feature is now enabled, and the user will be prompted for a code in each new Browser, smartphone, computer, or app where he or she tries to access the account.


In the users’ Preferences > Accounts > Account Security (if the Admin has enabled these options under the COS), the user will see more options like the one-time codes, Trusted devices, and Applications. as


Testing Zimbra Two-factor authentication

Testing a new Web Browser session in a new Computer

If the user now goes to another Web Browser, computer, smartphone, or if he or she tries to configure Zimbra Desktop, the user will successfully pass the two-factory authentication. For example on the Web Client: One-time Codes


With the two-factor authentication enabled, there may be a situation when the smartphone doesn’t have battery to answer the code challenge, or the device has been lost, etc. For cases like this, Zimbra introduces the One-time codes functionality. This function allow users to generate multiple codes to use in case of emergency. The total number of one-time codes can be configured by the Admin.

The user can click on the One-time codes View option to see the codes. The user must keep the codes secure (written somewhere, in another device, etc.).


Testing Zimbra Desktop with 2FA

  • Pending

Testing Zimbra Connector for Outlook with 2FA

  • Pending

Trusted Devices

Zimbra Web Client and Zimbra Touch Client can be specified trusted during the second stage of two-factor authentication. Once the computer/device is trusted user will only need to provide standard credentials, bypassing the two-factor code.

How to trust a computer/device

Once the user enters two-factor code in the login screen the user will have to select the check box Trust this computer and click Verify to trust the current computer/device. User can trust more than one computer/device.

Trusted Devices 1.jpg

How to revoke trusted computer/device

Once the user trust some computer/device user can revoke the trusted computer/device by navigating to Preferences > Accounts > Trusted Devices in Zimbra Web Client. User can revoke trust for the current device by clicking revoke this device link and all other trusted devices by clicking revoke all other devices link.

Trusted Devices 2.jpg

Application Passcode

Clients such as IMAP or ActiveSync do not support the UI flow needed for TOTP authentication. For these users need to generate application passcode.

Application passcodes:

  • Randomly generated.
  • Can be created by giving a label and revoked by their label.
  • Changing account password will revoke all application passcodes.

How to create an application passcode

User can create an application passcode by navigating to Preferences > Accounts > Applications and selecting Add Application Code button. User can enter the application name in the Add Application Code dialog and click Next. Application passcode will get generated and it can be used to sign in to your account.

Application specific passcode.png

How to revoke an application passcode

Once the user generates application passcode user can revoke it by navigating to Preferences > Accounts > Applications in Zimbra Web Client. User can revoke this application passcode after selecting the required name in the list.

Application passcode.png

Known Issues

Zimbra bugs

Bug 103824 {AUTH} Provide 2FA configuration capability in ZCO

Bug 104144 2fa:ReferenceError: AjxDebug is not defined when zimbraFeatureTwoFactorAuthRequired in multinode rolling upgrade environment

Bug 104648 allow clearing 2FA data from admin console

Bug 105678 Application specific password entry should be purged when 2FA disabled from Admin Console


Disabling two-factor authentication using Admin console does not clear user's two-factor data. Admin can disable user's two-factor authentication in case user is facing issues with authentication using TOTP/scratch codes. Re-enabling user's two-factor authentication using Admin console after user's problem has got resolved will allow user to use two-factor authentication. In future, Bug 104648 will allow Admin to clear user's two-factor data.

Third party issues

Issue - Mail client issues with application passcode

Scenario: User's zimbra account is configured on EWS Apple Mail and Thunderbird (IMAP/POP3). User enables 2FA using Web client, adds application passcodes for Apple Mail and Thunderbird applications.

Expected behavior: Both clients (Apple Mail) and Thunderbird should prompt for new password, user if enters application passcode, authentication should succeed.

Current behavior:

  • EWS Apple Mail app complains about connection failure and provides option to enter new password, wherein entering correct application passcode does not work. Only option is to Edit Account and provide new password, which works correctly.
  • Thunderbird (IMAP/POP3) prompts for new password after some time (after few minutes or sometimes after restarting client)

Additonal Content

Identified Support Issues

  • No Support issues reported yet.
Verified Against: Zimbra Collaboration Suite 8.7 Date Created: 02/03/2016
Article ID: https://wiki.zimbra.com/index.php?title=Zimbra_Two-factor_authentication Date Modified: 2018-01-18

Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Wiki/KB reviewed by SME1 SME2 Copyeditor Last edit by Jorge de la Cruz
Jump to: navigation, search