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.
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 viazxsuite 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
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.
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,
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:
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
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 |