search

maldua-suite / zimbra-ose-2fa

Two factor authentication for Zimbra OSE
13 stars 5 forks source link

readme

Zimbra OSE 2FA

Zimbra 2FA Splash

About

MALDUA'S Zimbra OSE 2FA Extension & Administration Zimlet brought to you by BTACTIC, open source & cloud solutions.

Two-factor authentication adds an additional layer of security to your Zimbra login. Thanks to a third-party authenticator such as Google Authenticator Zimbra users are now required to enter a randomly generated code.

Supported Zimbra versions

Non support

Features

Integrated with Zimbra Webclient UI

Seamless integrated with native Zimbra Webclient UI for 2FA.

Setup two-step authentication ...

Setup two-step authentication wizard

Includes QR support

Setup two-step authentication wizard with QR

Basic 2FA

An additional authentication factor based on TOTP (Time-based One-Time Passwords). This is compatible with Google Authenticator or Authy.

Verify step

Trusted devices

Mark your usual device as trusted so that you are not asked for 2FA each time you login.

Application specific passwords

Do you have Imap or pop3 applications that do not support 2FA? Keep using them with an specific password for each one of them.

Application name Application passcode Applications in Webclient

Scratch codes

Scratch or one-time use codes are generated so that you can write them down in a paper just in case your 2FA application no longer works for you.

Scratch codes in Webclient Scratch popup

Network Edition binary compatibility upgrade

Both Zimbra OSE 2FA and current Zimbra Network Edition share a design based on a public codebase from around 2016.

Take a look at this scenario:

Once you have upgraded to ZCS NE 8.8.15 all of the 2FA features that were enabled/used in ZCS OSE 8.8.15 + zimbra-ose-2fa setup should keep working. No need to reissue 2FA codes and ask final users to update their Google Authenticator, Authy or specific Thunderbird/Imap client password.

Admin documentation

Basic Management

When creating or editing a class of service or an account there is an additional tab named 2FA (Maldua) where you can:

Admin Zimlet for Two Factor Authentication

Disabling 2FA for an user

When disabling 2FA for an user you need to make sure to:

Otherwise the user will be asked for the 2FA code when loging in if he has ever setup 2FA in the past.

Extra documentation

In addition to the documentation you can find in this README you should be also checking:

.

Not everything described there applies to this Open Source implementation but it can be helpful to understand how the technology works.

Upgrade

From 0.7.0 version

If you have installed 0.7.0 version please run as root:

cp /opt/zimbra/jetty/webapps/zimbra/public/TwoFactorSetup.jsp_2FAQR_COPY /opt/zimbra/jetty/webapps/zimbra/public/TwoFactorSetup.jsp
cp /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js_2FAQR_COPY /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js

before running the installation.

From 0.6.0 version

If you have installed 0.6.0 version please uninstall the QR zimlet with:

su - zimbra -c 'zmzimletctl undeploy com_btactic_twofactorauth_qr'

because you won't need it anymore.

Installation

Time sync warning

As per Zimbra installation requisites your Operating System should have its time in sync with global clocks thanks to tools such as:

otherwise the final user might get a wrong password even if it's the correct one.

Please notice that the device where Google Authenticator is needs its time to be in sync too.

Finally if you ever need it you can check zimbraTwoFactorTimeWindowOffset attribute described on Steps to fix 2FA setup error - Zimbra Wiki.

Automatic installation

Notice: In a Multi-Server cluster these commands have to be run on each one of the mailbox nodes.

sudo -i # Become root
cd /tmp
wget 'https://github.com/maldua-suite/zimbra-ose-2fa/releases/download/v0.8.0/zimbra-ose-2fa_0.8.0.tar.gz'
tar xzf zimbra-ose-2fa_0.8.0.tar.gz
cd zimbra-ose-2fa_0.8.0

For regular installation or upgrade you can run:

./install.sh

instead .

