What is Zextras Auth
Zextras Auth is the Zextras Suite module that influences the process ofaccessing a Zextras instance from the Login Page onwards, including:
The access modality. Depending on the authentication backendsconfigured, the access mask changes, to allow user to provide theircredentials using any of the backends. This also is reflected in theZxAuth for users (Auth Zimlet).
Customisations. Define how the login page looks like. See dedicatedsection Custom Login Page for a list of customisableitems.
Zextras Auth allows to manage all the Authentication Strategies(user/pwd, SAML, 2FA, MobilePwd, QrCode) and Service Authorizationssupported by Zextras.
This section is divided in three main parts and organised as follows.Immediately below, you can find the description of all supportedauthentication methods; the next two sections are dedicated toadministration tasks, which requireprivileged access and are mostly carried out from the CLI, andeveryday’s task, which can be carried outfrom the Web GUI by both administrators and users,respectively. Finally, the list of all CLI commands is given as a reference, with link to each command.
Supported Authentication Methods
Zextras Auth supports the following backends:
Self service credentials management
Mobile password management
Application password
Custom login page
SAML integration
2FA Authentication using OTP token
Credential Management by CLI
Self Service Credentials Management
Self-service credential management allows every user to create newpasswords and QR codes for third-parties—for example team members,personal assistants—accessing her/his email account and ZextrasApplications from mobile devices.
QR Codes in particular can be used to access Zextras Apps, currentlyTeam and Drive.
More information and step by step guidelines can be found in SectionZxAuth for users (Auth Zimlet).
Custom Login Page
All Zextras functionality can be accessed upon login from the loginpage of Zextras, which can be customised in several parts, for exampleto add the company’s logo or other elements of the company’s corporateidentity.
This feature is carried out from the CLI and therefore requiresadministrator privileges; more information and guidelines in sectionCustom Login Page.
SAML
The Security Assertion Markup Language (SAML) is an XML-based openstandard data format for exchanging authentication information. Itenables web-based authentication and authorization scenarios includingcross-domain Single Sign-On (SSO), which allows the use of the samecredentials to access different applications.
SAML implementation in Zextras relies on an external IDentity Provider(IDP), to which a user identifies; the IDP then passes authorizationcredentials to a service providers (SP). SAML authentication is theprocess of verifying the user’s identity and credentials. In ZextrasSuite, SAML requires little configuration, because an administrator cangenerate the SAML configuration by importing SAML metadata from the ISP.Each domain can have a different SAML endpoint and both SDP and IDP SAMLauthentication is supported.
These are the key concepts of SAML authentication:
- Service Provider
(SP) is the entity providing the service.
- Identity Provider
(IdP) is the entity providing the identities.
- SAML Request
is generated by the Service Provider to “request” an authentication.
- SAML Response
is generated by the Identity Provider and contains the assertion ofthe authenticated user.
Moreover, the Assertion Consumer Service (ACS) endpoint is a location towhich the SSO tokens are sent, according to partner requirements.
Directions on how to configure SAML and integrate other applicationsin Zextras Suite is described in Section Setting up SAML Configuration.
Two Factor Authentication
Two Factor Authentication (usually spelled as 2FA) adds a securitylayer to the login phase, making unwanted accesses less likely to takeplace. In Zextras, this additional layer is given by an One TimePassword (OTP), which can be read as a QR code on mobile devices.
When 2FA is configured on a Zextras domain, it is mandatory to have anOTP to be able to login: providing only username and password will fail.Moreover, the attribute zimbraAuthMech must be configured on thedomain with for 2FA to work properly.
2FA applies only to those protocols or apps supporting it, for exampleHTTP and HTTPS but not to IMAP and SMTP, and can be configured at eitherdevice, IP, or IP range level, by means of the trusted_device ortrusted_ip parameter. When an IP or IP range is trusted, 2FA will besuccessful for any login originating from there, while thetrusted_device requires that the same browser or app be used,otherwise it will fail: if a 2FA login is carried out on Chrome,accessing the same page with Firefox will require a new login.
In order to use the OTP, a domain must be configured (seeQR Code Requirements) by the site admin, while users can configureit using the Auth Zimlet.
See also
Community Article
https://community.zextras.com/improve-the-security-using-zextras-2fa/
This article showcases a few deployment scenarios of 2FA in Zextrasand describes how Administrators can take advantage of sucharchitecture.
ZxAuth for Admins
This section is dedicated to administrators and the activities they cancarry out to manage and maintain Zextras Auth. Here administrators canfind the requirements for the various authentication methods, then theinstallation instructions. Credential management follows, with theoption to customise the login page at the end.
Requirements
QR Code Requirements
The QR Code Application Password feature requires the followingproperties to be set at domain level in order to be functional:
zimbraPublicServiceHostnamezimbraPublicServicePortzimbraPublicServiceProtocol
Should one or more of the properties be unset, a notification will bedelivered to the Admin reporting the affected domains and their missingproperties.
2FA Requirements
In order to properly have 2FA set up, the zimbraAuthMech attributebust be configured at domain level:
zmprov modifyDomain example.com zimbraAuthMech custom:zx
To enable 2FA it is also necessary to:
Enter the addresses of all mailbox and MTAs as
ZimbraMailTrustedIp, using the command:zmprov mcf +zimbramailtrustedip IP_ADDRESS
A
trusted ip rangemust be defined for all servicesFor all services the
ip_can_changeattribute must be validated ontrueand2fa_policy = 1
Warning
2FA requires a specific zimbraAuthMech and this makes itnot compatible with other mechanism such as ldap, ad or kerberos5
SAML Requirements
Before enabling SAML login, it is necessary to modify the ZextrasBackend processing, because these header attributes are required tocompose the complete URL request: Protocol X and X-Port.
The files affected by this change are the templates:
nginx.conf.web.http.default.templatenginx.conf.web.http.templatenginx.conf.web.https.default.templatenginx.conf.web.https.template
In each of them, the location ^~ /zx/ code should be changed.
location ^~ /zx/ { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Host $http_host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Port $server_port; proxy_pass ${web.upstream.zx}; }
Installing the Zextras Auth Zimlet
To deploy the Zextras Auth Zimlet, simply run zxsuite authdoDeployAuthZimlet as the zimbra user on any mailbox server of yourinfrastructure.
Custom Login Page
The Auth module provides the ability to customise the Login Page as itis seen by other user.
The login page can be set at domain level and customized in terms oftitle, logo, background and favicon.
Enabling the Login Page
To enable the Login Page for a domain (we use example.com), set thezimbraWebClientLoginURL and zimbraWebClientLogoutURLconfiguration keys. You can do so from the GUI by adding the followingtwo values:
Web client login redirect URL: /zx/login/page/?domain=example.comWeb client logout redirect URL: /zx/auth/logout/
The same action can be done by using the following CLI command, whichconfigures also the authentication method (zimbraAuthMech):
zmprov md example.com zimbraAuthMech custom:zx zimbraWebClientLoginURL /zx/login/page/?domain=example.com zimbraWebClientLogoutURL /zx/auth/logout/
Customizing the Login Page
The Login Page can be customized through the use of the loginPageAuth CLI command.
Image File Locations and Sizes
Zextras Auth offers two options for custom image files used by the LoginPage, either by embedding remote image files or hosting them locally.Image files can be used for logo, background, and favicon.
Remote File
The image is available on a public online resource (like, e.g.,a corporate server or a hosting service) and can be directlyaccessed. When adopting this approach, use the full URL to theresource in the CLI command, for example:https://www.example.com/resources/logo.png
Hint
This is the preferred alternative.
Local File
The image is hosted locally and must be stored in a directoryunder /opt/zimbra/jetty/webapps/zimbra/public/. Whenconfiguring it, the relative path to the file from the/opt/zimbra/jetty/webapps/zimbra/ base path must be used. Ifthe file is saved as/opt/zimbra/jetty/webapps/zimbra/public/logo.png, then use/public/logo.png
The optimal size for a logo image is 320x80 pixels. Other sizes can beused but the logo image could be stretched or scaled resulting in poorquality. The aspect ratio of 4:1 should always be maintained.
While the optimal size for the background image depends on theresolution of the client’s screen, it’s stongly advised to avoid imagessmaller than the current standard monitor resolutions to avoid verticalor horizontal bars to be displayed on screens with a bigger resolutionthan the background image.
Login Page Title
The login page title can be modified by using either of the followingcommands:
Global level by using zxsuite auth loginPage setTitle global
zxsuite auth loginPage setTitle global 'My Custom Login Page'
Domain level by using zxsuite auth loginPage setTitledomain
zxsuite auth loginPage setTitle domain example.com 'My Custom Login Page'
Viewing the current configuration
The current Login Page settings for a domain can be viewed by using thezxsuite auth loginPage getConfigdomain command:
$ zxsuite auth loginPage getConfig domain example.com zimbraPublicServiceHostname mail.example.com loginPageBackgroundImage /public/background.jpg zimbraPublicServicePort 443 zimbraPublicServiceProtocol https zimbraDomainName example.com publicUrl https://mail.example.com loginPageLogo /public/logo.png
Setting up Policy Management for 2FA
Zextras Auth introduced the second factor as part of the serviceauthentication strategy. At domain or at global level, each servicecan either:
be enabled or disabled for the 2FA
have its own Trusted Networks
When enabled, the connection can be established only if the sourceis trusted, which means that the connection originates either from atrusted network, manually configured by the admin for the service,or from a previously trusted IP or device, depending on the 2FApolicy configured for the service.
If none of the above conditions holds, the service must ask for theOTP, used as the second factor. If the service does not support thesecond factor, or is not able to interact with the user for it, theauthentication process fails. For example, IMAP is a service notsupporting OTP and therefore 2FA can not be used with it. Otherwise,when the user provides a valid OTP, the current user’s device and IPare stored in the Trusted Device table
Moreover, depending on the service policy, the connection should bevalid even if the IP has been trusted by another service.
2FA Policy Management is a rather advanced technique which avoids theuse of OTP in all cases when an authentication request is receivedfrom a device that is already in the Trusted Networks or TrustedDevices tables.
To set up and manage 2FA Policies, several CLI commands are available.
Display policies
The command zxsuite auth policy list returns the list of 2FAby domain, with option to filter specific services.
Example
zxsuite auth policy list domain example.com service EASShows 2FA setting for domain example.com and for serviceEAS.
Example
zxsuite auth policy list globalDisplay for which services 2FA can be enabled. As a bonus, theoutput contains a lists of all supporter services, whichfall in:
standard protocols or technologies (CLI, DAV, EAS, IMAP,POP3, and SMTP)
related to Zextras Zimbra components (MobileApp, WebAdminUI,WebUI, ZmWebUI).
Reference: policy list domain policy list global
Manage policies
The command zxsuite auth policy set enables ordisables a service and accepts the following three optionalparameters:
ip_can_changeThis attribute allows the server to deny connection requestscoming from an IP other than the one used during theauthentication. As an example, suppose that authenticationwas successfully carried out from a device with IP192.168.1.72 and for any reason the IP of the device changes(e.g., a laptop moved to a different subnet). If
ip_can_changeis set to true, then the device isstill authenticated and connections are allowed, otherwise,ifip_can_changeis set to false, authentication isinvalidated and no connection is allowed for the device untila new authentication.trusted_ip_rangeIt defines the Trusted Networks, a set of IP rangesconfigured for each service (like e.g., DAV, EAS, SMTP, andmore). If a connection comes from an IP in the TrustedNetworks, the authentication will not require the secondfactor validation, independently from the policy specified,but users will be authenticated with username and password.
2fa_policyThis parameter determines how 2FA policies are enforced foreach service and takes one of these three integer values:
0 (no_2fa): 2FA authentication is disabled for theservice
1 (ip_2fa): Trust the IP from which the connectionstarts. All the subsequent logins from the same IP will notrequire the second factor.
2 (device_2fa): Trust the device from which theconnection starts. All the subsequent logins from the samedevice (that is, same browser or Mobile App) will notrequire the second factor.
These parameters are supported by all services.
Reference: policy set Cli domain policy set Cli global and following commands forthe services listed in the Display policy panel.
Manage expiration time
Two commands help to check and define the expiration time oftrusted devices.
zxsuite auth policy TrustedDevice getExpiration
Check the current policy for expiration time, i.e., for howlong a device will be considered as trusted. The number ofdays is returned. The command acts at domain and globallevel.
Example
zxsuite auth policy trustedDevice getExpiration domain example.comShow how many days is the expiration time for example.com.
Example
zxsuite auth policy trustedDevice getExpiration globalShow how many days is the expiration time for the wholeinfrastructure.
Reference: trustedDevice getExpiration domain policy trustedDevice getExpirationglobal
zxsuite auth policy TrustedDevice setExpiration
Define the current policy for expiration time, i.e., for howlong a device will be considered as trusted. The number ofdays is required. The command acts at domain and globallevel.
Example
zxsuite auth policy trustedDevice setExpiration domain example.com 20Defines the expiration time for domain example.com to 20 days.
Reference: trustedDevice setExpiration_domain trustedDevice setExpiration global
Setting up SAML Configuration
To integrate a SAML application into Zextras, you need to configure theSAML IDP (IDentity Provider) using the Zextras SAML SP data. In oursample scenario, we want to add SAML authentication to our domainexample.com, accessible at SP_URL.
The SAML configuration is carried out at an IDP provider, then importedin Zextras Suite using a dedicated command.
The most important configuration options are the following. You shouldconfigure them on the SAML IDP side.
sp.entityidhttps://SP_URL/zx/auth/samlMetadata?domain=example.com
sp.assertion_consumer_service.urlhttps://SP_URL/zx/auth/saml
sp.nameidformaturn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
In order to validate against Zextras, make sure that the Name of theattribute that is used as NameID is set to mailPrimaryAddress.
You can now integrate a SAML application in Zextras in two ways, eitherautomatic or manual. The following sections describe each method indetail.
Import SAML Configuration Automatically
The SAML IDP provides a URL from which to download the configuration;assuming that this URL ishttps://my-saml-provider.org/simplesaml/saml/idp/metadata.php, you canimport the configuration using the command:
zxsuite auth saml import example.com URL https://my-saml-provider.org/simplesaml/saml/idp/metadata.php
Note
The URL supplied by the SAML IDP for an unsecured connectionmay be slight different from the previous one, like in our example.
zxsuite auth saml import example.com url https://localidp.local.loc/app/xxxxxxxxxxxxxxx/sso/saml/metadata allow_unsecure true
You are now DONE! You can see the LOGIN SAML button on the login page.
By clicking it, you will be redirect to the SAML IDP login page.
Import SAML Configuration Manually
If you need to manually edit the SAML configuration, you need tofollow this 4-step procedure. In a nutshell, you need to export thedefault SAML settings, modify them, then save and import them back.
Step 1. Export the default SAML settings
In order to export the default SAML setting, use
zxsuite auth saml get example.com export_to /tmp/saml.json
Step 2. Modify /tmp/saml.json
Open the resulting file /tmp/saml.json in any editor and modifythe requested attributes:
entityidassertion_consumer_service.urlnameidformat
Step 3. Check modified /tmp/saml.json
The /tmp/saml.json` file should look similar to thisone:
Simple saml.json file
{ "sp.entityid":"https://SP_URL/zx/auth/samlMetadata?domain=example.com", "sp.assertion_consumer_service.url":"https://SP_URL/zx/auth/saml", "sp.nameidformat":"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "sp.assertion_consumer_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST", "sp.single_logout_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect", "sp.single_logout_service.url":"https://SP_URL/?loginOp=logout", "sp.x509cert":"aabbcc", "idp.entityid":"https://IDP-URL/simplesamlphp/saml2/idp/metadata.php", "idp.x509cert":"xxyyzz", "idp.single_sign_on_service.url":"https://IDP-URL/simplesamlphp/saml2/idp/SSOService.php", "idp.single_sign_on_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect", "idp.single_logout_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect", "organization.name":"ACME, INC.", "organization.displayname":"Example", "organization.url":"https://www.example.com/", "security.requested_authncontextcomparison":"exact", "security.signature_algorithm":"http://www.w3.org/2000/09/xmldsig#rsa sha1", "security.want_nameid_encrypted":"false", "security.want_assertions_encrypted":"false", "security.want_assertions_signed":"false","debug":"true", "security.want_messages_signed":"false", "security.authnrequest_signed":"false", "security.want_xml_validation":"true", "security.logoutrequest_signed":"false" "security.logoutresponse_signed":"false",}
Values appearing in the above code excerpt are taken from theexample in the previous section. Certificates must be valid,they are omitted for clarity.
Step 4. Save the changes
The final step is to save the changes made to the file and importit into Zextras Suite using the command:
zxsuite auth saml import example.com file /tmp/saml.json
Hint
It is also possible to view or edit single attributesby using the zxsuite auth saml get and zxsuite auth samlset command options.
Configure SAML Logout
Some SAML IDP provider require that also the logout procedure besigned. In case you had already configured SAML, you can proceed in asimilar fashion as described in the previous section: export the configuration,modify it, then import it again.
Here we show how to add signed logout to the configuration used in theprevious section, by modifying the configuration filesaml.json presented there.
Note
We also report below the configuration file presented in theprevious section, modified according to the procedure describedbelow and with the lines interested by the changes highlighted. Theline numbers are those
First, you need to configure the SAML IDP logout service URL (line7, sp.single_logout_service.url). We use Okta as example SAML IDP provider, so the URL will besimilar to https://mycompany.okta.com/app/test/app_id/slo/saml.
Then, configure also the service provider’s certificate,sp.x509cert (line 8), which however should be alreadypresent.
At this point, you should be done and you can import the modifiedconfiguration file.
However, in case the SAMP IDP requires that also the requests besigned, or in case to sign the requests for security reasons, pleasefollow these additional steps.
Create a new X509 certificate and register it to the SAML IDP. Youcan use a command similar to the following one to create one withopenssl
# openssl req -x509 -sha256 -nodes -days 365 \-newkey rsa:2048 -keyout privateKey.key -out certificate.crt
Add to the configuration file the certificate assp.x509cert and the private key as sp.privatekey(lines 8 and 9 respectively)
Enable the signature generation, that is, setsecurity.logoutrequest_signed to
true(line 30)You can also optionally enable the signature for the login request,by setting security.authnrequest_signed
to true(line32)
saml.json file with signed logout and requests.
1{ 2 "sp.entityid":"https://SP_URL/zx/auth/samlMetadata?domain=example.com", 3 "sp.assertion_consumer_service.url":"https://SP_URL/zx/auth/saml", 4 "sp.nameidformat":"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", 5 "sp.assertion_consumer_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST", 6 "sp.single_logout_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect", 7 "sp.single_logout_service.url":"https://mycompany.okta.com/app/test/app_id/slo/saml", 8 "sp.x509cert":"aabbcc", 9 "sp.privatekey":"ddeeff",1011 "idp.entityid":"https://IDP-URL/simplesamlphp/saml2/idp/metadata.php",12 "idp.x509cert":"xxyyzz",13 "idp.single_sign_on_service.url":"https://IDP-URL/simplesamlphp/saml2/idp/SSOService.php",14 "idp.single_sign_on_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",15 "idp.single_logout_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",1617 "organization.name":"ACME, INC.",18 "organization.displayname":"Example",19 "organization.url":"https://www.example.com/",2021 "security.requested_authncontextcomparison":"exact",22 "security.signature_algorithm":"http://www.w3.org/2000/09/xmldsig#rsa sha1",23 "security.want_nameid_encrypted":"false",24 "security.want_assertions_encrypted":"false",25 "security.want_assertions_signed":"false","debug":"true",26 "security.want_messages_signed":"false",27 "security.authnrequest_signed":"false",28 "security.want_xml_validation":"true",29 "security.logoutrequest_signed":"true"30 "security.logoutresponse_signed":"true",31 "security.authnrequest_signed":"true",32}
Access a Service Using SAML
Once SAML authentication has been properly configured on both the SPand IDP sides, it is possible to access to a Suite resource usingdifferent modalities:
Login to the IDP portal and click on the resource you want toaccess.
Directly go to the service’s web page and click theSAML LOGIN button that appears near theusername and password fields
Note
The label on the button might slight differ, depending onIPD and configuration.
Use the direct link to the SAML authentication of the service. Forexample, given a Suite installation (the Service) located atmail.example.com, and provided you are already authenticated tothe IDP, it is possible to access the mailbox by using the linkhttps://mail.example.com/zx/auth/startSamlWorkflow?redirectUrl=https://mail.example.com/suite/mails
Hint
By replacing the URL after the
redirectUrlit ispossible to allow direct access to other Carbonio components,for example:https://mail.example.com/zx/auth/startSamlWorkflow?redirectUrl=https://mail.example.com/suite/fileswill open the Carbonio Files component.
Temporary Auth Link
A typical user-management task that an administrator needs to carryout is to allow the first access to the company’s infrastructure to anew colleague or employee.
When 2FA is enabled on the mailstore, a new user can not loginimmediately, therefore the solution is to provide a temporary link(auth link) that allows the user to access and configure 2FA.
Administrators can generate a auth link easily from theAdministration GUI:
In the user’s General Information section, in box calledTemporary link, click the Create a temporary link button
A URL link will be shown in an overlay window and can be copied byclicking on the accompanying button
The link can then be sent to the new user
The user must access the mailbox within 5 minutes before the linkexpires
ZxAuth for users (Auth Zimlet)
Zextras Auth features a dedicated zimlet (see Fig. 10)to manage all user-side credential and features, such as the accountand EAS Mobile Passwords, Mobile App QR Codes, and OTP forTwo Factor Authentication.
Zextras Auth Zimlet overview
The Zextras Auth Zimlet can be accessed from the “Zimlets” section ofthe Zimbra Web Client. Users do not need any CLI access to use theZextras Auth.
The creation of a new credential allows to give access to the account,possibly including the Zextras Mobile Apps, to other persons withouthaving to share the personal credentials.
From the zimlet, the user can:
Change the password of the current logged in user
Add new credentials in the dedicated pages, accessible byclicking Exchange ActiveSync, Mobile Apps, or OTPAuthentication
Check the status and other information for all ExchangeActiveSync and Mobile Apps credential created. In each section,entries in the list display the label of the password, its status,the service it is valid for, and its creation date.
Check the status and other information for every One TimePassword created. Here, each entry shows a description, its status,the failed attempts, and its creation date.
Manage the 2FA access. Each user can decide whether to enforceaccess using 2FA, unless its use has been enabled or disabled atCOS, domain, or global level.
Delete any credential created
Important
Users can in no case modify their assigned credentials,change the password of credentials they generate, or modify anyproperty of the credential. Limited editing of a credential isstrictly limited to the administrators.
In the remainder of this section, we give an overview of the variouspossibilities to create new credentials and provide instruction to addor delete them them.
Change Password
In order to change password, access the Auth zimlet and click changepassword. Here, you need to provide the current password, then entertwice a new one.
Hint
Make sure you use a robust password, which includeslowercase and uppercase letters, numbers, characters, and is atleast *8 characters long.
To save the new password, click the blue CHANGEPASSWORD button.
Create New Credentials: EAS
To create a new Password for EAS service, open theZextras Auth Zimlet and click Exchange ActiveSync, thenNEW AUTHENTICATION +.
Here, enter an easy to remember identifier for the password in theAuthentication description field.
Then click CREATE PASSWORD: the new Mobile Passwordwill be displayed.
Finally, click the COPY PASSWORD button to copythe password to the clipboard.
Warning
Mobile Passwords are randomly generated and cannot bedisplayed again after the creation is complete.
Click DONE to close the Zextras Auth window. An entryfor the new Mobile Password is now visible in the Active Passwordslist of the Zextras Auth Zimlet.
Create New Credentials: Mobile Apps
Zextras Auth can speed up and manage Zextras Application logins, suchas those for the Team Mobile App andDrive Mobile App.
This is achieved through the creation of a QR Code, which the user canthen scan from the App’s login page to log in. The procedure is verysimilar to the one described in the previous section.
Warning
QR Codes are a one-time credential only, meaning thatonce generated it will grant access to the app until the relevantcredential itself is deleted from the account. Once generated, theQR Code can only be viewed once.
In order to create a new QR Code for Mobile Application, open theZextras Auth Zimlet and click Mobile Apps, thenNEW AUTHENTICATION +.
Here, enter an easy to remember identifier for the password in theAuthentication description.
Click CREATE PASSWORD and the new QR code for MobileApplication will be displayed. You can use the Zextras mobile app toframe the code and grant access to the app.
Warning
QR Codes are randomly generated and cannot be displayedagain after the creation is complete.
Click on DONE to close the Zextras Auth window. Anentry for the new Mobile Application is now visible in the ActivePasswords list of the Zextras Auth Zimlet.
Create New Credentials: OTP
In order to create a new One Time Password access, open the ZextrasAuth Zimlet and click OTP Authentication, thenNEW OTP + to open a dialog in which you have toenter a unique label to identify the OTP.
You will be presented with the QR code and a list of PIN codes to beused for authentication.
Next, click the PRINT PIN CODES button to print thecodes on paper or to a file. The printed document includes all thecodes, the username/e-mail address for which they are valid andinstructions to use them.
Warning
QR codes and their associated PINs are randomly generatedand cannot be displayed again after the creation is complete.
Finally, click DONE to close the Zextras Authwindow. An entry for the new OTP entry will be shown in the list.
Note
The Description is automatically created using the emailaddress to which it is associated.
Delete Credentials
In order to delete a credential, simply select it from the list ofActive passwords or OTPs, and click the DELETE xbutton:
Click YES to confirm the removal of the credential.
Credential Management
Within Zextras Suite, a credential is something that allows access toone of its services or modules.
Zextras Suite Auth’s Credential Management system allows to create dedicatedpasswords for different services such as Exchange ActiveSync devices,Mobile Applications (e.g., Team and Drive) or the Zimbra WebClientit*elf.
It is also possible to share the access to a service with othercolleagues, team members, or even third-party persons by simply creatinga new authentication means (e.g., a QR code for mobile access) for theservice, without the need to share the password. Once the access forthese persons is not needed anymore, it suffices to delete theauthentication means to revoke the access.
This also implies, as an additional advantage, that users are able todecide who can have access to the same services they use, providing ahigh level of granularity also at user level.
In the remainder of this section, we show a few common and relevanttasks that an administrator can carry out.
Services supported
Zextras Auth allows to create or update custom passwords for thefollowing services:
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 |
Administrators can combine these services to set up multiple basic tocomplex scenarios, including:
enable only WebAccess
enable IMAP without SMTP
enable IMAP/SMTP only for managed client (pre-setup without theuser)
create SMTP password that are not enabled for Web/Soap/Imap access,to be used for automation or external services
See the next section for a few examples.
Add new credentials
Administrators can set the password of any user account on the commandline when they create the credentials. In no other circ*mstancesthey have access to the password, not even for changing it.
New credentials for each of the active authentication services can beadded using the zxsuite auth credential add command:
# zxsuite auth credential add john@example.com [param VALUE[,VALUE]]
By default, this command uses EAS (Exchange ActiveSync) asservice. Multiple services can be added as comma separated list.Some examples follow, the first includes a commented output.
create a password and a label for user john@example.com who canaccess service eas (mobile password).
# zxsuite auth credential add john@example.com password 'easpass' label "Smartphone" service easCredential correctly addedlist generated 0 created 1620892109473 label Smartphone id aKcLK services EAS hash 6Fs6knbW1+fJmWMB1nKoCgLFPy+IGsuZGtmkW0NzV4A= enabled true algorithm SHA256text_data auth_method password password easpass user john@example.com
generated- whether the credential was randomly generated or not,0 true and 1 means falsecreated- the creation timestamplabel- the label, useful to remember the purpose or user of thecredentialsid- the unique ID, which is mandatory to edit or update thecredentialsservices- the services for which access is allowedhash- the hashed credential itselfenabled- whether the credential can be actually used or notalgorithm- the hashing algorithm usedpassword- the password assigned or randomly generated. Asmentioned, this is the only occasion that the administrator cansee a user’s password
Create a password for jane@example.com, that can be used only for WebAccess (both ClassicUI and Zextras Login Page)
# zxsuite auth credential add jane@example.com password \ 'SecretPassword!' label "Web access" service ZmWebUI,WebUI
Create a password for alice@example.com that can be used only forIMAP and POP3 download (no SMTP)
# zxsuite auth credential add alice@example.com password \ 'LocalClient' service imap,pop3
Create a password for bob@example.com/SMTP_Service_Credential can beused to enable SMTP for an external client
# zxsuite auth credential add bob@example.com password \'SMTP_Service_Credential' service smtp
An important parameter is qrcode, to create a new QR code to beused by mobile devices, provided QR code support has beenenabled. Used together with the --json switch,it will show the QR code’s payload as well. An example is:
# zxsuite auth credential add charles@example.com password \ 'SMTP_Service_Credential' qrcode true service smtp
List existing Credentials
System Administrators can view an extended list of all credentialsactive on an account by using the zxsuite auth credential list command:
# zxsuite auth credential list john@example.com
Note
The zxsuite auth credential list does not give access to theuser’s password.
The output of this command can be quite long, because it shows all thecredentials configured on an account, including a number of additionalinformation. Let’s see an example and which are the relevantinformation:
# zxsuite auth credential list john@example.com values generated 1 created Tue 04 May 2021 at 08:39:41 label MobilePassword 1 id 5llDP services SMTP,IMAP hash W6q6hvf10TcPasPL+Oy96iHWO7SrjZBDHfaldt6ZxQk= enabled true algorithm SHA256 generated 0 created Wed 05 May 2021 at 17:53:38 label My Label id Fr2jM services EAS hash +Crk6YcPL7IapCg6xfT6oXWP977uTeZdJTVQDQZd+Io= enabled true algorithm SHA256
is the id of the credentials, which is unique and necessary toedit the credential—see next section
the service(s) for which the credential is valid.
Editing a Credential
While usually the credential (password) itself cannot be edited, theSystem Administrator can update its label and properties, includingthe services for which it is valid, by using the zxsuite authcredential update command:
# zxsuite auth credential update *john@example.com* *f51as* \ [param VALUE[,VALUE]]
Building on the above example, we want to change the label of credentialid Fr2jM belonging to user john@example.com. This can be achievedwith:
# zxsuite auth credential update john@example.com Fr2jM label "New Label"
The successful credential update will be displayed as output of theprevious command, reporting all credential’s properties:
Credential Fr2jM updated values generated 0 created Wed 05 May 2021 at 17:53:38 label New Label id Fr2jM services EAS hash +Crk6YcPL7IapCg6xfT6oXWP977uTeZdJTVQDQZd+Io= enabled true algorithm SHA256
Zextras Auth CLI
This section contains the index of all zxsuite auth commands. Fullreference can be found in the dedicated sectionZxAuth CLI Commands.
credential add credential delete credential list credential update doDeployAuthZimlet doRestartService doStartService doStopService enforce2FA get account enforce2FA get cos enforce2FA set account enforce2FA set cos getServices loginPage getBackgroundImage domain loginPage getBackgroundImage global loginPage getColorPalette domain loginPage getColorPalette global loginPage getConfig domain loginPage getConfig global loginPage getFavicon domain loginPage getFavicon global loginPage getLogo domain loginPage getLogo global loginPage getSkinLogoAppBanner domain loginPage getSkinLogoAppBanner global loginPage getSkinLogoURL domain loginPage getSkinLogoURL global loginPage getTitle domain loginPage getTitle global loginPage setBackgroundImage domain loginPage setBackgroundImage global loginPage setColorPalette domain loginPage setColorPalette global loginPage setFavicon domain loginPage setFavicon global loginPage setLogo domain loginPage setLogo global loginPage setSkinLogoAppBanner domain loginPage setSkinLogoAppBanner global loginPage setSkinLogoURL domain loginPage setSkinLogoURL global loginPage setTitle domain loginPage setTitle global policy list domain policy list global policy set Cli domain policy set Cli global policy set Dav domain policy set Dav global policy set EAS domain policy set EAS global policy set Imap domain policy set Imap global policy set MobileApp domain policy set MobileApp global policy set Pop3 domain policy set Pop3 global policy set Smtp domain policy set Smtp global policy set WebAdminUI domain policy set WebAdminUI global policy set WebUI domain policy set WebUI global policy set ZmWebUI domain policy set ZmWebUI global policy trustedDevice getExpiration domain policy trustedDevice getExpiration global policy trustedDevice setExpiration_domain policy trustedDevice setExpiration global saml delete saml get saml import saml update saml validate token invalidate token list totp delete totp generate totp list trustedDevice delete trustedDevice list
