Zextras Auth

What is Zextras Auth

Zextras Auth is currently under development, some of its features are only released as a public beta while others have not been implemented yet.

Zextras Auth allows to manage all the Authentication Strategies (user/pwd, token, SAML, 2FA, MobilePwd, QrCode) and Service Authorizations. It also provides additional authentication-related features such as custom Login pages, profiling and security.

It is backward-compatible with Zimbra Custom Auth, it can manage QR Authentication form Mobile App (Team / Drive) along with multiple EAS Credential and provides a single point for the User Gateway Management (aka User Profile)

Zextras Auth provides a single entry point for:

Authentication
Authorization
Session Management
External Auth Federation

Features

Zextras Auth is currently under development, some of its features are only released as a public beta while others have not been implemented yet.

Credentials Management
- Mobile Password Management (Beta)
- QR Code Application Passwords (Beta)
Custom Login Page
Service Authorization (future)
SAML integration (future)

Auth Zimlet

Zextras Auth features a dedicated zimlet to manage all user-side credential and features, such as the EAS Mobile Password and Mobile App QR Codes.

Installing the Zextras Auth Zimlet

To deploy the Zextras Auth Zimlet, simply run zxsuite auth doDeployAuthZimlet as the zimbra user on any mailbox server of your infrastructure.

Zextras Auth Zimlet overview

The Zextras Auth Zimlet can be accessed from the "Zimlets" section of the Zimbra Web Client.

From here, the user can add new credentials ("New Password"), deleting existing ones and check on the status of all existing credentials.

Data Storage

All Zextras Auth data - including passwords and tokens - is saved in a local HSQL database.

All passwords, tokens and sensitive information are stored in hashed form using the SHA256 algorithm using auto-generated keys and no credential or sensitive information is ever stored cleartext.

Credential Management

Zextras Auth’s Credential Management system allows to create dedicated passwords for different services such as Exchange ActiveSyn devices, Mobile Applications (e.g. Team and Drive) or the Zimbra WebClient itself.

All credentials generated by Zextras Auth are not bound to Zimbra’s own password policies, neither in regards of the password’s character and length limit nor in regards of password expiration.

Credential Management CLI

All Credential Management features can be accessed through the zxsuite auth credential command, and its sub-commands:

zxsuite auth credential

Add/Update/Delete/List the account credentials

  add                      - Add a credential to the given account
                             zxsuite auth credential add {john@example.com} [attr1 value1 [attr2 value2...]]

  list                     - List all credentials for the given account
                             zxsuite auth credential list {john@example.com}

  update                   - List all mobile passwords for the given account
                             zxsuite auth credential update {john@example.com} {f51as} [attr1 value1 [attr2 value2...]]

  delete                   - Delete credentials with the given account and id
                             zxsuite auth credential delete {john@example.com} {f51as}

More information of the most common usages of this command can be found in the topic-specific sections of this page.

List existing Credentials

Any user can see the list of active Mobile Passwords in the Zextras Auth Zimlet. Each entry of the list displays the label of the password, its status, the service it is valid for and its creation date.

System Administrators, on the other hand, can view an extended list of all credentials active on an account by running zxsuite auth credential list user@domain.com, e.g.

zxsuite auth credential list admin

        values

                generated                                                   1
                created                                                     1603120043615
                label                                                       MobilePassword 1
                id                                                          5llDP
                services

                        service                                                             EAS
                hash                                                        W6q6hvf10TcPasPL+Oy96iHWO7SrjZBDHfaldt6ZxQk=
                enabled                                                     true
                algorithm                                                   SHA256

                generated                                                   0
                created                                                     1603120995372
                label                                                       My Label
                id                                                          Fr2jM
                services

                        service                                                             EAS
                hash                                                        +Crk6YcPL7IapCg6xfT6oXWP977uTeZdJTVQDQZd+Io=
                enabled                                                     true
                algorithm                                                   SHA256

For each credential, the following fields are displayed:

generated - whether the credential was randomly generated or not, 0 true and 1 means false
created - the credential’s creation timestamp
label - the credential’s label
id - the credential’s ID, required to edit credentials via zxsuite auth credential update
services - the services that the credential allows access to
hash - the hashed credential itself
enabled - whether the credential can be used to access all appropriate services or not
algorithm - the hashing algorithm used to store the credential

Editing a Credential

While usually the credential (password) itself cannot be edited, the System Administrator can edit its label and properties using the zxsuite auth credential update command.

e.g. to change the label of a Mobile Password belonging to the user john.doe@domain.com, whose id is Fr2jM to "New Label" run:

zxsuite auth credential update john.doe@domain.com Fr2jM label "New Label"`

The system will confirm the credential update and display all credential’s information:

Credential Fr2jM updated

        values
            generated                                               0
            created                                                 1603120995372
            label                                                   New Label
            id                                                      Fr2jM
            services

                    service                                                         EAS
            hash                                                    +Crk6YcPL7IapCg6xfT6oXWP977uTeZdJTVQDQZd+Io=
            enabled                                                 true
            algorithm                                               SHA256

See the "List existing Credentials" section above to find out how to obtain the credential’s ID

Mobile Password

Mobile Passwords are one of the credentials managed by Zextras Auth, which allows to set up multiple Mobile Passwords for each account.

Creating a new Mobile Password

A new Mobile Password can be created both from the Zextras Auth Zimlet and from the Zextras CLI.

Create a Mobile Password from the Zextras Auth Zimlet

To create a new Mobile Password, open the Zextras Auth Zimlet and click on "New Password":

Enter an easy to remember identifier for the password in the "Password Label" field and select "Text code" as the Password Type:

Click "Next".
The new Mobile Password will be displayed:

Mobile Passwords are randomly generated and cannot be displayed again after the creation is complete.

Click on "Done" to close the Zextras Auth window. An entry for the new Mobile Password is now visible in the "Active Passwords" list of the Zextras Auth Zimlet.

Create a Mobile Password from the Zextras CLI

To create a Mobile Password from the Zextras CLI, use the zxsuite auth credential command with the following attributes:

password: enter the password you wish to set as the Mobile Password
label: enter the label for the Mobile Password
service: use eas to set a Mobile Password

E.g. To add the gn89hg95hvmn59..] Mobile Password to the john.doe@domain.com account, labeled as "Personal Phone", run:

zxsuite auth credential add john.doe@domain.com password "gn89hg95hvmn59..]" label "Personal Phone" service eas

The system will confirm the success of the operation and display all the password’s information:name: value

Credential correctly added

        values
            generated                                               0
            created                                                 1603120995372
            label                                                   Personal Phone
            id                                                      Fr2jM
            services

                    service                                                         EAS
            hash                                                    +Crk6YcPL7IapCg6xfT6oXWP977uTeZdJTVQDQZd+Io=
            enabled                                                 true
            algorithm                                               SHA256
        text_data
            auth_method                                             password
            password                                                gn89hg95hvmn59..]
            user                                                    john.doe@domain.com

List existing Mobile Passwords

Specifically, all passwords valid for the "EAS" service are Mobile Passwords.

System Administrators, on the other hand, can view an extended list of all credentials, including Mobile Passwords,

Editing a Mobile Password

While a Mobile Password itself cannot be edited, the System Administrator can edit its label and properties using the zxsuite auth credential update command

Application Password (QR Code)

Zextras Auth can speed up and manage Application logins, such as those for the Team App and Drive App.

This is achieved through the creation of a QR Code in the Zimbra WebClient, which the user can then scan from the App’s login page to log in.

QR Codes are a one-time credential only, meaning that once generated it will grant access to the app until the relevant credential itself is deleted from the account. Once generated, the QR Code can only be viewed once.

QR Code Requirements

The QR Code Application Password feature requires the following properties to be set at domain level in order to be functional:

zimbraPublicServiceHostname
zimbraPublicServicePort
zimbraPublicServiceProtocol

Should one or more of the properties be unset, a notification will be delivered to the Admin reporting the affected domains and their missing properties.

Creating a new QR Code Credential

While, as all credentials, QR Codes can be created from both the Zextras Auth Zimlet and Zextras CLI, only the former allows the user to use the QR code itself so the latter will not be taken into consideration in this guide.

Creating a QR Code Credential from the Zextras Auth Zimlet

o create a new QR Code, open the Zextras Auth Zimlet and click on "New Password":

Enter an easy to remember identifier for the password in the "Password Label" field and select "QR code" as the Password Type:

Click "Next".
The new QR Code will be displayed:

QR Codes are randomly generated and cannot be displayed again after the creation is complete.

Click on "Done" to close the Zextras Auth window. An entry for the new Mobile Password is now visible in the "Active Passwords" list of the Zextras Auth Zimlet.

Service Credentials

Zextras Auth allows to create custom passwords for specific services using the zxsuite auth credential CLI seen above.

Such passwords can be used to restrict authentication to the following services:

Table 1. Services
Name	Description
EAS	Mobile Password
WebUI	Zextras Auth Login Page
WebAdminUI	Admin Console
MobileApp	Zextras Mobile Apps
ZmWebUI	Standard Zimbra Login Page
Dav	Zextras LDAP Address Book
Smtp	SMTP Authentication
Imap	IMAP Authentication
Pop3	POP3 Authentication

All of this services can be assigned to a credential through the services argument of the zxsuite auth credential command set. Multiple services can be entered at once through a comma separated list.

Sample Scenarios

Admin can enable only WebAccess (limiting SMTP)
Admin can enable IMAP without SMTP
Admin can enable IMAP/SMTP only for managed client (pre-setup without the user)
Admin can create SMTP password that are not enabled for Web/Soap/Imap access (e.g. for automation or external service)
Admin can create SOAP password that are not enabled for Web/Imap/SMTP access (e.g. for automation or external service)

Examples

zxsuite auth credential add user3@custom.zx password 'ABCdef123' service ZmWebUI,WebUI

user3@custom.zx/ABCdef123 can be used only for Web Access (both ClassicUI and Zextras Login Page)

zxsuite auth credential add user3@custom.zx password 'LocalClient' service imap,pop3

user3@custom.zx/LocalClient can be used only for IMAP and POP3 download (no SMTP)

zxsuite auth credential add user3@custom.zx password 'SMTP_Service_Credential' service smtp

user3@custom.zx/SMTP_Service_Credential can be used to enable SMTP for an external client

Forcing Auth-only logins

Auth can be forced to be the only authentication provider at global or domain level by setting the authZextrasAuthenticationOnly Zextras Config property to True, e.g.:

zxsuite config global set attribute authZextrasAuthenticationOnly value true
zxsuite config domain set domain.com attribute authZextrasAuthenticationOnly value true

Setting the property to false will revert back to the standard behavior, where both the Auth module and Zimbra’s own login provider are active.

Custom Login Page

The Auth module provides a custom Login Page that can be used instead of Zimbra’s own one.

The login page can be set at domain level and customized in terms of logo, background and favicon.

In order for this feature to work, the zimbraPublicServiceHostname and zimbraPublicServiceProtocol domain config keys must be properly set up.

Enabling the Login Page

To enable the Login Page for a domain, set the zimbraWebClientLoginURL config key to the Auth Login Page endpoint passing the domain={domain.tld} query string.

e.g. for the domain.tld domain

zmprov md domain.tld zimbraWebClientLoginURL /zx/login/page/?domain=domain.tld

To date, the Auth Login Page does not support any further Query Parameter (e.g. ?dev=1 or ?app=cal)

Customizing the Login Page

The Login Page can be customized through the use of the loginPage Auth CLI command.

Image File Locations and Sizes

Zextras Auth offers two options for image files used by the Login Page:

Remote File: the image is hosted on a public online resource and can be directly accessed.
- When using a remote file, use the full URL to the resource in CLI Commands, e.g. https://domain.tld/resources/logo.png
Local File: the image is hosted locally, in the /opt/zimbra/jetty/webapps/zimbra/public/
- When using a local file, use the relative path to the file from the /opt/zimbra/jetty/webapps/zimbra/ base path, e.g. /public/logo.png

The optimal size for a logo image is 320x80. Other sizes can be used but the logo image could be stretched or scaled resulting in poor quality. The aspect ratio of 4:1 should always be maintained.

While the optimal size for the background image depends on the resolution of the client’s screen, it’s stongly advised to avoid images smaller than the current standard monitor resolutions to avoid vertical or horizontal bars to be displayed on screens with a bigger resolution than the background image.

Editing the Background

The Login Page background can be set with the loginPage setBackgroundImage command at domain level:

(local) zxsuite auth loginPage setBackgroundImage domain domain.tld "/public/background.png"

(remote) zxsuite auth loginPage setBackgroundImage domain domain.tld "https://domain.tld/resources/background.png"

Editing the Logo

The Login Page logo can be set with the loginPage setLogo command at domain level:

(local) zxsuite auth loginPage setLogo domain domain.tld "/public/background.png"

(remote) zxsuite auth loginPage setLogo domain domain.tld "https://domain.tld/resources/background.png"

Editing the Favicon

The Login Page favicon can be set with the loginPage setFavicon command at domain level:

(local) zxsuite auth loginPage setFavicon domain domain.tld "/public/favicon.ico"

(remote) zxsuite auth loginPage setFavicon domain domain.tld "https://domain.tld/resources/favicon.ico"

Viewing the current configuration

The current Login Page settings for a domain can be viewed through the getConfig command:

zimbra@mail:~$ zxsuite auth loginPage getConfig domain domain.tld

        zimbraPublicServiceHostname                         mail.domain.tld
        loginPageBackgroundImage                            /public/background.jpg
        zimbraPublicServicePort                             443
        zimbraPublicServiceProtocol                         https
        zimbraDomainName                                    domain.tld
        publicUrl                                           https://mail.domain.tld
        loginPageLogo                                       /public/logo.png

CLI

Zextras Auth CLI

zxsuite auth

Table 2. Zextras Auth CLI
Name	Description	Usage
doStartService	start a given service	zxsuite auth doStartService [object Object]
doStopService	stop a given service	zxsuite auth doStopService [object Object]
getServices	show current status of all services for this module	zxsuite auth getServices
doRestartService	restart a given service	zxsuite auth doRestartService [object Object]
saml	saml configuration	zxsuite auth saml
credential	Add/Update/Delete/List the account credentials	zxsuite auth credential
loginPage	Manage login page attributes from CLI	zxsuite auth loginPage
policy	Manage policies from CLI	zxsuite auth policy
token	Manage token authorization and expiration	zxsuite auth token
doDeployAuthZimlet	Deploy ZeXtras Suite Auth zimlet to handle new credentials.	zxsuite auth doDeployAuthZimlet