In order for the two-factor authentication extension and the adminZimlet to apply you need to restart mailboxd with:

sudo -i # Become root
su - zimbra -c 'zmmailboxdctl restart'

Manual installation

Notice: In a Multi-Server cluster these commands have to be run on each one of the mailbox nodes.

WARNING: Please change 0.8.0 with whatever it's the latest released version.

sudo -i # Become root
cd /tmp
wget 'https://github.com/maldua-suite/zimbra-ose-2fa/releases/download/v0.8.0/zimbra-ose-2fa_0.8.0.tar.gz'
tar xzf zimbra-ose-2fa_0.8.0.tar.gz
chown zimbra:zimbra zimbra-ose-2fa_0.8.0
chown zimbra:zimbra zimbra-ose-2fa_0.8.0/com_btactic_twofactorauth_admin.zip
cd zimbra-ose-2fa_0.8.0
cp zetatwofactorauth.jar /opt/zimbra/lib/ext/twofactorauth/zetatwofactorauth.jar
su - zimbra -c 'zmzimletctl -l deploy /tmp/zimbra-ose-2fa_0.8.0/com_btactic_twofactorauth_admin.zip'

chown zimbra:zimbra qr
chown zimbra:zimbra qr/qrcode.js
chown zimbra:zimbra qr/TwoFactor_qr.js

cp qr/qrcode.js /opt/zimbra/jetty/webapps/zimbra/js
cp qr/TwoFactor_qr.js /opt/zimbra/jetty/webapps/zimbra/js
chown zimbra:zimbra /opt/zimbra/jetty/webapps/zimbra/js/qrcode.js
chown zimbra:zimbra /opt/zimbra/jetty/webapps/zimbra/js/TwoFactor_qr.js
su - zimbra -c 'cat /opt/zimbra/jetty/webapps/zimbra/js/qrcode.js | gzip -c > /opt/zimbra/jetty/webapps/zimbra/js/qrcode.js.zgz'
su - zimbra -c 'cat /opt/zimbra/jetty/webapps/zimbra/js/TwoFactor_qr.js | gzip -c > /opt/zimbra/jetty/webapps/zimbra/js/TwoFactor_qr.js.zgz'

cp /opt/zimbra/jetty/webapps/zimbra/public/TwoFactorSetup.jsp /opt/zimbra/jetty/webapps/zimbra/public/TwoFactorSetup.jsp_2FAQR_COPY
sed -i 's~</head>~<script src="https://github.com/maldua-suite/zimbra-ose-2fa/raw/main/${contextPath}/js/qrcode.js<%=ext%>?v=${version}"></script><script src="https://github.com/maldua-suite/zimbra-ose-2fa/raw/main/${contextPath}/js/TwoFactor_qr.js<%=ext%>?v=${version}"></script></head>~g' /opt/zimbra/jetty/webapps/zimbra/public/TwoFactorSetup.jsp

cp /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js_2FAQR_COPY
cp /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js.zgz /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js.zgz_2FAQR_COPY
cat /opt/zimbra/jetty/webapps/zimbra/js/qrcode.js >> /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js
cat /opt/zimbra/jetty/webapps/zimbra/js/TwoFactor_qr.js >> /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js
su - zimbra -c 'cat /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js | gzip -c > /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js.zgz'

In order for the two-factor authentication extension and the adminZimlet to apply you need to restart mailboxd with:

sudo -i # Become root
su - zimbra -c 'zmmailboxdctl restart'

Uninstallation

sudo -i # Become root
su - zimbra -c 'zmzimletctl undeploy com_btactic_twofactorauth_admin'
mv /opt/zimbra/lib/ext/twofactorauth/zetatwofactorauth.jar /root/zetatwofactorauth.jar-REMOVED-ON-YYYY-MM-DD
cp /opt/zimbra/jetty/webapps/zimbra/public/TwoFactorSetup.jsp_2FAQR_COPY /opt/zimbra/jetty/webapps/zimbra/public/TwoFactorSetup.jsp
cp /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js_2FAQR_COPY /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js
cp /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js.zgz_2FAQR_COPY /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js.zgz

mkdir /root/zetaqraddon-REMOVED-ON-YYYY-MM-DD

mv /opt/zimbra/jetty/webapps/zimbra/js/qrcode.js /root/zetaqraddon-REMOVED-ON-YYYY-MM-DD
mv /opt/zimbra/jetty/webapps/zimbra/js/TwoFactor_qr.js /root/zetaqraddon-REMOVED-ON-YYYY-MM-DD
mv /opt/zimbra/jetty/webapps/zimbra/js/qrcode.js.zgz /root/zetaqraddon-REMOVED-ON-YYYY-MM-DD
mv /opt/zimbra/jetty/webapps/zimbra/js/TwoFactor_qr.js.zgz /root/zetaqraddon-REMOVED-ON-YYYY-MM-DD

mv /opt/zimbra/jetty/webapps/zimbra/public/TwoFactorSetup.jsp_2FAQR_COPY /root/zetaqraddon-REMOVED-ON-YYYY-MM-DD
mv /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js_2FAQR_COPY /root/zetaqraddon-REMOVED-ON-YYYY-MM-DD
mv /opt/zimbra/jetty/webapps/zimbra/js/Preferences_all.js.zgz_2FAQR_COPY /root/zetaqraddon-REMOVED-ON-YYYY-MM-DD

In order for the removal to be applied you need to restart mailboxd with:

sudo -i # Become root
su - zimbra -c 'zmmailboxdctl restart'

.

Additional notes

The QR addon modifies some stock Zimbra files.

Those are:

.

Automatic installation makes copies of those files here:

.

Developer documentation

This documentation is aimed at developers, not at admins.

How to build the extension

How to install the extension

How to build the admin zimlet

How to install the admin zimlet

How to release the extension and admin zimlet

Some background

This is some background for those of you that enjoy reading developer stories.

At the Zimbra Roadmap and Product Update from February, 2015 you can read about how for ZCS 8.7 there was a Mobile Gateway section that mentioned: Zimbra Mobile Gateway + Push Notifications + 2-Factor Security.

This was actually ZCS 8.6 being improved for having such features.

Development versions of ZCS OSE 8.6 had an initial implementation of 2FA but, then, someone at Zimbra, decided that it was worth it moving it to the NE version as an extension (2FA was not going to be available at OSE version!). More over the 2FA webclient support will be refactored in such a way so that alternative 2FA implementations could be written by other developers or companies.

You can take a look at commits from those days:

So... this extension is an affirmative answer to this question...

Is it possible to rewrite the old 8.6 code for 2FA so that it can be ported into its own extension?

Licenses

License (Extension)

Zimbra OSE 2FA Extension
Copyright (C) 2023 BTACTIC, S.C.C.L.

Zimbra Collaboration Suite Server
Copyright (C) 2007, 2008, 2009, 2010, 2013, 2014 Zimbra, Inc.

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software Foundation,
version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program.
If not, see <http://www.gnu.org/licenses/>.

License (Administration zimlet)

Zimbra OSE 2FA Administration zimlet
Copyright (C) 2023 BTACTIC, S.C.C.L.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see http://www.gnu.org/licenses/.

License (QR Addon)

Zimbra OSE 2FA QR Addon
Copyright (C) 2023 BTACTIC, S.C.C.L.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see http://www.gnu.org/licenses/.

License (QRJS library)

The MIT License (MIT)
---------------------
Copyright (c) 2012 davidshimjs

Permission is hereby granted, free of charge,
to any person obtaining a copy of this software and associated
 documentation files (the "Software"),
to deal in the Software without restriction,
including without limitation the rights to use, copy,
 modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons
 to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall
 be included in all copies or substantial portions
 of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
 OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
 OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH
 THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.